PG/TOOLS GitHub
Production PostgreSQL engineering

Run PostgreSQL changes with confidence.

Configure servers, audit production, plan and execute reviewed database changes, and validate performance before go-live - with reviewable inputs and portable evidence at every step.

Explore production tools Start with an audit
  • 10-18Version-aware tooling
  • HEALTH + SECURITYProduction checks
  • PLAN FIRSTReviewed changes
Open-source database engineering toolkit

Make PostgreSQL experiments repeatable.

Configure, provision, load, benchmark, diagnose, and compare with one composable toolchain built for DBAs, performance engineers, developers, and AI agents.

Explore the toolkit View pg-play
  • 10-18PostgreSQL majors
  • CLI + MCPHuman and agent ready
  • JSON + HTMLPortable evidence
Measured, not guessed Evidence in every report Safe, bounded execution Built to compose

01 / THE ECOSYSTEM

One toolkit. Connected workflows.

Use each utility independently from the command line, or install the current pg-play release to coordinate all PG Tools components through recoverable workflows. Each card links to its source and package while the commands install the latest available release.

MCP ORCHESTRATOR 00

pg-play

The control plane for reviewed PostgreSQL operations.

Coordinates configuration reviews, incident captures, database changes, benchmarks, and experiments as durable, inspectable operations.

  • Asynchronous, resumable execution
  • Typed MCP operations for AI agents
  • Immutable plans and artifact hashes
Guide PyPI
CONFIGURE 01

pg-configurator

Explainable, hardware-aware PostgreSQL configuration.

Converts hardware limits, workload shape, topology, and server version into a reviewable configuration candidate.

  • Explicit safety budgets
  • Rule provenance for every GUC
  • Version-aware validation
Guide PyPI
PROVISION 02

pg-stand

Declarative Docker testbeds for PostgreSQL.

Creates disposable but realistic database environments with managed images, bounded resources, logs, and persistent evidence.

  • Single and replicated topologies
  • Repeatable, schema-validated YAML
  • Safe ownership boundaries
Guide PyPI
EMULATE 03

pg-workload

Profile-driven PostgreSQL backend activity.

Produces realistic plans, logs, locks, and runtime statistics through editable, deterministic workload profiles.

  • Packaged activity profiles
  • Controlled data generation
  • Scheduler and resource guards
Guide PyPI
BENCHMARK 04

pg-perf-bench

Controlled maximum-TPS performance experiments.

Sweeps concurrency, measures saturation, and keeps the workload, configuration, host, and raw execution evidence together.

  • PostgreSQL 10-18 targets
  • Environment-safe report joins
  • TPS and host metric comparisons
Guide PyPI
DIAGNOSE 05

pg-diag

PostgreSQL diagnostics with host metrics.

Collects database and Linux evidence locally or over SSH, then produces portable reports for humans and automation.

  • Read-only PostgreSQL collection
  • One-shot and time-series modes
  • Self-contained JSON and HTML
Guide PyPI
CHANGE 06

pg-converter

Asynchronous tracked changes across databases.

Applies reviewed database operations - versioned SQL change packets, Python steps, operational tasks, and diagnostics - to one or many PostgreSQL 10-18 databases.

  • Tracked, resumable deployments
  • Bundled operations and local overrides
  • Webhooks and encrypted exports
Guide PyPI

02 / THE WORKFLOW

Change one thing. Prove the effect.

The toolkit preserves the context around every result, so a faster run is evidence - not an anecdote.

  1. 01
    Define

    Describe the stand, workload, limits, and expected artifacts.

  2. 02
    Run

    Provision safely, apply a candidate, and execute bounded workloads.

  3. 03
    Observe

    Capture TPS, database state, CPU, memory, disk, network, and logs.

  4. 04
    Compare

    Join only compatible reports and isolate the variable that changed.

CONTROLLED COMPARISON

From “it feels faster” to a reproducible result.

Configuration, workload source, generated data, client version, host facts, and collection diagnostics travel with the report. Incompatible experiments are rejected before they distort a chart.

same workload same environment one changed variable
THROUGHPUT TPS by concurrency
baseline candidate
0 1k 2k 3k 4k 1 4 8 16 32
end to end - from stand to compared reports 
# initialize editable component assets
$ pg-stand init --directory stand
$ pg-workload init --directory workload

# validate and review the complete experiment
$ pg-play validate experiment.yaml
$ pg-play plan experiment.yaml > plan.json

# start the unchanged plan in a durable worker
$ pg-play start experiment.yaml --plan-hash sha256:... --run-id baseline-001
$ pg-play status experiment.yaml --run-id baseline-001

# compare compatible benchmark artifacts
$ pg-play compare-benchmark-reports baseline.json candidate.json

03 / THE ARTIFACT

Every run leaves proof.

pg-diag and pg-perf-bench make structured JSON the durable automation artifact and render self-contained HTML alongside it.

REAL OUTPUT, TRIMMED

One JSON. Humans and machines read the same truth.

Collected items keep their columns, types, rows, and collection status. The content checksum verifies that reports use the same diagnostic content set. Workload, configuration, topology, and host identity still have to match before results are compared.

schema versioned sha256 verified renders to HTML
report.json - pg-diag 
{
  "artifact_schema_version": 4,
  "generator": { "name": "pg_diag" },
  "content": {
    "checksum": "sha256:9a846631…fefc7f8e8",
    "report_id": "pg_diag_minimal"
  },
  "items": {
    "activity_locks.lock_modes": {
      "collection_status": "ok",
      "result": {
        "kind": "table",
        "columns": [
          { "name": "locktype", "pg_type": "text" },
          { "name": "mode", "pg_type": "text" },
          { "name": "granted", "pg_type": "bool" },
          { "name": "locks", "pg_type": "int8", "unit": "count" }
        ],
        "row_count": 4,
        "rows": [
          ["virtualxid", "ExclusiveLock", true, "3"],
          ["relation", "ShareUpdateExclusiveLock", true, "2"]
        ]
      }
    }
  }
}

04 / AI-READY

Built for agents, not just humans.

pg-play-mcp exposes supported workflows across the toolkit as typed MCP operations - no arbitrary shell, SQL, or Docker access.

31 TYPED MCP OPERATIONS

Agents plan, run, and compare through contracts.

High-level operations cover experiment lifecycles, live diagnostics, configuration reviews, converter runs, and artifact comparison. Calls are schema-validated, plans are hashed before execution, and durable runs are resumable.

plan_experiment start_experiment experiment_status compare_benchmark_reports join_benchmark_reports teardown_experiment
mcp - plan_experiment 
→ tool call
{
  "name": "plan_experiment",
  "arguments": { "manifest": "experiments/pg18-candidate.yaml" }
}

← tool result
{
  "schema_version": "pg_play/plan-v1",
  "experiment_id": "pg18-candidate-03",
  "plan_hash": "sha256:4be2…9d01",
  "phases": {
    "benchmark": true,
    "workload_diagnostics": true,
    "recreate_workload_database": true
  }
}

05 / ENGINEERING PRINCIPLES

Designed for trustworthy automation.

01

Evidence first

Results carry their inputs, environment, versions, raw output, timestamps, and collection status.

02

Safe boundaries

Read-only diagnostics, explicit disposable databases, resource guards, and reviewed deployment plans.

03

Open interfaces

Stable CLIs, versioned schemas, structured JSON, portable HTML, and typed MCP operations.

START WITH THE LATEST RELEASE

Install the orchestrator.
Explore the toolkit.

Available on PyPI · Python · PostgreSQL · Linux

Connect an MCP client ↗
Command copied