PGSimCity: PostgreSQL Database Visualization

When PGSimCity rose to the top of Hacker News in July 2026 — gathering about 164 points and hundreds of comments — many readers assumed it was another gimmick of the "turn your database schema into a SimCity skyline" variety. It is not.

PGSimCity, created by database expert Nikolay Samokhvalov, is an interactive three-dimensional model of how PostgreSQL works internally. You walk through conceptual representations of the buffer pool, write-ahead log (WAL), MVCC tuple lifecycle, vacuum processes, checkpoints, and background workers. It teaches engine architecture through spatial metaphor — not by importing the public.users table and rendering foreign keys as roads.

What PGSimCity Represents

PostgreSQL internals are notoriously opaque. Developers write SQL for years without understanding why a long transaction blocks vacuum, why bloat accumulates, or how shared buffers relate to disk pages. Textbook diagrams help; PGSimCity adds navigable 3D space where subsystems are buildings, pipelines, and observable flows while simulated workloads run.

Modeled subsystems

Open source project: github.com/NikolayS/PGSimCity. Live demo: nikolays.github.io/PGSimCity.

What It Is NOT (Correcting Common Errors)

After the Hacker News thread, incorrect descriptions still circulate. Here are definitive clarifications:

• Not schema visualization: It does not connect to your production database to render tables as urban blocks sized by row count
• Not a PostgreSQL emulator: You do not point psql at PGSimCity nor expect bitwise-accurate timing of real queries
• Not a monitoring dashboard: For live metrics use pg_stat_* views, Grafana, pgHero, Datadog — PGSimCity teaches concepts, it does not replace observability
• Not a video game: The SimCity name evokes urban planning, but the goal is education — understanding engine behavior, not entertainment score

The value lies in making invisible machinery visible. When you see WAL records queue up while checkpoints fall behind, autovacuum settings stop being abstract knobs. — Recurring sentiment in the Hacker News thread, July 2026

Hacker News — #1 with ~164 Points

PGSimCity reached the top position on Hacker News in July 2026 with about 164 points — a strong result, but not the inflated "699 points" figure that appeared in early copy-paste summaries. The thread split predictably: veteran database people wished they had had it when learning; skeptics asked for quantitative fidelity benchmarks.

The HN title was explicit about the internals focus — "How PostgreSQL Works, in 3D" — reducing confusion with schema visualization tools. The most useful comments linked official MVCC documentation and shared war stories about neglected autovacuum in production.

For the original thread: search news.ycombinator.com for "PGSimCity" — actual points were on the order of ~164, not hundreds and hundreds as incorrectly reported in some AI aggregate newsletters.

The Postgres.ai community and r/postgresql picked up the link in subsequent weeks, extending visibility beyond the initial HN peak.

Samokhvalov published related technical posts on the Postgres.ai blog that deepen the same concepts visualized in the simulator — useful as a reading path after the 3D experience.

Samokhvalov's credibility helped: he is a recognized PostgreSQL consultant and educator, not an anonymous weekend demo. Supporters argued that conceptual models deliberately simplify — like physics simulations in a classroom — and that the navigable 3D format lowers the activation energy for junior DBAs and backend engineers.

What convinced the community

• Real gap between "I know how to write SQL" and "I understand why the DB caught fire at 3 AM"
• Open source, runnable in the browser without heavy installation
• Author with PostgreSQL track record (Postgres.ai, technical blog, conference talks)
• Fresh alternative to static slides and dense documentation

Nikolay Samokhvalov and the Project Philosophy

Samokhvalov built PGSimCity in response to a problem observed over years of consulting: teams operate PostgreSQL in production (RDS, Cloud SQL, Supabase, self-hosted) without a mental model of the engine. When an incident arrives — bloat, replication lag, checkpoint storm — debugging becomes trial-and-error on parameters copied from blog posts.

PGSimCity does not replace official documentation. It complements it with spatial intuition: seeing flows, queues, feedback loops. It is the same principle as network simulators or algorithm visualizers — conscious simplification in service of understanding.

How to Use PGSimCity

1. Open the demo: nikolays.github.io/PGSimCity — modern browser with WebGL
2. Navigate the city: WASD or mouse controls to explore subsystem buildings
3. Start guided scenarios: INSERT/UPDATE workloads, long transactions blocking vacuum, checkpoint spikes
4. Observe visual feedback: WAL queues growing, pages entering/leaving the buffer pool, dead tuples accumulating
5. Read tooltips and panels: each area explains the corresponding PostgreSQL concept
6. Cross-reference documentation: MVCC and routine vacuuming chapters

Local clone for development

git clone https://github.com/NikolayS/PGSimCity.git
cd PGSimCity
# Follow README for local build (typically npm install && npm run dev)

Advanced Features and Scenarios

Scenario: long transaction vs autovacuum

Start a heavy UPDATE workload, then open a transaction that stays idle with an old snapshot. Observe how autovacuum cannot reclaim dead tuples — direct visualization of the conflict that in production manifests as table bloat and disk growth.

Scenario: checkpoint under WAL pressure

Generate a write burst. Watch WAL grow and checkpoint attempt massive dirty page flush — latency spike that in pg_stat_bgwriter and logs appears as frequent "checkpoint starting".

Scenario: cache hit ratio

Compare queries hitting the buffer pool (hot data) vs cold read from simulated "disk". Immediate intuition on why shared_buffers and RAM sizing matter.

Simulation limits

• Timing is neither realtime nor calibrated to specific hardware
• Parallel query and partition pruning may be simplified or absent
• Does not replace EXPLAIN (ANALYZE, BUFFERS) on real queries

Concrete Use Cases

