A single disposable database process is not enough when the task involves replication, client certificates, connection pooling, WAL, logs, or resource limits. pg-stand turns a declarative YAML profile into a realistic PostgreSQL 10-18 environment managed through Docker.

The payoff

Recreating a failure or validating a runbook becomes a named configuration plus a few commands - not a hand-built collection of containers, networks, credentials, volumes, and replication bootstrap steps.

Real tasks it helps with

Reproduce a production issue

Match the PostgreSQL major and topology, apply the relevant settings, generate activity, and inspect the same logs and statistics without touching the real server.

Validate replication runbooks

Practice asynchronous or synchronous physical replication, inspect lag, reinitialize a standby, or sync an all-tables logical subscriber.

Test secure clients

Exercise certificate-only PostgreSQL and replication connections, expected authentication failures, and both PgBouncer pooling modes.

Run a version matrix

Build integration checks against supported majors with fixed CPU, RAM, host-visible PGDATA, WAL, and CSV logs.

Topology at a glance

Full profile
                         synchronous physical WAL
                  +================================> standby
                  |
clients --> PgBouncer --> primary
                  |
                  +---- logical publication ------> logical replica
                  |
                  +---- PGDATA / WAL / CSV logs --> host storage

YAML profile --> pg-stand --> Docker SDK --> owned resources only

Topologies and lifecycle modes

Mode What it provides Typical commands
Single One server with direct, session-pooled, and transaction-pooled access up, status, health
Async physical Primary plus a non-blocking physical standby replication status, standby reinit --force
Sync physical Commit waits for the configured standby wait, watch, replication watch
Sync + logical Physical copy plus an independent logical subscriber logical sync, health
Change lifecycle Read-only drift plan, reloadable apply, or container restart plan, apply --reload, apply --restart

Bring up a stand

pg-stand init
pg-stand -c configs/primary-standby-async.yaml validate
pg-stand -c configs/primary-standby-async.yaml storage init
pg-stand -c configs/primary-standby-async.yaml up
pg-stand -c configs/primary-standby-async.yaml health
pg-stand -c configs/primary-standby-async.yaml replication status

Know the boundary

pg-stand is a controlled test environment, not a production cluster manager. Automatic failover and promotion are out of scope. Its diagnostic images deliberately enable aggressive statistics and logging that add overhead and should not be copied into production as tuning advice.

GitHub repository ↗ PyPI package ↗