disposable PostgreSQL, on demand
A command-line tool that provisions, manages, and tears down local PostgreSQL sandbox instances for development, testing, and bug reproduction. It ships as a single static binary with no runtime dependencies beyond the PostgreSQL binaries you point it at.
# point at an existing PostgreSQL install, then spin one up $ export PGS_BIN_DIR=/opt/postgresql/18.4 $ pg_sandbox deploy -s pg18 $ pg_sandbox use -s pg18 # open psql $ pg_sandbox run -s pg18 -- pgbench -i $ pg_sandbox destroy -s pg18 --force
Not a database driver, server, or HA system — a tool to stand instances up and tear them down cleanly. Every invocation is a short-lived process; there is no daemon.
Stand up an isolated PostgreSQL instance with a single deploy. Ports are auto-allocated; connect with use or run any utility with run.
Stand up physical streaming replication and logical pub/sub with --replicate-from, publish, and subscribe.
Provision a primary + N standbys (or publisher + N subscribers) in one cluster deploy, with shared manifest metadata and a consolidated status view.
Ask any sandbox whether it's running, primary or standby, its replication lag and subscriptions — as text or --json.
global_status lists every sandbox on the machine at a glance, in text or JSON for piping into jq.
Generate a pg_gather HTML report from a captured out.txt in a throwaway sandbox that's cleaned up automatically on success.
Compile any PostgreSQL version with build <version> — optional --with-icu / --with-openssl and debug builds via PGS_BUILD_DEBUG.
Resolve every value through a documented chain — CLI flag > PGS_* env var > sandbox config > global config > default. Inspect exactly where each came from with config show.
Pre-built binaries are attached to each GitHub Release. Pick the artifact matching your platform; a SHA256SUMS file is published alongside each release for checksum verification.
pg_sandbox-darwin-arm64
pg_sandbox-darwin-amd64
pg_sandbox-linux-amd64
pg_sandbox-linux-arm64
curl -L -o /usr/local/bin/pg_sandbox \ https://github.com/guriandoro/postgresql_sandbox/releases/latest/download/pg_sandbox-linux-amd64 chmod +x /usr/local/bin/pg_sandbox
Pre-built binaries have no Go requirement. CGO_ENABLED=0 on the cross-compile path means the Linux artifacts have no glibc dependency and run on any reasonably-recent kernel.
# local-arch binary into ./bin/pg_sandbox make build # all four release binaries into ./bin/ make build-all # or, without GNU make: ./scripts/build.sh
Binaries are stripped (-ldflags="-s -w") and stamped with the current version + commit — pg_sandbox --version shows both.
pg_sandbox does not bundle PostgreSQL — it points at an existing install and trusts that install's own version semantics.
initdb, pg_ctl, psql, pg_basebackup, pg_dump reachable on disk — pointed at via --bin-dir or PGS_BIN_DIR.
Targets amd64 and arm64. Windows is not supported.
Only for building from source — pre-built release binaries carry no Go requirement.
Each recipe assumes you've pointed at an install root once per shell session: export PGS_BIN_DIR=/opt/postgresql/18.4. A bare -s <name> resolves under the sandbox root, so it names the same sandbox from any directory.
deploy · connect · run · tear down
# deploy a standalone instance pg_sandbox deploy -s pg18 # connect with psql pg_sandbox use -s pg18 # run any utility (auto-injected flags) pg_sandbox run -s pg18 -- pgbench -i # stop and tear down pg_sandbox destroy -s pg18 --force
primary + async standby
# primary pg_sandbox deploy -s primary # async standby attached to it pg_sandbox deploy -s standby1 \ --replicate-from primary \ --slot primary_standby1_slot # promote standby1 if primary dies pg_sandbox promote -s standby1
publisher + subscriber
# publisher pg_sandbox deploy -s pub pg_sandbox publish -s pub \ --pub-name my_pub --all-tables # subscriber (deployed already subscribed) pg_sandbox deploy -s sub \ --subscribe-to pub \ --pub-name my_pub --copy-schema
1 primary + 2 standbys
# deploy the whole cluster at once pg_sandbox cluster deploy -s mycluster \ -N 2 --sync-count 1 # consolidated status pg_sandbox cluster status -s mycluster # tear down everything in one shot pg_sandbox cluster destroy -s mycluster --force
Run pg_sandbox help <command> (or pg_sandbox <command> --help) for full usage, flags, and examples on any single command.
deploy — create a new sandboxdestroy — tear down a sandboxstart / stop / restart — control PostgreSQLstatus — running state + replication infouse — open psql against a sandboxrun <bin> — run any PG utilitypromote — standby → standalone primaryconfig show — effective config + sourceconfig get <KEY> — read one valueconfig set KEY=VAL — mutate atomicallyconfig validate — check the configconfig migrate — convert legacy .envpublish — create a publicationsubscribe — create a subscriptioncluster deploy — primary + N standbyscluster status — consolidated viewcluster destroy — tear the cluster downglobal_status — list every sandboxreport --input — pg_gather HTML reportbuild <version> — compile PG from sourcecleanup-install-versions — prune unused installshelp [<command>] — built-in helpA slide-by-slide walkthrough — spin up any installed PG version in seconds, wire replication, and generate a report — every command verified working end-to-end against a real install.