1Test::PostgreSQL(3pm) User Contributed Perl DocumentationTest::PostgreSQL(3pm)
2
6 Test::PostgreSQL - PostgreSQL runner for tests
7
9 use DBI;
10 use Test::PostgreSQL;
11 use Test::More;
12 # optionally
14 # (if not already set at shell):
15 #
16 # $ENV{POSTGRES_HOME} = '/path/to/my/pgsql/installation';
17 my $pgsql = eval { Test::PostgreSQL->new() }
19 or plan skip_all => $@;
20 plan tests => XXX;
22 my $dbh = DBI->connect($pgsql->dsn);
24
26 "Test::PostgreSQL" automatically setups a PostgreSQL instance in a
27 temporary directory, and destroys it when the perl script exits.
28 This module is a fork of Test::postgresql, which was abandoned by its
30 author several years ago.
31
33 "Test::PostgreSQL" object has the following attributes, overridable by
34 passing corresponding argument to constructor:
35 dbname
37 Database name to use in this "Test::PostgreSQL" instance. Default is
38 "test".
39 dbowner
41 Database owner user name. Default is "postgres".
42 host
44 Host name or IP address to use for PostgreSQL instance connections.
45 Default is 127.0.0.1.
46 base_dir
48 Base directory under which the PostgreSQL instance is being created.
49 The property can be passed as a parameter to the constructor, in which
50 case the directory will not be removed at exit.
51 base_port
53 Connection port number to start with. If the port is already used we
54 will increment the value and try again.
55 Default: 15432.
57 unix_socket
59 Whether to only connect via UNIX sockets; if false (the default),
60 connections can occur via localhost. [This changes the "dsn" returned
61 to only give the UNIX socket directory, and avoids any issues with
62 conflicting TCP ports on localhost.]
63 socket_dir
65 Unix socket directory to use if "unix_socket" is true. Default is
66 "$base_dir/tmp".
67 pg_ctl
69 Path to "pg_ctl" program which is part of the PostgreSQL distribution.
70 Starting with PostgreSQL version 9.0 "pg_ctl" can be used to start/stop
72 postgres without having to use fork/pipe and will be chosen
73 automatically if "pg_ctl" is not set but the program is found and the
74 version is recent enough.
75 NOTE: do NOT use this with PostgreSQL versions prior to version 9.0.
77 By default we will try to find "pg_ctl" in PostgresSQL directory.
79 initdb
81 Path to "initdb" program which is part of the PostreSQL distribution.
82 Default is to try and find it in PostgreSQL directory.
83 initdb_args
85 Arguments to pass to "initdb" program when creating a new PostgreSQL
86 database cluster for Test::PostgreSQL session.
87 Defaults to "-U postgres -A trust". See "dbowner".
89 extra_initdb_args
91 Extra args to be appended to "initdb_args". Default is empty.
92 pg_config
94 Configuration to place in "$base_dir/data/postgresql.conf". Use this to
95 override PostgreSQL configuration defaults, e.g. to speed up PostgreSQL
96 database init and seeding one might use something like this:
97 my $pgsql = Test::PostgreSQL->new(
99 pg_config => q|
100 # foo baroo mymse throbbozongo
101 fsync = off
102 synchronous_commit = off
103 full_page_writes = off
104 bgwriter_lru_maxpages = 0
105 shared_buffers = 512MB
106 effective_cache_size = 512MB
107 work_mem = 100MB
108 |);
109 postmaster
111 Path to "postmaster" which is part of the PostgreSQL distribution. If
112 not set, the programs are automatically searched by looking up $PATH
113 and other prefixed directories. Since "postmaster" is deprecated in
114 newer PostgreSQL versions "postgres" is used in preference to
115 "postmaster".
116 postmaster_args
118 Defaults to "-h 127.0.0.1 -F".
119 extra_postmaster_args
121 Extra args to be appended to "postmaster_args". Default is empty.
122 psql
124 Path to "psql" client which is part of the PostgreSQL distribution.
125 "psql" can be used to run SQL scripts against the temporary database
127 created by "new":
128 my $pgsql = Test::PostgreSQL->new();
130 my $psql = $pgsql->psql;
131 my $out = `$psql -f /path/to/script.sql 2>&1`;
133 die "Error executing script.sql: $out" unless $? == 0;
135 psql_args
137 Command line arguments necessary for "psql" to connect to the correct
138 PostgreSQL instance.
139 Defaults to "-U postgres -d test -h 127.0.0.1 -p $self->port".
141 See also "dbowner", "dbname", "host", "base_port".
143 extra_psql_args
145 Extra args to be appended to "psql_args".
146 run_psql_args
148 Arguments specific for "run_psql" invocation, used mostly to set up and
149 seed database schema after PostgreSQL instance is launched and
150 configured.
151 Default is "-1Xqb -v ON_ERROR_STOP=1". This means:
153 • 1: Run all SQL statements in passed scripts as single transaction
155 • X: Skip ".psqlrc" files
157 • q: Run quietly, print only notices and errors on stderr (if any)
159 • b: Echo SQL statements that cause PostgreSQL exceptions (version
161 9.5+)
162 • -v ON_ERROR_STOP=1: Stop processing SQL statements after the first
164 error
165 seed_scripts
167 Arrayref with the list of SQL scripts to run after the database was
168 instanced and set up. Default is "[]".
169 NOTE that "psql" older than 9.6 does not support multiple "-c" and "-f"
171 switches in arguments so "seed_scripts" will be executed one by one.
172 This implies multiple transactions instead of just one; if you need all
173 seed statements to apply within a single transaction, combine them into
174 one seed script.
175 auto_start
177 Integer value that controls whether PostgreSQL server is started and
178 setup after creating "Test::PostgreSQL" instance. Possible values:
179 0 Do not start PostgreSQL.
181 1 Start PostgreSQL but do not run "setup".
183 2 Start PostgreSQL and run "setup".
185 Default is 2.
187
189 new
190 Create and run a PostgreSQL instance. The instance is terminated when
191 the returned object is being DESTROYed. If required programs (initdb
192 and postmaster) were not found, the function returns undef and sets
193 appropriate message to $Test::PostgreSQL::errstr.
194 dsn
196 Builds and returns dsn by using given parameters (if any). Default
197 username is "postgres", and dbname is "test" (an empty database).
198 uri
200 Builds and returns a connection URI using the given parameters (if
201 any). See URI::db for details about the format.
202 Default username is "postgres", and dbname is "test" (an empty
204 database).
205 pid
207 Returns process id of PostgreSQL (or undef if not running).
208 port
210 Returns TCP port number on which postmaster is accepting connections
211 (or undef if not running).
212 start
214 Starts postmaster.
215 stop
217 Stops postmaster.
218 setup
220 Setups the PostgreSQL instance. Note that this method should be invoked
221 before "start".
222 run_psql
224 Execute "psql" program with the given list of arguments. Usually this
225 would be something like:
226 $pgsql->run_psql('-c', q|'INSERT INTO foo (bar) VALUES (42)'|);
228 Or:
230 $pgsql->run_psql('-f', '/path/to/script.sql');
232 Note that when using literal SQL statements with "-c" parameter you
234 will need to escape them manually like shown above. "run_psql" will not
235 quote them for you.
236 The actual command line to execute "psql" will be concatenated from
238 "psql_args", "extra_psql_args", and "run_psql_args".
239 NOTE that "psql" older than 9.6 does not support multiple "-c" and/or
241 "-f" switches in arguments.
242 run_psql_scripts
244 Given a list of script file paths, invoke "run_psql" once with "-f
245 'script'" for every path in PostgreSQL 9.6+, or once per "-f 'script'"
246 for older PostgreSQL versions.
247
249 POSTGRES_HOME
250 If your postgres installation is not located in a well known path, or
251 you have many versions installed and want to run your tests against
252 particular one, set this environment variable to the desired path. For
253 example:
254 export POSTGRES_HOME='/usr/local/pgsql94beta'
256 This is the same idea and variable name which is used by the installer
258 of DBD::Pg.
259
261 Toby Corkindale, Kazuho Oku, Peter Mottram, Alex Tokarev, plus various
262 contributors.
263
265 Current version copyright X 2012-2015 Toby Corkindale.
266 Previous versions copyright (C) 2009 Cybozu Labs, Inc.
268
270 This module is free software, released under the Perl Artistic License
271 2.0. See <http://www.perlfoundation.org/artistic_license_2_0> for more
272 information.
273perl v5.34.0 2022-02-21 Test::PostgreSQL(3pm)