PGSimCity: A 3D Interactive City That Visualizes How PostgreSQL Works

Nikolay Samokhvalov released PGSimCity, an explorable 3D visualization that models PostgreSQL internals as a living city. The project hit #1 on Hacker News on July 26 with 682 points and 66 comments. The reaction was broadly positive, with a strong undercurrent of debate about AI-assisted development and how much trust to place in educational tools built by vibe coding.

What PGSimCity Actually Does#

PGSimCity is a browser-based 3D environment where every building and district corresponds to a real PostgreSQL mechanism. The central plaza is shared_buffers - 1024 page frames whose height represents their clock-sweep usage count and whose color indicates their true state. The amber district to the east is the write-ahead log. The pit under the plaza is the data directory, where heap files grow when you bloat them. A standby to the south replays what the primary sends it, always a little behind.

The color scheme is semantic throughout: WAL is amber, dirty pages are red, clean pages are blue, vacuum is violet, checkpoints are pink, the background writer is teal, replication is orange, storage is green, indexes are aqua, and locks are red. Every color carries information.

Interactive Scenarios#

You can drag shared_buffers down to 64 pages and watch the plaza thrash: usage counts collapse, the clock hand races, and backends start writing out their own dirty pages because nothing clean is left to evict. You can enable a long-running transaction and watch the xmin horizon blade sink while autovacuum trucks keep driving their route but come up empty every time - the README calls this "the most expensive lesson in the app." A checkpoint storm scenario shows the fsync phase shudder and a wall of full-page writes flood the WAL district. Toggling synchronous_commit off shows every backend stop waiting in commit_wait. Enabling slow replay makes the four LSNs on the standby pull apart.

You can press G to walk at eye level, 1.7 meters tall, through the city. A buffer plaza looks different when each frame is three times your height.

The city has 14 districts: client sky, postmaster, backend row, shared memory plaza (shared_buffers, wal_buffers, ProcArray, lock table, CLOG, buffer mapping table), the excavation (storage), WAL district, maintenance yard (checkpointer, background writer, autovacuum), standby, and query lab. Each is accessible by pressing 1 through 8. A guided tour walks through all of them in order.

How It Is Built#

The stack is three.js r185, TypeScript, and Vite. One runtime dependency. No framework, no CDN, no telemetry - a single static bundle with no network calls. The source is organized around three rules: world/layout.ts is the single source of truth for geography; the simulation never imports three.js and the world never mutates it directly (they meet at SimState); and structure is matte while meaning is neon - only emissive materials cross the bloom threshold. 115 commits, 110 GitHub stars.

PGSimCity is a model, not an emulator. No PostgreSQL source code runs in the browser. The algorithms are real - clock-sweep replacement, WAL insert/write/flush positions, checkpoint pacing against checkpoint_completion_target, autovacuum thresholds, the xmin horizon blocking cleanup, HOT updates - but the numbers are scaled so a human can watch them. 1024 buffers stand in for a million; one particle stands in for thousands of tuples. Every simplification is documented in the inspector panel.

What HN Is Saying#

The Hacker News thread is worth reading for the range of responses.

Enthusiasm for the approach. The most common reaction was genuine excitement. "Understanding how scheduling works inside a database used to require numerous architecture diagrams to explain," wrote one commenter. "I was amazed when I saw PGSimCity - it presents such a complex technical implementation process in such an engaging way." Multiple people suggested the concept could extend to Kubernetes, CPU pipelines, and other complex systems. Others noted the potential for XR and live observability dashboards.

UX feedback was specific. The top critique was that the scene is too dense for a laptop screen. One commenter wrote: "remove ~50% of the UI." Others asked for a "slow down" button, better camera controls, and a way to trace a single query end-to-end through the system. This is fair feedback for a v0.1 prototype, and the author has been responsive on GitHub issues.

The AI-assisted development debate. One commenter noted "3.86B tokens to build a visual simulator of a database that runs on a fraction of that compute." Another asked: "Considering that it has been vibe-coded with not even 48 hours passed: Is this truthful and accurate at all? Or will it lead to false conclusions?" The README handles this well - it explicitly calls itself a prototype, warns about potential inaccuracies, and invites corrections. But the community is split on whether that is enough.

Accuracy concerns. One commenter with deep PostgreSQL knowledge said the visualization actually confused them - "it is too busy to understand." Others pointed to the risk of "anti-knowledge" if the model is wrong and learners internalize incorrect mental models. The project's open-source nature and explicit invitation for corrections mitigate this, but it is a real concern for any AI-assisted educational tool.

Trademark and naming. Several commenters noted SimCity is an active EA trademark. The README addresses this with a disclaimer that PGSimCity is an independent educational project not affiliated with EA or the PostgreSQL project.

Why This Matters#

PGSimCity sits at an interesting intersection of three trends.

The first is the growing appetite for visual learning tools in systems education. Databases, operating systems, and networks are fundamentally about interacting components, and text-based documentation has limits when you need to understand how a clock-sweep eviction interacts with a checkpoint flush. PGSimCity makes that interaction visible in a way that no architecture diagram can, even if the v0.1 implementation is imperfect.

The second is the AI-assisted development question. PGSimCity was built quickly, likely with heavy AI tooling. The README admits it upfront. The debate on HN is about whether speed and accuracy can coexist in educational tools. The honest answer is that they can - with the right review process. The project's approach of labeling itself clearly and inviting domain-expert corrections is the right model for a v0.1. The key question is whether future versions can close the accuracy gap.

The third is PostgreSQL's centrality to the modern stack. Increasingly complex features - parallel query, incremental backup, logical replication - widen the gap between what operators need to know and what documentation covers. Tools that close this gap, even imperfectly, have real value. Every developer who has debugged a production checkpoint stall or a bloat-caused query regression has wished for this kind of visualization.

Sources#

• PGSimCity GitHub repository - README, architecture, simulation details. Fetched July 27, 2026.
• PGSimCity live site - Interactive 3D visualization. Fetched July 27, 2026.
• Hacker News discussion - 682 points, 66 comments. Fetched July 27, 2026.
• Three.js r185 - WebGL rendering framework used by PGSimCity.

Continue Reading#

• DuckDB Internals: Why DuckDB Is Fast - Deep dive into database internals from a different angle, covering columnar storage, vectorized execution, and what makes DuckDB's design choices work.
• PostgreSQL 19: New Features and What They Mean for Developers - PostgreSQL's latest release and the internal changes that power new capabilities.
• Rust-Powered PostgreSQL: pg_lakehouse and the Future of Database Extensions - How Rust is changing the PostgreSQL extension ecosystem.
• Webernetes: Kubernetes Ported to the Browser in TypeScript - Another browser-based visualization of a complex system, showing Kubernetes internals in your browser tab.
• Startup PostgreSQL Survival Guide - Practical operations advice for teams running PostgreSQL in production, covering the concepts PGSimCity visualizes.