• Backend onboarding: New hire using an ORM for months without understanding why it generates bloat — one hour in PGSimCity before the first incident
• Junior DBA training: Preparation for tuning shared_buffers, autovacuum thresholds, max_wal_size with visual intuition
• Computer science students: Transaction isolation beyond the ACID acronym — seeing READ COMMITTED vs SERIALIZABLE in simulated action
• Managed Postgres teams: RDS/Cloud SQL/Supabase hide internals, but incidents require an engine model — PGSimCity bridges the gap
• Talks and workshops: Live demo at database conferences more memorable than 40 static slides
• Maker with IoT + PostgreSQL stack: BVRobotics projects logging telemetry to Postgres benefit from understanding why aggressive retention policies require vacuum planning

If You Need Schema Visualization

Different problem, different tools:

PGSimCity complements them; it does not compete.

Technical Detail: What to Learn from Each Subsystem

Buffer pool and locality principle

PostgreSQL reads pages from disk (typically 8KB) into the shared buffer cache. PGSimCity visualizes hit ratio: when repeated queries find pages already in RAM, disk I/O collapses. Production parameter shared_buffers (often 25% RAM on dedicated server, less on shared instances) becomes intuitive after seeing forced eviction under simulated workload.

WAL and the "write-ahead" rule

Before data page changes are durable, WAL records must be written and fsync'd. The simulator shows why synchronous_commit, streaming replication, and point-in-time recovery all depend on the same log sequence. A checkpoint that cannot keep pace generates I/O spikes — a pattern recognizable in pg_stat_bgwriter and "checkpoint starting: time" logs.

MVCC: why UPDATE does not overwrite

PostgreSQL creates a new tuple version; the old one remains until no active transaction needs it for snapshot isolation. PGSimCity makes dead tuple accumulation visible and shows the role of xid and xmin/xmax. Understanding this explains why UPDATE-heavy workloads without vacuum generate bloat even without explicit DELETEs.

VACUUM: non-optional maintenance

Autovacuum reclaims space and prevents transaction ID wraparound — a catastrophic but rare failure mode documented in the manuals. In the simulator, virtually disabling autovacuum under a long-running transaction shows uncontrolled growth — a lesson many DBAs learn only after the first real incident.

-- Real commands to try AFTER PGSimCity on a dev instance
SELECT relname, n_dead_tup, last_autovacuum
FROM pg_stat_user_tables ORDER BY n_dead_tup DESC LIMIT 10;

SELECT * FROM pg_stat_bgwriter;

Project Evolution and Community

PGSimCity is a young project with a community-driven roadmap. Contributors can extend scenarios (logical replication, partition pruning, parallel query), improve relative timing fidelity, add UI localization. The open source model on GitHub invites PRs for new "buildings" representing additional PostgreSQL subsystems.

For teams training internally, PGSimCity can become a mandatory backend onboarding module — one hour of simulation + quiz on official documentation beats weeks of theory without a mental model.

PGSimCity and Maker Projects with PostgreSQL

Many IoT projects on BVRobotics — sensor telemetry, energy box logs, Miniservices backends — persist data on PostgreSQL or TimescaleDB. When aggressive retention policies or write-heavy queries cause unexplained disk growth, PGSimCity helps understand whether the culprit is MVCC bloat, checkpoint I/O, or insufficient autovacuum rather than "PostgreSQL is slow."

You do not need to be a DBA: one hour of 3D exploration before tuning parameters on a Raspberry Pi or VPS avoids weeks of guesswork on postgresql.conf.

Quick FAQ

Can I connect PGSimCity to my RDS database?

No. There is no JDBC/DSN connection. It is a pedagogical simulation, not an operational tool.

Does it work offline?

The browser demo requires initial asset loading; a local clone can run completely offline after build.

Is it suitable for SQL beginners?

Yes, in fact it is an ideal target — as long as you pair it with practice on a real PostgreSQL instance after the simulation. PGSimCity explains the engine; it does not replace learning SELECT/JOIN.

Does Samokhvalov actively maintain the project?

Check recent commits on GitHub and the issue tracker. HN viral projects sometimes slow after launch; the community can contribute fixes and scenarios independently.

Comparison with books like "PostgreSQL 14 Internals"?

Books remain deep and precise reference. PGSimCity is a visual and interactive complement — ideal as a first step before reading hundreds of pages of dense technical text.

Conclusions

PGSimCity earned its Hacker News moment by solving a real teaching problem: PostgreSQL internals are hard to imagine from flat diagrams. By building an interactive 3D model — not a schema toy, not a complete emulator — Nikolay Samokhvalov gave the community a new on-ramp to buffer pool, WAL, MVCC, and vacuum.

If you operate PostgreSQL in production, spend an hour inside PGSimCity before the next incident. The city is fictional; the lessons are not. Then open pg_stat_user_tables on your dev instance and connect what you saw in the simulation to real numbers — that step closes the loop between intuition and operations.

Sources

• PGSimCity Demo — nikolays.github.io/PGSimCity
• PGSimCity GitHub — github.com/NikolayS/PGSimCity
• PostgreSQL MVCC — postgresql.org/docs/current/mvcc.html
• Routine Vacuuming — postgresql.org/docs/current/routine-vacuuming.html
• Write-Ahead Log — postgresql.org/docs/current/wal-intro.html
• Hacker News — front page discussion July 2026 (~164 points)
• Text alternative — "The Internals of PostgreSQL" and official wikis for post-simulation deep dive
• Nikolay Samokhvalov — postgres.ai/blog (related PostgreSQL articles)

For questions about PostgreSQL tuning in maker or IoT projects, contact the author via email.

Article updated July 2026 — corrected distinction between internals vs schema visualization and verified HN score (~164 points, #1 front page).