How PGSimCity Turns PostgreSQL Complexity Into a Virtual City 3D Simulation

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, it is accessible via the PGSimCity Live Visualisation sandbox. The project 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. Key components include shared_buffers as a central 1024-frame grid, wal_buffers, ProcArray, lock tables, and the Commit Log (CLOG). Storage details involve 8 KB page fields, B-trees, Free Space Maps (FSM), and Visibility Maps (VM). Write-Ahead Logging is routed to the east WAL district, with walwriter and walsender threads broadcasting replication streams. The western maintenance yard houses checkpointer, bgwriter, and autovacuum workers. The presentation layer decouples three.js rendering from core state transitions using TypeScript state machines at src/sim/state.ts to ensure frame-rate stability. Developers can trace statement lifecycles through parse, rewrite, plan, and execute stages, while SREs can simulate operational pathologies. Configurations like setting shared_buffers to 16 MB force clock-sweep eviction races, and restricted work_mem causes Sort and HashAggregate spills. Long-running transactions starve autovacuum, inducing table bloat, while heavy write bursts trigger checkpoint storms. The project sparked discussion on Hacker News about AI-assisted software architecture visualisation and cognitive load. Samokhvalov built the initial prototype using multi-billion-token LLM prompting before manual calibration against PostgreSQL REL_18_STABLE source code. Community feedback has reduced UI pop-up density and inspired spin-offs like CHSimCity for ClickHouse. PGSimCity also incorporates PGlite to execute real PostgreSQL compiled to WebAssembly directly in the browser. The ROADMAP.md outlines milestones such as introducing statement-pooling visualisation, aligning buffer-frame ring-sizing with PostgreSQL 18’s dynamic io_combine_limit and effective_io_concurrency rules, expanding interactive query plan paths, and implementing nightly mutation testing gates. The full codebase, documentation, and operational test suites are available on the PGSimCity GitHub repository under the Apache-2.0 License, encouraging developer contributions.