PG/TOOLS GitHub
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. Every layer.

Use each utility independently from the command line, or install the current pg_play source to bring the complete PostgreSQL stack into one recoverable workflow. Cards describe current source; PyPI versions identify the latest published packages installed by the commands below.

MCP ORCHESTRATOR 00

pg_play

The control plane for reproducible PostgreSQL experiments.

Turns a reviewed experiment manifest into durable runs, append-only events, verified artifacts, and comparable results.

  • Asynchronous, resumable execution
  • Typed MCP operations for AI agents
  • Immutable plans and artifact hashes
Source v0.3.0 · Alpha PyPI 0.2.1
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
Source v0.9.1 · Alpha PyPI 0.9.1
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
Source v0.2.1 · Alpha PyPI 0.2.1
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
Source v0.4.0 · Alpha PyPI 0.4.0
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
Source v0.2.0 · Alpha PyPI 0.2.0
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
Source v0.10.5 · Beta Guide PyPI 0.10.4
MIGRATE 06

pg_converter

Asynchronous packet deployments across databases.

Applies versioned SQL and Python packets—migrations, operational, and diagnostic tasks—to one or many PostgreSQL 10–18 databases.

  • Tracked, resumable deployments
  • 46 bundled packets, local overrides
  • Webhooks and encrypted exports
Source v2.0b2 · Beta PyPI 2.0b0

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 binds the report to the exact query pack that produced it—so two reports can be compared safely.

schema versioned sha256 verified renders to HTML
report.json — pg_diag 0.10.5 
{
  "artifact_schema_version": 4,
  "generator": { "name": "pg_diag", "version": "0.10.5" },
  "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 the whole stack 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 current source.

PyPI 0.2.1 · source 0.3.0 · Python 3.10+ · PostgreSQL 10–18 · Linux

Command copied