Nikolay Samokhvalov has released PGSimCity, an open-source educational visualisation tool that converts PostgreSQL cluster mechanics into an interactive 3D spatial simulation. Running entirely in the browser without local dependencies, the project is accessible via the PGSimCity Live Visualisation sandbox. It bridges the conceptual gap between high-level SQL queries and low-level kernel execution for backend developers, site reliability engineers, and database architects.
The core abstraction transforms PostgreSQL 18 internals into explicit municipal districts defined in src/world/layout.ts. Client connections enter from the north sky into the Postmaster supervisor, which forks worker processes along the backend avenue. The shared_buffers pool sits as a central 1024-frame grid alongside wal_buffers, the ProcArray, lock tables, and the Commit Log (CLOG). Storage excavations beneath the city structure heap data as 8 KB page fields, B-trees, Free Space Maps (FSM), and Visibility Maps (VM). Write-Ahead Logging is routed to the east WAL district, where walwriter and walsender threads broadcast replication streams, while the western maintenance yard houses checkpointer, bgwriter, and autovacuum workers.
-1786786155672.gif)
To maintain architectural fidelity, the presentation layer strictly decouples three.js rendering from core state transitions. Simulation mutations are computed in isolated TypeScript state machines at src/sim/state.ts using SimState, ensuring frame-rate fluctuations never desynchronize internal state.
While backend developers can trace statement lifecycles through parse, rewrite, plan, and execute stages, principal database engineers and SREs can trigger operational pathologies to inspect engine failure modes. Setting shared_buffers to 16 MB forces clock-sweep eviction races where backends write dirty victim pages before reading new data. Simulating restricted work_mem causes Sort and HashAggregate execution nodes to spill temporary files into base/pgsql_tmp.
Long-running transactions depress the xmin horizon, starving autovacuum and inducing table bloat, while heavy write bursts trigger checkpoint storms that flood pg_wal with full-page writes (FPW) across the max_wal_size / (1 + checkpoint_completion_target) threshold.
On Hacker News, the project sparked widespread discussion around AI-assisted software architecture visualisation and cognitive load, with Samokhvalov noting the initial prototype was built through multi-billion-token LLM prompting before extensive manual calibration against PostgreSQL REL_18_STABLE source code. Community feedback has driven efforts to reduce UI pop-up density and inspired spin-offs like CHSimCity for ClickHouse.
PGSimCity also incorporates PGlite to execute real, in-memory PostgreSQL compiled to WebAssembly directly inside the browser’s client thread. Looking forward, the project's ROADMAP.md outlines several core technical milestones: introducing statement-pooling visualisation modes, aligning the buffer-frame ring-sizing model with PostgreSQL 18's dynamic io_combine_limit and effective_io_concurrency rules, expanding interactive query plan paths, and implementing nightly mutation testing gates to harden the deterministic verification engine against the upstream REL_18_STABLE branch. The full codebase, documentation, and operational test suites are accessible on the PGSimCity GitHub repository under the Apache-2.0 License, encouraging developers to provide feedback, fork and contribute.