1Test::PostgreSQL(3pm) User Contributed Perl DocumentationTest::PostgreSQL(3pm)
2
3
4

NAME

6       Test::PostgreSQL - PostgreSQL runner for tests
7

SYNOPSIS

9         use DBI;
10         use Test::PostgreSQL;
11         use Test::More;
12
13         # optionally
14         # (if not already set at shell):
15         #
16         # $ENV{POSTGRES_HOME} = '/path/to/my/pgsql/installation';
17
18         my $pgsql = eval { Test::PostgreSQL->new() }
19             or plan skip_all => $@;
20
21         plan tests => XXX;
22
23         my $dbh = DBI->connect($pgsql->dsn);
24

DESCRIPTION

26       "Test::PostgreSQL" automatically setups a PostgreSQL instance in a
27       temporary directory, and destroys it when the perl script exits.
28
29       This module is a fork of Test::postgresql, which was abandoned by its
30       author several years ago.
31

ATTRIBUTES

33       "Test::PostgreSQL" object has the following attributes, overridable by
34       passing corresponding argument to constructor:
35
36   dbname
37       Database name to use in this "Test::PostgreSQL" instance. Default is
38       "test".
39
40   dbowner
41       Database owner user name. Default is "postgres".
42
43   host
44       Host name or IP address to use for PostgreSQL instance connections.
45       Default is 127.0.0.1.
46
47   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
52   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
56       Default: 15432.
57
58   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
64   socket_dir
65       Unix socket directory to use if "unix_socket" is true. Default is
66       "$base_dir/tmp".
67
68   pg_ctl
69       Path to "pg_ctl" program which is part of the PostgreSQL distribution.
70
71       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
76       NOTE: do NOT use this with PostgreSQL versions prior to version 9.0.
77
78       By default we will try to find "pg_ctl" in PostgresSQL directory.
79
80   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
84   initdb_args
85       Arguments to pass to "initdb" program when creating a new PostgreSQL
86       database cluster for Test::PostgreSQL session.
87
88       Defaults to "-U postgres -A trust". See "dbowner".
89
90   extra_initdb_args
91       Extra args to be appended to "initdb_args". Default is empty.
92
93   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
98           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
110   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
117   postmaster_args
118       Defaults to "-h 127.0.0.1 -F".
119
120   extra_postmaster_args
121       Extra args to be appended to "postmaster_args". Default is empty.
122
123   psql
124       Path to "psql" client which is part of the PostgreSQL distribution.
125
126       "psql" can be used to run SQL scripts against the temporary database
127       created by "new":
128
129           my $pgsql = Test::PostgreSQL->new();
130           my $psql = $pgsql->psql;
131
132           my $out = `$psql -f /path/to/script.sql 2>&1`;
133
134           die "Error executing script.sql: $out" unless $? == 0;
135
136   psql_args
137       Command line arguments necessary for "psql" to connect to the correct
138       PostgreSQL instance.
139
140       Defaults to "-U postgres -d test -h 127.0.0.1 -p $self->port".
141
142       See also "dbowner", "dbname", "host", "base_port".
143
144   extra_psql_args
145       Extra args to be appended to "psql_args".
146
147   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
152       Default is "-1Xqb -v ON_ERROR_STOP=1". This means:
153
154       •   1: Run all SQL statements in passed scripts as single transaction
155
156       •   X: Skip ".psqlrc" files
157
158       •   q: Run quietly, print only notices and errors on stderr (if any)
159
160       •   b: Echo SQL statements that cause PostgreSQL exceptions (version
161           9.5+)
162
163       •   -v ON_ERROR_STOP=1: Stop processing SQL statements after the first
164           error
165
166   seed_scripts
167       Arrayref with the list of SQL scripts to run after the database was
168       instanced and set up. Default is "[]".
169
170       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
176   auto_start
177       Integer value that controls whether PostgreSQL server is started and
178       setup after creating "Test::PostgreSQL" instance. Possible values:
179
180       0   Do not start PostgreSQL.
181
182       1   Start PostgreSQL but do not run "setup".
183
184       2   Start PostgreSQL and run "setup".
185
186           Default is 2.
187

METHODS

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
195   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
199   uri
200       Builds and returns a connection URI using the given parameters (if
201       any). See URI::db for details about the format.
202
203       Default username is "postgres", and dbname is "test" (an empty
204       database).
205
206   pid
207       Returns process id of PostgreSQL (or undef if not running).
208
209   port
210       Returns TCP port number on which postmaster is accepting connections
211       (or undef if not running).
212
213   start
214       Starts postmaster.
215
216   stop
217       Stops postmaster.
218
219   setup
220       Setups the PostgreSQL instance. Note that this method should be invoked
221       before "start".
222
223   run_psql
224       Execute "psql" program with the given list of arguments. Usually this
225       would be something like:
226
227           $pgsql->run_psql('-c', q|'INSERT INTO foo (bar) VALUES (42)'|);
228
229       Or:
230
231           $pgsql->run_psql('-f', '/path/to/script.sql');
232
233       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
237       The actual command line to execute "psql" will be concatenated from
238       "psql_args", "extra_psql_args", and "run_psql_args".
239
240       NOTE that "psql" older than 9.6 does not support multiple "-c" and/or
241       "-f" switches in arguments.
242
243   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

ENVIRONMENT

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
255           export POSTGRES_HOME='/usr/local/pgsql94beta'
256
257       This is the same idea and variable name which is used by the installer
258       of DBD::Pg.
259

AUTHOR

261       Toby Corkindale, Kazuho Oku, Peter Mottram, Alex Tokarev, plus various
262       contributors.
263
265       Current version copyright X 2012-2015 Toby Corkindale.
266
267       Previous versions copyright (C) 2009 Cybozu Labs, Inc.
268

LICENSE

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.
273
274
275
276perl v5.34.0                      2022-02-21             Test::PostgreSQL(3pm)
Impressum