PGSimCity

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

PGSimCity turns a PostgreSQL cluster into a city you can inspect, walk through, and break. It is 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.

Explore the live city — no install required.

PGSimCity is an independent, non-commercial educational visualization of PostgreSQL internals. It is not affiliated with, sponsored, endorsed, or approved by Electronic Arts Inc. SimCity is a trademark of Electronic Arts Inc.

This project contains no SimCity code, assets, artwork, logos, characters, audio, or game content.

How much to trust this

PGSimCity is still 0.x: early and moving. 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.

Three specialist review rounds checked PostgreSQL correctness against postgresql.org/docs and the source rather than memory; every finding was independently checked by a reviewer tasked with refuting it. A separate audit treated buildings, adjacencies, and animations as claims.

The suite has 234 tests; CI fails the build on a red test. They pin the WAL trigger point as max_wal_size / (1 + checkpoint_completion_target) at every call site, cache hit ratio as blks_hit / (blks_hit + blks_read), and the clock-sweep usage_count cap at 5.

Mistakes have been found and fixed throughout; the commit history records them. Known limitation: touch controls have been verified only in Chrome's mobile emulation. Corrections from people who know the engine are exactly what this needs: open an issue or send a pull request.

A possible future

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. The separate Query flow offers an opt-in PGlite mode: real PostgreSQL supplies parsing, plans, catalogs, buffer counters, errors and results, while its plan drives the cl