PGSimCity

An explorable 3D city that shows how PostgreSQL actually works.

**Live: **

🍊 #1 on Hacker News — thanks to everyone who visited, and especially to those who filed corrections. Bug reports about PostgreSQL behaviour are the most valuable thing this project can receive; see the prototype note below.

Every building is a real mechanism. The plaza in the centre is shared_buffers — 1024 page frames whose height is their clock-sweep usage count and whose colour is their true state. The amber district to the east is the write-ahead log. The pit under the plaza is the data directory, and the heap files down there grow when you bloat them. To the south, a standby replays what the primary sends it, always a little behind.

It is built for engineers who are good at their job and have never had to operate a database — the people who need to understand why a checkpoint spikes latency, why one forgotten transaction bloats a table forever, and what synchronous_commit is really charging them.

---

This is a prototype (v0.1)

It was built quickly, and it almost certainly contains inaccuracies and mistakes — in the simulation as well as in the explanations. It is a model of PostgreSQL, not an emulator: no PostgreSQL source code runs here, and the numbers are scaled so a human can watch them.

If you spot something wrong, especially a claim about how PostgreSQL actually behaves, please open an issue or send a pull request. Corrections from people who know the engine are exactly what this needs.

---

A possible future

Today the city uses a hand-written simulation of PostgreSQL’s mechanisms, which is what makes internals such as the clock sweep’s frame-by-frame victim choice observable. A real PostgreSQL compiled to WebAssembly — PGlite and similar projects embed the actual engine — would make query results and plans authoritative, but could expose only what PostgreSQL exposes through catalogs, pg_stat_* views, and EXPLAIN, not those internal steps. They answer different questions; a future hybrid could let real execution and plans drive the modelled interior, but that is a direction rather than a promise.

---