PGSimCity

Кластер PostgreSQL, визуализированный в виде города, вокруг которого можно вращаться, летать или ходить на уровне глаз, где подсистемы движка представлены районами. Заявленная Николаем Самохваловым аудитория - инженеры, компетентные в своей работе, но никогда не администрировавшие базы данных: те, кому нужно понимать, почему checkpoint вызывает всплески задержек, почему одна забытая транзакция навсегда раздувает таблицу и какую цену они платят за synchronous_commit. Проект работает прямо в браузере без установки.

Сопоставление достаточно буквальное, чтобы быть полезным. Postmaster делает fork одного backend-процесса на каждое соединение и никогда не касается данных. Шестнадцать backend-процессов стоят в ряд, и их подсветка - это и есть их состояние, включая idle in transaction. shared_buffers - это площадь из 1024 репрезентативных фреймов рядом с wal_buffers, ProcArray, таблицей блокировок, CLOG и таблицей сопоставления буферов. Под ней находится котлован - директория данных, где заканчивается память и начинается хранилище; там лежат heap-файлы в виде полей из 8-КиБ страниц, B-деревья, отрисованные как настоящие деревья, TOAST, FSM и visibility map, кэш страниц ОС и диски. Район WAL уходит на восток (walwriter, сегменты pg_wal, archiver, walsender), хозяйственный двор - на запад (checkpointer, background writer, autovacuum launcher и workers), а standby расположен на юге со своим walreceiver, процессом startup, воспроизводящим WAL, и отставанием между ними. Внешний квартал непрерывности охватывает архив WAL, базовые резервные копии, PITR, второй отложенный standby, а также механизмы leader lease и повторного присоединения.

Цвет здесь семантический и никогда не служит просто декорацией: янтарный для WAL, красный для "грязных" страниц (dirty pages), синий для чистых страниц, фиолетовый для vacuum, розовый для checkpoint'ов, бирюзовый для background writer, оранжевый для репликации, зелёный для хранилища, цвет морской волны для индексов, красный для блокировок.

Что модель действительно может показать

Сценарии - это то, ради чего модель вообще создавалась: они позволяют наблюдать за обычно невидимыми взаимодействиями с понятной человеку скоростью.

Cache thrash устанавливает shared_buffers в 16 МиБ, что ниже порога в 128 МиБ для ручной настройки, так что clock sweep начинает гонку, и backend'ам приходится самим сбрасывать на диск свои "грязные" страницы-жертвы, прежде чем прочитать следующую страницу.
Long-running transaction опускает лезвие горизонта xmin и окрашивает его в красный цвет. Autovacuum по-прежнему обходит таблицы и сообщает о нуле удаляемых строк, пока таблица sessions продолжает раздуваться. Стоит завершить транзакцию, как очистка возобновляется.
Checkpoint storm раскручивает маховик checkpointer'а, сотрясает систему на фазе fsync и заливает район WAL полностраничными записями (full-page writes) после начала каждого checkpoint'а.
Slow replay разносит значения sent_lsn, write_lsn, flush_lsn и replay_lsn на standby.
Переключение synchronous_commit в off избавляет backend'ы от ожидания в commit_wait, после чего страница показывает, чем именно пришлось пожертвовать.

Enter запускает трассировку отдельного запроса; выбор Non-HOT UPDATE с замедленным воспроизведением показывает, как запрос попадает в buffer pool, генерирует WAL и ожидает коммита. T запускает интерактивный тур из 14 глав, прослеживая путь одного соединения от клиента через планирование, кэширование, WAL, checkpoint'ы, vacuum и репликацию. G опускает камеру на высоту 1,7 м и позволяет ходить пешком: в этот момент буферный фрейм, казавшийся маленькой плиткой на общем плане, превращается в нависающее сверху здание.

Сборка

three.js r185, TypeScript, Vite. three.js - единственная собранная в бандл runtime-зависимость 3D-приложения, фреймворков нет, а Plausible - единственный внешний сервис. npm install && npm run dev; результат сборки - статический бандл без сервера приложений.

Архитектуру исходного кода удерживают три правила, и именно они представляют интерес:

world/layout.ts - единый источник правды для географии: привязки, определения таблиц, сеть маршрутов. Ни один район не хардкодит координаты, нужные другому району.
Симуляция никогда не импортирует three.js, а мир никогда не мутирует симуляцию. Они встречаются в SimState.
Отрисовка передаёт смысл по-разному в зависимости от темы: ночью структуры матовые, а смысл выделен неоном; при дневном свете оттенок и яркость передают значение без опоры на bloom-эффект.

window.PGSIMCITY предоставляет доступ к sim, registry, bus, rig, gfx и flows, если вы предпочитаете управлять городом из консоли. Отдельный сценарий 2D Query может лениво загружать PGlite по явному клику: тогда реальный PostgreSQL обеспечивает парсинг, планы, каталоги, счётчики буферов, ошибки и результаты, пока его план управляет ближайшим смоделированным внутренним путём - страница помечает эти два источника отдельно, так как PostgreSQL отдаёт первое, но не второе.

Насколько этому можно верить

Это модель, а не эмулятор. Исходный код PostgreSQL здесь не выполняется, а числа смасштабированы так, чтобы человек успевал за ними следить. В README заявляется о серьёзной верификации: три раунда рецензирования специалистами для проверки корректности по postgresql.org/docs и исходному коду, а не по памяти; каждая находка независимо перепроверялась рецензентом с задачей её опровергнуть; плюс отдельный аудит, рассматривающий здания, смежность и анимации как проверяемые утверждения. Набор из 234 тестов ломает CI при падении, фиксируя точку срабатывания WAL как max_wal_size / (1 + checkpoint_completion_target) в каждом месте вызова, cache hit ratio как blks_hit / (blks_hit + blks_read), а ограничение usage_count для clock-sweep - на уровне 5.

Сам работающий сайт высказывается прямолинейнее, чем README. Его баннер гласит: "Early, unreviewed prototype. It almost certainly contains inaccuracies in both the model and explanations." Настолько сильное расхождение двух самооценок в рамках одного проекта версии 0.x заставляет насторожиться, и именно поэтому проект находится в watchlist, а не рекомендуется безоговорочно. Известное ограничение, названное автором: сенсорное управление проверялось только в мобильной эмуляции Chrome.

Связанные страницы

postgresql - страница сущности для моделируемого движка. linux-7-postgres-regression служит отличным дополнением: там рассматривается работа buffer pool, которую визуализирует этот проект, когда выбор жертвы в clock-sweep функцией StrategyGetBuffer под единым глобальным spinlock'ом перестаёт быть деталью реализации и вдвое снижает пропускную способность на машине с 96 vCPU. PGSimCity отрисовывает этот цикл выбора и закрепляет ограничение usage_count в тесте; регрессия же показывает, что происходит, когда нарушаются допущения относительно критической секции этого цикла.

Репозиторий: NikolayS/PGSimCity, Apache-2.0, copyright 2026 Nikolay Samokhvalov. Демо: nikolays.github.io/PGSimCity. План развития, включая список известных неточностей и то, что сознательно не планируется делать, находится в ROADMAP.md. Количество звёзд на момент ingest'а не зафиксировано.