PGSimCity Visualizes PostgreSQL Internals as an Interactive 3D City Simulation

Introducing PGSimCity

Nikolay Samokhvalov has launched PGSimCity, an open-source educational visualization tool. This application transforms the complex mechanics of a PostgreSQL cluster into an interactive 3D spatial simulation. It operates entirely within a web browser, requiring no local dependencies, and is available through the PGSimCity Live Visualisation sandbox.

Bridging Conceptual Gaps

PGSimCity aims to bridge the conceptual divide between high-level SQL queries and low-level kernel execution. It is designed for backend developers, site reliability engineers, and database architects to gain a clearer understanding of how PostgreSQL operates internally. The tool abstracts PostgreSQL 18 internals into distinct municipal districts, defined in its source code.

Architectural Visualization

The simulation depicts client connections entering the Postmaster supervisor, which then forks worker processes. Key PostgreSQL components like the shared_buffers pool, wal_buffers, ProcArray, lock tables, and Commit Log (CLOG) are represented as central city elements. Storage structures, including 8 KB page fields, B-trees, Free Space Maps (FSM), and Visibility Maps (VM), are visualized as excavations. Write-Ahead Logging (WAL) is routed to an eastern district with walwriter and walsender threads, while maintenance workers like checkpointer, bgwriter, and autovacuum reside in a western yard.

Simulating Operational Scenarios

PGSimCity allows users to trace statement lifecycles through parse, rewrite, plan, and execute stages. Database engineers and SREs can trigger operational pathologies, such as setting shared_buffers to 16 MB to force clock-sweep eviction races or restricting work_mem to cause temporary file spills. The tool also simulates long-running transactions leading to autovacuum starvation and table bloat, and heavy write bursts that trigger checkpoint storms.

Development and Discussion

The project maintains architectural fidelity by decoupling three.js rendering from core state transitions, ensuring internal state consistency regardless of frame rate. Samokhvalov noted that the initial prototype was built using multi-billion-token LLM prompting. The release has generated discussion on Hacker News regarding AI-assisted software architecture visualization and cognitive load.