PGSimCity for PostgreSQL Incident Training

PostgreSQL incidents often start with invisible mechanics: dirty buffers, checkpoint pressure, WAL flushes, standby replay lag, or one old transaction holding the xmin horizon open. PGSimCity makes those mechanics visible in a browser, so SREs and platform engineers can rehearse failure patterns without touching production.

What is PGSimCity?

PGSimCity is an Apache-2.0 TypeScript project that models a PostgreSQL cluster as a 3D city. The live demo runs at nikolays.github.io/PGSimCity and needs no install.

It is not a PostgreSQL emulator. The README is explicit that it is a 0.x educational model with scaled numbers, tests, and specialist review against PostgreSQL docs and source behavior. That honesty matters. Treat it as a training simulator that explains cause and effect, not as a sizing calculator.

Why SREs Should Care

Database internals are usually learned under pressure. PGSimCity gives teams a calmer way to build intuition:

• Watch client connections turn into backend processes.
• Follow a query through parse, rewrite, plan, and execute.
• See shared buffers, WAL, heap pages, indexes, TOAST, locks, and autovacuum as separate areas.
• Trigger scenarios like cache thrash, checkpoint storm, slow replay, and long-running transactions.
• Use the color legend to connect visual state with operational concepts.

That makes it useful for onboarding, post-incident review, and explaining why a small application behavior can become a large database symptom.

Run it Locally

The hosted version is the fastest path, but local runs are simple if you want to test changes or present it internally.

git clone https://github.com/NikolayS/PGSimCity.git
cd PGSimCity
npm install
npm run dev

Then open the Vite URL, usually http://localhost:5173.

A Practical Drill

Start with the guided tour by pressing T. Then open the scenarios menu and run Long-running transaction. Watch autovacuum reach the table but fail to remove rows while the xmin horizon remains pinned.

Next, release the transaction and observe cleanup begin again. That single drill is enough to explain a common production pattern: database bloat is not always caused by missing vacuum workers. Sometimes the blocker is an old transaction, an idle session, or an application path that never closes work cleanly.

For storage-pressure training, run Checkpoint storm. Slow the simulation down and watch full-page writes, WAL flow, and fsync pressure. This creates a useful bridge from dashboard symptoms to root cause: latency spikes, WAL growth, and disk pressure are connected systems, not isolated metrics.

Operational Tips

Use PGSimCity as a visual companion to real observability. Pair it with pg_stat_activity, pg_stat_bgwriter, pg_stat_replication, and WAL volume charts during training. Ask engineers to predict what a scenario should look like in metrics before they inspect a dashboard.

For incident reviews, map the real timeline to the simulator. If the outage involved standby lag, replay it with slow replay enabled. If it involved bloat, replay a long transaction and explain the cleanup delay.

Conclusion

PGSimCity is worth bookmarking because it turns abstract PostgreSQL behavior into something teams can discuss together. It will not replace production telemetry, but it can make that telemetry easier to understand when minutes matter.

Looking to automate your infrastructure operations? Akmatori provides AI-powered agents that help SRE teams manage complex operational workflows with confidence. Built on Gcore's global infrastructure, Akmatori brings intelligent automation to your operational stack.