PGSimCity Turns PostgreSQL 18 into a 3D Virtual City

Developer Nikolay Samokhvalov has released PGSimCity, an open-source educational tool that models PostgreSQL 18 cluster mechanics as an interactive 3D city. Running directly in the browser via WebAssembly and PGlite, the Apache-2.0 licensed project maps low-level database operations to spatial districts. Client connections enter from the north sky into the Postmaster supervisor, moving down backend avenue. The shared_buffers pool is represented as a central 1024-frame grid, while storage excavations beneath the city display data as 8 KB page fields, B-trees, Free Space Maps, and Visibility Maps.

To ensure high architectural fidelity, the tool decouples its three.js rendering engine from core state transitions calculated in isolated TypeScript state machines. This design prevents frame-rate drops from desynchronizing the internal simulation state. Users can trace SQL statements through their parse, rewrite, plan, and execute stages, or watch background processes like the checkpointer, bgwriter, and autovacuum operate in a western maintenance yard while write-ahead logging occurs in an eastern district.

For database administrators and site reliability engineers, PGSimCity allows the simulation of critical engine failures. For example, restricting shared_buffers to 16 MB triggers clock-sweep eviction races, while limiting work_mem forces Sort and HashAggregate nodes to spill temporary files into base/pgsql_tmp. Engineers can also observe how long-running transactions depress the xmin horizon to starve autovacuum, or how heavy write bursts trigger checkpoint storms that flood pg_wal with full-page writes across the max_wal_size / (1 + checkpoint_completion_target) threshold.

The initial prototype was generated using multi-billion-token large language model prompts before being manually calibrated against the PostgreSQL REL_18_STABLE source code. Future updates on the project's roadmap include visualizing statement-pooling, aligning buffer-frame ring-sizing with PostgreSQL 18's dynamic io_combine_limit and effective_io_concurrency rules, and implementing nightly mutation testing.