PGSimCity is taking an unusual approach to PostgreSQL education: it turns the database’s internal machinery into a browser-based virtual city. Released by Nikolay Samokhvalov, the open-source visualisation tool aims to make PostgreSQL cluster mechanics easier to understand for backend developers, site reliability engineers, and database architects by mapping core concepts onto a 3D simulation that runs entirely in the browser.
PGSimCity turns PostgreSQL internals into a city model
The project presents PostgreSQL 18 internals as a municipal layout, with distinct “districts” representing key subsystems. According to the source material, client connections enter from the north sky into the Postmaster supervisor, which then forks worker processes along a backend avenue. Shared memory and process coordination are represented in the city’s center, where shared_buffers appears as a 1024-frame grid alongside wal_buffers, the ProcArray, lock tables, and the Commit Log, or CLOG.
Below the surface, PGSimCity models storage as excavations and underground structures. Heap data is shown as 8 KB page fields, while B-trees, Free Space Maps, and Visibility Maps are placed in their own zones. Write-Ahead Logging is routed to an eastern WAL district, where walwriter and walsender threads broadcast replication streams, and maintenance components such as checkpointer, bgwriter, and autovacuum occupy a western yard.
A browser-only tool with no local setup
One of PGSimCity’s practical advantages is accessibility. The project runs entirely in the browser and requires no local dependencies, which lowers the barrier for readers who want to explore PostgreSQL behavior without building or installing database tooling first. The article notes that the live experience is available through the PGSimCity Live Visualisation sandbox.
This browser-first design makes the simulator easier to share in learning environments, demos, and team discussions. It also means the tool is positioned less as a production diagnostics platform and more as a visual teaching aid that helps users connect SQL-level actions to lower-level database processes.
How PGSimCity keeps simulation state reliable
The source says the project separates rendering from simulation logic to keep the model deterministic. The presentation layer uses three.js for graphics, but state transitions are handled independently in TypeScript state machines in src/sim/state.ts using SimState. That separation is meant to prevent frame-rate changes from desynchronizing the underlying simulation.
This kind of architecture matters in a visualization tool because the visual output must remain faithful even when a browser’s performance fluctuates. By isolating state changes from the rendering loop, PGSimCity can preserve internal consistency while still delivering a responsive 3D experience.
Educational focus for developers and SREs
PGSimCity is designed to bridge a common gap in PostgreSQL understanding: the space between high-level SQL statements and the engine’s internal execution. The project lets users follow a statement lifecycle through parse, rewrite, plan, and execute stages, making it easier to see how a query progresses inside the database.
For principal database engineers and SREs, the tool goes further by simulating operational failures and pathological scenarios. That makes it useful not just for explaining normal execution, but for observing how PostgreSQL behaves under stress.
Simulating pressure points inside PostgreSQL
The source highlights several scenarios that users can trigger in the simulation. Setting shared_buffers to 16 MB, for example, forces clock-sweep eviction races, where backends must write dirty victim pages before reading new data. That helps illustrate how memory pressure can affect page management and buffer replacement behavior.
Reducing work_mem leads Sort and HashAggregate nodes to spill temporary files into base/pgsql_tmp. In the simulator, this makes it easier to understand why query plans that look efficient on paper can become expensive when memory limits are too tight.
Other scenarios show the impact of long-running transactions and heavy write workloads:
- Long-running transactions depress the
xminhorizon, which can starve autovacuum and cause table bloat. - Heavy write bursts can trigger checkpoint storms, flooding
pg_walwith full-page writes. - Checkpoint behavior is shown relative to the
max_wal_size / (1 + checkpoint_completion_target)threshold described in the source.
These examples make the simulator more than a static diagram. It is meant to show cause and effect across PostgreSQL subsystems, especially where memory settings, vacuum behavior, and WAL activity interact in ways that are hard to observe directly from a query interface alone.
Built with WebAssembly PostgreSQL in the browser
The project also incorporates PGlite, which allows real PostgreSQL to run in memory inside the browser using WebAssembly. According to the source, this means PGSimCity is not only a conceptual model; it also executes actual PostgreSQL within the client thread.
That combination of a simulation layer and a real embedded database gives the project a more grounded feel than a purely illustrative animation. It lets users explore the engine visually while still working with database behavior that is tied to PostgreSQL itself.
Community interest and AI-assisted development
The source material says the project drew widespread discussion on Hacker News, especially around AI-assisted software architecture visualisation and cognitive load. Samokhvalov said the initial prototype was built through multi-billion-token LLM prompting, followed by extensive manual calibration against PostgreSQL REL_18_STABLE source code.
That detail is notable because it reflects a broader trend in developer tools: using AI to bootstrap complex systems, then refining them carefully against real upstream code. The report also says community feedback has already influenced the project, including efforts to reduce UI pop-up density and the emergence of a spin-off called CHSimCity for ClickHouse.
Roadmap items point to deeper modeling
The project’s ROADMAP.md includes several technical milestones, according to the source. Planned additions include statement-pooling visualisation modes, a buffer-frame ring-sizing model aligned with PostgreSQL 18’s dynamic io_combine_limit and effective_io_concurrency rules, more interactive query plan paths, and nightly mutation testing gates to strengthen the deterministic verification engine against the upstream REL_18_STABLE branch.
Those items suggest the project’s scope may continue to expand beyond a simple educational city map. If the roadmap is delivered as described, PGSimCity could become a richer environment for exploring how PostgreSQL tuning and runtime behavior interact across different workload patterns.
Why PGSimCity stands out
Plenty of database tools show metrics, logs, or diagrams. PGSimCity is different because it translates PostgreSQL’s internal structure into a place users can walk through visually, even if only virtually. That framing may make intimidating concepts more approachable, particularly for learners who struggle to connect abstract system terms with actual engine behavior.
At the same time, the project is careful to remain technically specific. It does not just use a city theme for decoration; it maps concrete PostgreSQL components, memory structures, worker processes, and failure modes into a coherent model that reflects how the database operates.
PGSimCity is available as open source under the Apache-2.0 License, and the source notes that the codebase, documentation, and operational test suites are published on GitHub. For developers interested in PostgreSQL internals, interactive visualisation, or browser-native tooling, it offers a distinctive way to study a database engine that is usually understood through text logs, docs, and command-line output.
Source: Original report
Was this helpful?
Explore more: Software Development More Software Development Tech News
Last Modified: August 17, 2026 at 1:52 am
2 views
