A production task rarely ends with one command. You collect facts, prepare a candidate, review the exact plan, run it, watch progress, and retain evidence. pg-play coordinates those steps across the PG Tools components without hiding their individual contracts.

The payoff

One reviewed plan hash, one durable run identity, ordered events, and validated artifacts replace an improvised chain of shell commands that is difficult to resume or audit.

Where it earns its place

Live incident capture

Start a bounded read-only diagnostics window for performance, locks, I/O, or CPU. The worker continues if the MCP client disconnects, while status and events remain queryable.

Configuration review

Collect facts from an existing server, generate an explainable candidate, and compare only changed or unobserved parameters - without applying or restarting.

Reviewed database change rollout

Resolve the exact pg-converter SQL change packet, source hash, and database aliases before a detached sequential run touches any target.

Controlled comparison

Recreate a stand, load it, benchmark it, diagnose it, then change one reviewed input and compare the resulting artifacts.

How the pieces connect

Reviewed workflow and durable evidence
operator or AI agent
        |
        v
 validate inputs --> build plan --> review plan_hash
                                      |
                                      v
                 start durable run --> events / status
                                      |
          +------------+--------------+--------------+
          |            |              |              |
          v            v              v              v
 pg-configurator   pg-stand     pg-converter    pg-diag
                                  / pg-workload  / pg-perf-bench
          |            |              |              |
          +------------+--------------+--------------+
                                      |
                                      v
                         validated JSON / HTML evidence

Operating modes

Mode Best for Control path
Converter run Reviewed database changes across an exact alias set plan-converter-run then start-converter-run
Live diagnostics Bounded production incident capture Typed MCP operations with immutable capture IDs
Configuration review Existing-server facts and candidate comparison Typed MCP workflow; deliberately read-only
Artifact inspection Validate or compare diagnostic and benchmark reports inspect-* and compare-*
Experiment Stand + optional benchmark + workload + diagnostics validate, plan, start, status, events, resume

Plan a reviewed database change

Resolve the exact SQL change packet, source hashes, and target aliases before starting a durable worker: 

pg-play plan-converter-run \
  --project /opt/pg_converter/current \
  --config /etc/pg_converter/pg_converter.conf \
  --packet release_42 \
  --database-selector 'prod_a,prod_b' \
  --timeout-seconds 3600 > converter-plan.json

# Review converter-plan.json, then copy its plan_hash:
pg-play start-converter-run converter-plan.json \
  --plan-hash sha256:... \
  --out /var/lib/pg_play/converter-runs \
  --run-id release-42

Run a reviewed experiment

pg-play validate experiment.yaml
pg-play plan experiment.yaml > plan.json

# Review plan.json, then copy its plan_hash:
pg-play start experiment.yaml \
  --plan-hash sha256:... \
  --run-id release-candidate-001

pg-play status experiment.yaml --run-id release-candidate-001
pg-play events experiment.yaml --run-id release-candidate-001

Know the boundary

pg-play is not a general remote shell and does not expose arbitrary SQL, Docker, or component commands. It does not silently apply a configuration candidate to production, and it never automatically destroys a stand. Those limits are what make the high-level workflow reviewable.

GitHub repository ↗ PyPI package ↗