PGSimCity
An explorable 3D city that shows how Postgres actually works
What is it?
What it is
An explorable 3D educational visualization that models PostgreSQL internals as a city to demonstrate database processes and behaviors.
Why it exists
To help engineers understand complex PostgreSQL mechanisms, such as checkpoint latency, transaction bloat, and synchronous commit, through visual inspection and interaction.
Who should use it
Database engineersBackend developersDatabase administratorsSystems engineersStudents learning database internals
Who should avoid it
Users looking for a production database emulatorUsers needing exact bit-for-bit PostgreSQL replicationUsers without WebGL2 support
How it works
A quick walkthrough in plain English
How PGSimCity works
Step 1 of 3
You interact with it
Open PGSimCity, send a request, or connect it to your stack.
Features
Advantages
- High educational value for database engineers
- Visualizes complex concepts like WAL, vacuuming, and replication
- Uses a validated model checked against official PostgreSQL documentation
- Zero-install accessibility via browser
- Provides intuitive spatial understanding of data movement
Disadvantages
- It is a model, not a true emulator (no actual PostgreSQL source code running)
- Numbers are scaled for human observation rather than exact precision
- Currently in 0.x early development stage
- Touch controls verified only in Chrome mobile emulation
Installation
FAQ
What is PGSimCity and what does it show?
PGSimCity is an explorable 3D city that visualizes how a PostgreSQL cluster works internally. Each district represents a PostgreSQL subsystem (e.g., shared buffers, WAL, checkpoints, autovacuum, replication) and uses colour‑coded semantics to convey state such as dirty pages (red), clean pages (blue), WAL traffic (amber), and more.
How do I run PGSimCity locally on my machine?
You need Node.js 20+ and a WebGL2‑capable browser. Clone the repo, run `npm install`, then `npm run dev` to start the development server at http://localhost:5173. For a production build use `npm run build` and preview with `npm run preview`.
What does pressing the `T` key do in the city?
Pressing `T` starts the 14‑chapter guided tour, which walks you through a single connection’s journey from the client sky, through planning and caching, WAL, checkpoints, vacuum, and replication, explaining each step as you move.
How can I observe the effect of a long‑running transaction on table bloat?
Enable the "Long-running transaction" scenario from the menu. This causes the xmin horizon to sink and turn red, autovacuum will still scan tables but report zero removable rows while the sessions table continues to grow. Releasing the transaction allows cleanup to proceed.
What happens when I set `synchronous_commit` to `off` and why might I want to try it?
With `synchronous_commit` set to `off`, backends no longer wait in the `commit_wait` state after issuing a COMMIT, so they proceed immediately. This demonstrates the trade‑off: you gain higher throughput but risk losing the last few seconds of transactions if a crash occurs before the WAL is flushed to disk.
Where can I find the full list of keyboard controls and colour legend?
Press `?` while in the city to open the overlay that shows the complete input map (camera movement, navigation keys, scenario shortcuts) and the colour legend explaining what each hue represents (e.g., WAL amber, dirty pages red, clean pages blue, etc.).
Featured in Videos
YouTube tutorials and walkthroughs for PGSimCity
Alternatives
Similar projects ranked by category, topics, and text overlap.