Monitoring and diagnostic tools look perfect against an idle database because there is nothing meaningful to observe. pg-workload installs declarative scenarios and generates the plans, locks, WAL, errors, autovacuum work, and logs that a real PostgreSQL service produces.

The payoff

A repeatable activity profile replaces a fragile demo script. Teams can recreate the same diagnostic signals, verify that an alert actually fires, and retest a runbook after changing the database, dashboard, or collector.

Real tasks it helps with

Validate observability

Feed query plans, statement churn, locks, errors, and log volume into pg-diag, dashboards, and log parsers before they are trusted in production.

Exercise application patterns

Recreate write-heavy stock updates, analytical joins, JSONB documents, SKIP LOCKED queues, or partition aging without copying production data.

Test maintenance behavior

Generate dead-tuple churn and scheduled VACUUM activity to verify bloat detection, autovacuum visibility, and DBA response procedures.

Reproduce a diagnostic window

Run the same profile and interval while comparing configuration candidates or PostgreSQL majors.

The observation loop

Generate behavior, then observe it
pg-stand or existing test server
                |
                v
        pg-workload install
                |
      +---------+----------+
      |                    |
      v                    v
 run selected jobs   desired-state scheduler
      |                    |
      +---------+----------+
                |
                v
 queries / plans / locks / WAL / bloat / errors / logs
                |
                v
       pg-diag / dashboards / alerting / runbooks

Operating modes

Dimension Modes When to use them
Execution run once or scheduler/start A focused reproduction versus recurring background activity
Target local, external, patroni DB host, TCP endpoint/proxy, or a selected Patroni member
Preparation prepare-db, install Create the dedicated role/database, then schema and deterministic data
Desired state enable, disable, set-interval Change scheduled jobs without restarting the scheduler
Review validate, plan, state Check local contracts and inspect work before connecting

Install and run one profile

# Keep credentials outside command-line history.
export WORKLOAD_ADMIN_PASSWORD='admin-secret'
export WORKLOAD_PASSWORD='new-workload-role-secret'

pg-workload init
pg-workload validate --profile simple_stock

pg-workload prepare-db \
  --target external \
  --host 127.0.0.1 \
  --database workload_db

pg-workload install \
  --target external \
  --host 127.0.0.1 \
  --database workload_db \
  --profile simple_stock \
  --scale 1

pg-workload run \
  --target external \
  --host 127.0.0.1 \
  --database workload_db \
  --profile simple_stock

Know the boundary

pg-workload emulates activity; it does not measure maximum TPS or prove capacity. Use pg-perf-bench for controlled performance measurement. Profiles and their Python generators are trusted code, so edit and run them only from a trusted project directory.

GitHub repository ↗ PyPI package ↗