PG_VIRTUALENV(1)

📦
version 293ubuntu1 · 8 versions
, in ubuntu stonking

🎀 PG_VIRTUALENV 🎀 (yes bestie, this is PG_VIRTUALENV(1) — the Debian PostgreSQL infrastructure girlies know)

okay so you found the pg_virtualenv page. section 1. Debian PostgreSQL infrastructure. we're doing this. sit down, hydrate, let's go 💅

✨ NAME ✨

pg_virtualenv — makes a whole entire throw-away PostgreSQL environment so you can run regression tests in it and then never think about it again. it's giving disposable. it's giving responsible. 🫶

🦋 SYNOPSIS 🦋

pg_virtualenv [OPTIONS] [-v 'version ...'] [command]

🌸 DESCRIPTION 🌸

So the whole vibe: pg_virtualenv creates a virtual PostgreSQL server environment and sets environment variables so that command can access the PostgreSQL database server(s). And the servers? They get destroyed when command exits. no residue, no mess, no "wait why is there a cluster on my machine from 2019". iconic behaviour honestly ✨

The environment variables PGHOST, PGDATABASE, PGUSER, and PGPASSWORD will be set. Per default, it creates a single new cluster, using the newest PostgreSQL server version installed. That cluster grabs the first available port number starting from 5432, and PGPORT gets set. PGVERSION is set to the PostgreSQL major version number.

Now when you create clusters for more than one version, they're gonna 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. And for ease of access, the clusters are also registered in /etc/postgresql-common/pg_service.conf, with the version number as the cluster name. So you can reach a cluster by passing the connection string "service=version", like psql service=9.2. cute, right? 😌

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. bestie privileges ✨

And if command fails? You get the tail of the PostgreSQL server log shown. Plus, if gdb is available, the backtrace from any PostgreSQL coredump is shown. that's the "we got you, here's what went wrong" energy. 💖

💅 OPTIONS 💅

  • -a — Use all PostgreSQL server versions installed. all of them. every single one. go off. 👑
  • -v version ... — Use these versions (space-separated list). you pick, bestie.
  • -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_control_path (extension_destdir on older versions) and dynamic_library_path in the 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. debugging main character energy fr fr.
  • -t — Install clusters in a temporary directory, even when running as root.
  • -h — Show program help. classic. never not useful. 😭

🌈 EXAMPLE 🌈

# pg_virtualenv make check

that's it. that's the whole thing. slay. ✨

🙈 NOTES 🙈

When run with fakeroot(1), pg_virtualenv will fall back to the non-root mode of operation. But heads up: running "fakeroot pg_virtualenv" as root will fail, though. so don't do that one. no cap. 💀

🧚 ENVIRONMENT 🧚

  • PG_VIRTUALENV_NEWPID=yes — When non-empty, pg_virtualenv will re-exec itself using newpid(1).
  • PG_VIRTUALENV_UNSHARE=flags — When non-empty, pg_virtualenv will re-exec itself using unshare(1) 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), pg_createcluster(1).

💜 AUTHOR 💜

Christoph Berg <myon@debian.org> — thank you for your service, king 🫡

and that's the page, bestie! this one came from Debian, dated 2026-07-28, and yeah, it's PG_VIRTUALENV(1). go make some throw-away clusters, you've got this 💖✨🎀

📦 where this page comes from