pg_virtualenv.pod 2.7 KB
Newer Older
1 2 3 4 5 6
=head1 NAME

pg_virtualenv - Create a throw-away PostgreSQL environment for running regression tests

=head1 SYNOPSIS

7
B<pg_virtualenv> [I<OPTIONS>] [B<-v> 'I<version ...>'] [I<command>]
8 9 10

=head1 DESCRIPTION

11
B<pg_virtualenv> creates a virtual PostgreSQL server environment, and sets
12
environment variables such that I<command> can access the PostgreSQL database
13
server(s). The servers are destroyed when I<command> exits.
14 15

The environment variables B<PGHOST>, B<PGDATABASE>, B<PGUSER>, and
16 17 18
B<PGPASSWORD> will be set. Per default, a single new cluster is created,
using the newest PostgreSQL server version installed. The cluster will use the
first available port number starting from B<5432>, and B<PGPORT> will be set.
19

20 21
When clusters for more than one versions are created, they will differ in the
port number used, and B<PGPORT> is not set. The clusters are
22 23 24 25 26 27
named I<version>/regress. To access a cluster, set
B<PGCLUSTER=>I<version>B</regress>. For ease of access, the clusters are also
registered in F</etc/postgresql-common/pg_service.conf>, with the version
number as cluster name. Clusters can be accessed by passing the connection
string "B<service=>I<version>", e.g. B<psql service=9.2>.

28 29
When invoked as root, the clusters are created in F</etc/postgresql/> as usual;
for other users, B<PG_CLUSTER_CONF_ROOT> and B<PGSYSCONFDIR> are
30 31
set to a temporary directory where all files belonging to the clusters are
created.
32 33 34 35 36 37 38 39 40 41 42 43 44

=head1 OPTIONS

=over 4

=item B<-a>

Use all PostgreSQL server versions installed.

=item B<-v> I<version ...>

Use these versions (space-separated list).

45 46 47 48 49 50 51 52
=item B<-c> I<pg_createcluster options>

Extra options to pass to B<pg_createcluster>.

=item B<-i> I<initdb options>

Extra initdb options to pass to B<pg_createcluster>.

53 54 55 56 57
=item B<-o> I<guc>B<=>I<value>

Configuration option to set in the C<postgresql.conf> file, passed to
B<pg_createcluster>.

58 59
=item B<-s>

60
Launch a shell inside the virtual environment when I<command> fails.
61

62 63 64 65
=item B<-t>

Install clusters in a temporary directory, even when running as root.

66 67 68 69 70 71 72 73
=item B<-h>

Show program help.

=back

=head1 EXAMPLE

74
  # pg_virtualenv make check
75

76 77 78 79 80
=head1 NOTES

When run with fakeroot(1), B<pg_virtualenv> will fall back to the non-root mode
of operation. Running "fakeroot pg_virtualenv" as root will fail, though.

81 82 83 84 85 86 87 88 89 90 91 92 93
=head1 ENVIRONMENT

=over 4

=item B<PG_VIRTUALENV_NEWPID>=yes

When non-empty, B<pg_virtualenv> will re-exec itself using newpid(1).

=item B<PG_VIRTUALENV_UNSHARE>=I<flags>

When non-empty, B<pg_virtualenv> will re-exec itself using unshare(1) using
these flags.

94 95 96 97
=item B<PGPORT>=I<n>

When set, the value is used for the (single) cluster created.

Christoph Berg's avatar
Christoph Berg committed
98 99
=back

100 101
=head1 SEE ALSO

102
initdb(1), pg_createcluster(1).
103 104 105 106

=head1 AUTHOR

Christoph Berg L<E<lt>myon@debian.orgE<gt>>