PostgreSQL Internals as a City You Can Walk Through

Every Postgres operator carries a mental model of the engine — backends forking off the postmaster, dirty pages waiting on the checkpointer, autovacuum circling a table it can't clean because some forgotten transaction pinned the xmin horizon. Almost nobody built that model from diagrams. They built it from incidents.

PGSimCity is a bet that you can build it by walking around instead. It renders a running PostgreSQL instance as an explorable 3D city in the browser: the central plaza is shared_buffers, 1024 page frames whose height is their clock-sweep usage count; the amber district to the east is the WAL pipeline, walwriter through archiver to walsender; a standby to the south replays what the primary ships it, always a little behind. It hit #1 on Hacker News this weekend, and it deserves a closer look than "neat demo" — both for what it teaches and for how it got made.

The failure modes are the curriculum

The smart design decision is that PGSimCity isn't organized around components, it's organized around incidents. The built-in scenarios are a tour of the ways Postgres actually hurts people in production.

Drag shared_buffers down to 64 pages and the plaza thrashes: usage counts collapse, the clock hand races, and backends start writing out dirty pages themselves because eviction can't find anything clean — which is exactly what that mystery write-latency spike looks like in pg_stat_bgwriter. Enable the long-running-transaction scenario and you watch the xmin horizon sink while autovacuum workers drive their full route and come up empty every pass; the table bloats and never recovers. Run the checkpoint storm and the fsync shudder is followed by a wall of full-page writes flooding the WAL district — the reason WAL volume spikes after a checkpoint, which surprises nearly everyone the first time. Flip synchronous_commit to off and every backend stops stalling in commit_wait; the inspector then tells you what you just traded away.

These are the four or five lessons that normally cost a team an outage apiece. Having them as interactive toys, with the actual algorithms — clock-sweep replacement, checkpoint pacing against checkpoint_completion_target, HOT updates skipping index maintenance — running underneath, is genuinely new. Plan visualizers like pev2 and pgMustard explain what the planner did with your query; books like Hironobu Suzuki's The Internals of PostgreSQL explain the machinery statically. Nothing before this let you watch the runtime misbehave on demand.

Built in a weekend, billions of tokens

The provenance is the other half of the story. The author is Nikolay Samokhvalov — founder of Postgres.ai and one of the most visible Postgres consultants working. And by his own account in the HN thread, the project started the day before launch with a single prompt to Claude Opus 5, burning through roughly 3.86 billion tokens (his figure, plus GPT assistance for parts of the coding — treat the number as anecdote, not benchmark). The commit log confirms it: co-author lines credit the model, and the entire history spans about a day. The result is a clean three.js + TypeScript codebase with one runtime dependency and a strict separation between the simulation and the renderer.

Interactive explainers of this caliber — think Bartosz Ciechanowski's essays — traditionally take a domain expert months of handcrafted work, which is why so few exist. That cost just collapsed. But PGSimCity also demonstrates the two things that keep the collapse from being a disaster. First, an expert steered it: the scenario selection, the "structure is matte, meaning is neon" color semantics, the insistence that the inspector disclose every simplification — that's twenty years of operating Postgres encoded as editorial judgment, not something a model volunteers. Second, it shipped with an unusually honest disclaimer: this is an unreviewed v0.1 prototype that "almost certainly contains inaccuracies," with corrections from people who know the engine explicitly solicited as the most valuable contribution.

That second point matters more than it sounds. An AI-generated explainer's failure mode is being beautiful, confident, and subtly wrong — and a wrong intuition about checkpoints is worse than no intuition, because you'll act on it. Samokhvalov's mitigation is Apache-2.0 source, a public issue tracker, and the entire Postgres community as reviewers. Expect a wave of imitations in other domains (HN commenters were already calling for Kubernetes); the ones worth your time will be the ones that copy the correction loop, not just the aesthetic.

Model or emulator

There's a real architectural fork here worth understanding before you rely on the tool. PGSimCity is a hand-written model — no PostgreSQL source runs in your browser, numbers are scaled (1024 buffers stand in for a million), and nothing parses SQL. The alternative approach exists: PGlite compiles the actual engine to WebAssembly, so query results and plans are authoritative. But real Postgres can only show you what it exposes — catalogs, pg_stat_* views, EXPLAIN. It cannot show you the clock sweep choosing a victim frame, because there's no interface for that. The model can, precisely because it's fake. The README sketches a hybrid future where real execution drives a modelled interior; that's the correct end state, and someone will build it.

Should you spend an hour in it?

Yes, with role-appropriate expectations. If you're an application engineer who's good at your job but has never operated a database — the stated target audience — this is the fastest route I've seen to the intuitions behind connection pooling, idle-in-transaction alarms, and why your DBA gets tense about long migrations. Run it locally (npm install && npm run dev, Node 20+, WebGL2) or just use the hosted version; press T for the tour, then go straight to the long-running-transaction scenario, which the README correctly calls the most expensive lesson in the app. If you're a seasoned DBA, your job is different: file corrections. The project's accuracy ceiling is set by how many people who know the engine bother to review it.

What you shouldn't do is cite it as authority. It's a v0.1 model of Postgres, one weekend old, and its own author says so. But as a template — expert-curated, AI-built, honestly caveated, open to correction — it's the most convincing example yet of what technical education looks like when the production cost of an interactive explainer drops from months to a weekend. The interesting question is no longer whether these tools can be built. It's who's steering.