A new open-source tool called PGSimCity lets developers explore PostgreSQL cluster mechanics as a living, interactive 3D city. Released by developer Nikolay Samokhvalov, the educational visualization runs entirely in the browser with no local dependencies. It is accessible through the PGSimCity Live Visualisation sandbox, where users can watch queries flow through simulated streets, districts, and storage excavations.
The tool aims to bridge the gap between high-level SQL queries and low-level kernel execution. Its target audience includes backend developers, site reliability engineers, and database architects. The core abstraction maps PostgreSQL 18 internals to municipal districts, turning abstract processes into visible, spatial structures. Olimpiu Pop wrote about the release for InfoQ on Aug 16, 2026, detailing how the city metaphor makes complex database mechanics tangible.
A City Built From Database Internals
The simulation's districts are defined in src/world/layout.ts. Client connections enter from the north sky into the Postmaster supervisor, which forks worker processes along backend avenue. At the center sits the shared_buffers pool, a 1024-frame grid. Other central elements include wal_buffers, ProcArray, lock tables, and the Commit Log (CLOG).
Beneath the city, storage excavations represent heap data as 8 KB page fields, alongside B-trees, Free Space Maps (FSM), and Visibility Maps (VM). Write-Ahead Logging routes to the east WAL district, where walwriter and walsender threads broadcast replication streams. The western maintenance yard houses the checkpointer, bgwriter, and autovacuum workers. Each component occupies a place, making the entire lifecycle of a query visible.
Fidelity Through Decoupled Design
The presentation layer decouples three.js rendering from core state transitions. Simulation mutations are computed in isolated TypeScript state machines at src/sim/state.ts using SimState. This design choice ensures frame-rate fluctuations never desynchronize internal state. Backend developers can trace statement lifecycles through parse, rewrite, plan, and execute stages without losing accuracy.
Samokhvalov noted that the initial prototype was built through multi-billion-token LLM prompting. The prototype was then manually calibrated against the PostgreSQL REL_18_STABLE source code. That calibration process grounded the simulation in real behavior, not just visual metaphor. The result is a tool that does not merely illustrate concepts but simulates them with operational precision.
Simulating Real Operational Pathologies
Stay ahead of the AI curve
The most important updates, news, and content — delivered weekly.
No spam. Unsubscribe anytime.
Principal database engineers and SREs can trigger operational pathologies to learn failure modes. Setting shared_buffers to 16 MB forces clock-sweep eviction races. In those races, backends write dirty victim pages before reading new data. Simulating a 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. Heavy write bursts trigger checkpoint storms that flood pg_wal with full-page writes (FPW). The FPW threshold is calculated as max_wal_size / (1 + checkpoint_completion_target). Each scenario gives users a safe space to see how PostgreSQL degrades under stress.
Community Feedback Shapes the Roadmap
The release sparked discussion on Hacker News about AI-assisted software architecture visualization and cognitive load. Community feedback led to a reduction in UI pop-up density, making the tool easier to read. That same feedback inspired a spin-off project called CHSimCity, aimed at ClickHouse, the column-oriented database management system.
PGSimCity incorporates PGlite to execute real, in-memory PostgreSQL compiled to WebAssembly in the browser's client thread. This means the simulation runs actual PostgreSQL code, not just a model of it. The project's ROADMAP.md outlines several core technical milestones. These include statement-pooling visualization 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.
Licensing and Contribution
The full codebase, documentation, and operational test suites are available on the PGSimCity GitHub repository. The project is licensed under the Apache-2.0 License, a permissive open-source license. Developers are encouraged to provide feedback, fork, and contribute to the project.
The tool represents a shift in how database education can work. Instead of reading about buffer pools and WAL segments, developers can watch them operate in real time. The city metaphor turns invisible processes into something explorable. For teams debugging performance issues or learning PostgreSQL internals, PGSimCity offers a new way to see what is happening under the hood.