---
name: "pg_virtualenv"
section: "1"
platform: "linux"
package: "postgresql-common"
version: "278"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/pg_virtualenv"
---

# pg\_virtualenv(1)

Create a throw-away PostgreSQL environment for running regression tests

## NAME

pg\_virtualenv - Create a throw-away PostgreSQL environment for running regression tests

## SYNOPSIS

**pg\_virtualenv** \[*OPTIONS*\] \[**-v** '*version ...*'\] \[*command*\]

## DESCRIPTION

**pg\_virtualenv** creates a virtual PostgreSQL server environment, and sets environment variables such that *command* can access the PostgreSQL database server(s). The servers are destroyed when *command* exits.

The environment variables **PGHOST**, **PGDATABASE**, **PGUSER**, and **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 **5432**, and **PGPORT** will be set. **PGVERSION** is set the the PostgreSQL major version number.

When clusters for more than one versions are created, they will differ in the port number used, and **PGPORT** and **PGVERSION** are not set. The clusters are named *version*/regress. To access a cluster, set **PGCLUSTER=***version***/regress**. For ease of access, the clusters are also registered in */etc/postgresql-common/pg\_service.conf*, with the version number as cluster name. Clusters can be accessed by passing the connection string "**service=***version*", e.g. **psql service=9.2**.

When invoked as root, the clusters are created in */etc/postgresql/* as usual; for other users, **PG\_CLUSTER\_CONF\_ROOT** and **PGSYSCONFDIR** are set to a temporary directory where all files belonging to the clusters are created.

If *command* fails, the tail of the PostgreSQL server log is shown. Additionally, if **gdb** is available, the backtrace from any PostgreSQL coredump is show.

## OPTIONS

- **-a**

  Use all PostgreSQL server versions installed.

- **-v** *version ...*

  Use these versions (space-separated list).

- **-c** *pg\_createcluster options*

  Extra options to pass to **pg\_createcluster**.

- **-i** *initdb options*

  Extra initdb options to pass to **pg\_createcluster**.

- **-o** *guc***=***value*

  Configuration option to set in the `postgresql.conf` file, passed to **pg\_createcluster**.

- **-p** *package*

  Set **extension\_destdir** and **dynamic\_library\_path** in cluster to enable loading and testing extensions at build-time from **debian/***package***/**.

  This is a Debian-specific PostgreSQL patch.

- **-s**

  Launch a shell inside the virtual environment when *command* fails.

- **-t**

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

- **-h**

  Show program help.

## EXAMPLE

```
  # pg_virtualenv make check
```

## NOTES

When run with [**fakeroot**(1)](/fakeroot/1.md), **pg\_virtualenv** will fall back to the non-root mode of operation. Running "fakeroot pg\_virtualenv" as root will fail, though.

## ENVIRONMENT

- **PG\_VIRTUALENV\_NEWPID**=yes

  When non-empty, **pg\_virtualenv** will re-exec itself using [**newpid**(1)](/newpid/1.md).

- **PG\_VIRTUALENV\_UNSHARE**=*flags*

  When non-empty, **pg\_virtualenv** will re-exec itself using [**unshare**(1)](/unshare/1.md) using these flags.

- **PGPORT**=*n*

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

## COMPATIBILITY

**PGVERSION** is set in postgresql-common (\>= 219~).

## SEE ALSO

[**initdb**(1)](/initdb/1.md), [**pg\_createcluster**(1)](/pg_createcluster/1.md).

## AUTHOR

Christoph Berg \<myon@debian.org\>