=head1 NAME

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

=head1 SYNOPSIS

B<pg_virtualenv> [B<-ash> B<-v> 'I<version ...>'] [I<command>]

=head1 DESCRIPTION

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

The environment variables B<PGHOST>, B<PGDATABASE>, B<PGUSER>, and
B<PGPASSWORD> will be set. Per default, a single new cluster is created on port
B<5432>, using the newest PostgreSQL server version installed. When more
clusters are created for other versions, they will use other port numbers.

B<pg_createcluster> is used to create the database clusters. The clusters are
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>.

When invoked as root user, the servers and I<command> are run in an unshared
mount and network namespace; the servers are created on tmpfses, so actions
caused by I<command> in the database do not affect the running system.
I<command> can drop privileges as needed, provided the environment variables
are passed.

When invoked as non-root user, B<PG_CLUSTER_CONF_ROOT> and B<PGSYSCONFDIR> are
set to a temporary directory where all files belonging to the clusters are
created.

=head1 OPTIONS

=over 4

=item B<-a>

Use all PostgreSQL server versions installed.

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

Use these versions (space-separated list).

=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>.

=item B<-o> I<guc>B<=>I<value>

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

=item B<-s>

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

=item B<-h>

Show program help.

=back

=head1 EXAMPLE

  # pg_virtualenv make check

=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.

=head1 SEE ALSO

initdb(1), pg_createcluster(1), unshare(1).

=head1 AUTHOR

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