.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` 
.    ds C' 
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PG_VIRTUALENV 1"
.TH PG_VIRTUALENV 1 2024-04-15 Debian "Debian PostgreSQL infrastructure"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
pg_virtualenv \- Create a throw\-away PostgreSQL environment for running regression tests
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBpg_virtualenv\fR [\fIOPTIONS\fR] [\fB\-v\fR '\fIversion ...\fR'] [\fIcommand\fR]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBpg_virtualenv\fR creates a virtual PostgreSQL server environment, and sets
environment variables such that \fIcommand\fR can access the PostgreSQL database
server(s). The servers are destroyed when \fIcommand\fR exits.
.PP
The environment variables \fBPGHOST\fR, \fBPGDATABASE\fR, \fBPGUSER\fR, and
\&\fBPGPASSWORD\fR 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 \fB5432\fR, and \fBPGPORT\fR will be set.
\&\fBPGVERSION\fR is set the the PostgreSQL major version number.
.PP
When clusters for more than one versions are created, they will differ in the
port number used, and \fBPGPORT\fR and \fBPGVERSION\fR are not set. The clusters are
named \fIversion\fR/regress. To access a cluster, set
\&\fBPGCLUSTER=\fR\fIversion\fR\fB/regress\fR. For ease of access, the clusters are also
registered in \fI/etc/postgresql\-common/pg_service.conf\fR, with the version
number as cluster name. Clusters can be accessed by passing the connection
string "\fBservice=\fR\fIversion\fR", e.g. \fBpsql service=9.2\fR.
.PP
When invoked as root, the clusters are created in \fI/etc/postgresql/\fR as usual;
for other users, \fBPG_CLUSTER_CONF_ROOT\fR and \fBPGSYSCONFDIR\fR are
set to a temporary directory where all files belonging to the clusters are
created.
.PP
If \fIcommand\fR fails, the tail of the PostgreSQL server log is shown.
Additionally, if \fBgdb\fR is available, the backtrace from any PostgreSQL
coredump is show.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-a\fR 4
.IX Item "-a"
Use all PostgreSQL server versions installed.
.IP "\fB\-v\fR \fIversion ...\fR" 4
.IX Item "-v version ..."
Use these versions (space-separated list).
.IP "\fB\-c\fR \fIpg_createcluster options\fR" 4
.IX Item "-c pg_createcluster options"
Extra options to pass to \fBpg_createcluster\fR.
.IP "\fB\-i\fR \fIinitdb options\fR" 4
.IX Item "-i initdb options"
Extra initdb options to pass to \fBpg_createcluster\fR.
.IP "\fB\-o\fR \fIguc\fR\fB=\fR\fIvalue\fR" 4
.IX Item "-o guc=value"
Configuration option to set in the \f(CW\*(C`postgresql.conf\*(C'\fR file, passed to
\&\fBpg_createcluster\fR.
.IP "\fB\-p\fR \fIpackage\fR" 4
.IX Item "-p package"
Set \fBextension_destdir\fR and \fBdynamic_library_path\fR in cluster to enable
loading and testing extensions at build-time from \fBdebian/\fR\fIpackage\fR\fB/\fR.
.Sp
This is a Debian-specific PostgreSQL patch.
.IP \fB\-s\fR 4
.IX Item "-s"
Launch a shell inside the virtual environment when \fIcommand\fR fails.
.IP \fB\-t\fR 4
.IX Item "-t"
Install clusters in a temporary directory, even when running as root.
.IP \fB\-h\fR 4
.IX Item "-h"
Show program help.
.SH EXAMPLE
.IX Header "EXAMPLE"
.Vb 1
\&  # pg_virtualenv make check
.Ve
.SH NOTES
.IX Header "NOTES"
When run with \fBfakeroot\fR\|(1), \fBpg_virtualenv\fR will fall back to the non-root mode
of operation. Running "fakeroot pg_virtualenv" as root will fail, though.
.SH ENVIRONMENT
.IX Header "ENVIRONMENT"
.IP \fBPG_VIRTUALENV_NEWPID\fR=yes 4
.IX Item "PG_VIRTUALENV_NEWPID=yes"
When non-empty, \fBpg_virtualenv\fR will re-exec itself using \fBnewpid\fR\|(1).
.IP \fBPG_VIRTUALENV_UNSHARE\fR=\fIflags\fR 4
.IX Item "PG_VIRTUALENV_UNSHARE=flags"
When non-empty, \fBpg_virtualenv\fR will re-exec itself using \fBunshare\fR\|(1) using
these flags.
.IP \fBPGPORT\fR=\fIn\fR 4
.IX Item "PGPORT=n"
When set, the value is used for the (single) cluster created.
.SH COMPATIBILITY
.IX Header "COMPATIBILITY"
\&\fBPGVERSION\fR is set in postgresql-common (>= 219~).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBinitdb\fR\|(1), \fBpg_createcluster\fR\|(1).
.SH AUTHOR
.IX Header "AUTHOR"
Christoph Berg <myon@debian.org>