- PostgreSQLの接続/バックエンド/共有メモリ/WAL/ストレージ/チェックポイント/autovacuum/レプリケーションを建物と区域で表現した3D教育用シミュレーションで、各建物とアニメーションが実際のデータベース機構に対応している
shared_buffersのclock-sweep置換、WALの記録とフラッシュ、チェックポイントのペーシング、xmin horizonとテーブル膨張など、内部動作を遅い時間スケールで観察できるよう数値と規模を縮小している- 実際のPostgreSQLコードを実行するエミュレーターではなく手書きのモデルであり、PostgreSQLのドキュメントとソースを基準に3回の専門レビューと別途の視覚的監査を経て、210件のテストで主要な計算と制限値を固定している
- バッファ不足、長時間実行トランザクション、チェックポイントの暴走、
synchronous_commit=off、遅いレプリケーション再生といったシナリオを実行し、運用設定が遅延/膨張/耐久性/レプリケーション遅延に与える変化を直接確認できる - three.js/TypeScript/Viteで作られた静的WebGL2アプリケーションであり、将来的には実際のWebAssembly版PostgreSQLのクエリ実行結果とプランを現在の内部モデルにつなぐハイブリッド構造も可能な方向として検討している
PostgreSQLを都市として表現する方法
- PGSimCityは、PostgreSQLの内部構造を歩き回って探索できる独立・非商用の教育用可視化プロジェクト
- 中央広場は
shared_buffersを表し、1,024個のページフレームの高さはclock-sweepのusage_count、色は実際のバッファ状態を表現する - 東側のオレンジ色の区域はWAL、広場の下の掘削現場はデータディレクトリ、南側の都市はプライマリサーバーが送信したWALを少し遅れて再生するスタンバイサーバーを表す
- データベースを直接運用したことのないエンジニアが、次の現象を理解できるよう設計されている
- チェックポイントがレイテンシを急増させる理由
- 終了していないトランザクションがテーブル膨張を継続させる仕組み
synchronous_commitがコミット時にどのようなコストを課すか
モデルの正確性と限界
- PGSimCityはまだ0.x段階のモデルであり、PostgreSQLエミュレーターではない
- PostgreSQLのソースコードを実行しない
- 人が変化を見られるよう数値と時間スケールを調整している
- SQLをパースしたり、実際のクエリ結果を計算したりしない
- PostgreSQLの動作の正確性を
postgresql.org/docsとソースコードに照らし合わせる3回の専門レビューを受けており、各発見事項はそれを反証するよう指定された別のレビュアーが再確認している - 建物配置/隣接関係/アニメーションが暗黙的に作り出す主張も、別途監査を受けている
- 210件のテストが含まれ、失敗したテストがあるとCIビルドは停止する
- WALベースのチェックポイント開始点:
max_wal_size / (1 + checkpoint_completion_target) - キャッシュヒット率:
blks_hit / (blks_hit + blks_read) - clock-sweepの
usage_count最大値: 5
- WALベースのチェックポイント開始点:
- 見つかった誤りと修正過程はコミット履歴に残っている
- タッチ操作はChromeのモバイルエミュレーションでのみ検証済み
- 単純化された動作は、各コンポーネントのinspectorで明示している
実際のエンジンと組み合わせる可能性
- 現在は、clock-sweepがフレームごとに犠牲ページを選ぶ過程のようにPostgreSQLの外部に公開されない内部ステップを見せるため、手書きのシミュレーションを使っている
- PGliteのように実際のPostgreSQLをWebAssemblyで実行すれば、クエリ結果と実行計画を実際のエンジンに任せられる
- 実際のエンジンがブラウザで提供できる情報は、catalog、
pg_stat_*ビュー、EXPLAINなどPostgreSQLが外部に公開する範囲に限られる - 実際の実行と計画がモデル内部の動きを駆動するハイブリッド方式も可能だが、確定した開発上の約束ではなく将来の方向性である
都市の区域と構成要素
- Client sky: アプリケーション層から入ってくる接続
- Postmaster: 接続ごとにバックエンドプロセスを生成するが、ユーザーデータには直接アクセスしない監督プロセス
- Backend row: 16個のバックエンドプロセスで、照明により
idle in transactionを含む現在の状態を表示する - Shared memory plaza
shared_bufferswal_buffers- ProcArray
- ロックテーブル
- CLOG
- バッファマッピングテーブル
- The excavation: メモリ領域とディスク領域の境界
- Storage
- 8KiBページで構成されたheapファイル
- 実際の木の形をしたB-tree
- TOAST
- FSM
- visibility map
- OSページキャッシュ
- ディスク
- WAL district: walwriter →
pg_walセグメント → archiver → walsender - Maintenance yard: checkpointer/background writer/autovacuum launcherとworker
- Standby: walreceiver/WALを再生するstartupプロセス/2つのプロセス間の遅延
- Query lab: 選択したバックエンドの文をparse → rewrite → plan → executeの段階に展開して見せる
色と視覚的な意味
- 色は装飾ではなく、状態とメカニズムを伝える
- WAL: オレンジ色
- dirty page: 赤色
- clean page: 青色
- vacuum: 紫色
- checkpoint: ピンク色
- background writer: 青緑色
- replication: オレンジ色
- storage: 緑色
- index: アクア色
- lock: 赤色
- 構造物はマットに、意味を持つ要素はネオンで表現し、発光マテリアルだけがbloomのしきい値を超えるよう構成している
自分で試せるシナリオ
shared_buffersを64ページに縮小usage_countが崩れ、clock handが高速に循環する- 削除できるclean pageが不足し、バックエンドが自分のdirty pageを直接書き込み始める
- Long-running transactionを有効化
- ProcArrayのxmin horizonが下がり、赤色に変わる
- autovacuum workerが巡回し続けるが、掃除対象のタプルを削除できない
sessionsテーブルが膨張し、回復しない
- Checkpoint stormを実行
- checkpointerが加速し、fsync段階が揺れる
- その後、full-page writeがWAL区域へ大量に流入する
synchronous_commit=offを設定- バックエンドが
commit_waitで待機しなくなる - 即時応答と引き換えにした耐久性条件もあわせて確認できる
- バックエンドが
- Slow replayを有効化
- スタンバイサーバーのsent/written/flushed/applied LSNが互いに広がる
- この差は
pg_stat_replicationで観察するレプリケーション遅延に対応する
Gキーを押すと高さ1.7mの歩行視点に降り、バッファと建物を目線の高さで眺められる
探索と操作
- マウスとタッチ操作
- 左ドラッグ: 地図をつかんで動かすように移動
- 右ドラッグ: 都市の周囲を回転
- ホイール: カーソル位置を基準に拡大/縮小
- 1本指: 移動
- 2本指: 拡大/縮小、回転、傾き変更
- 移動モード
W/A/S/Dまたは矢印キー: 移動Space/E: 上昇C/Q: 下降Shift: 高速移動Alt: 精密移動
- 主なキー
F: 飛行/軌道カメラ切り替えG: 地上歩行H: 初期の全景へ戻るT: 都市全体を案内する14章のツアー/またはCtrl-K: コンポーネント/設定/シナリオ検索?: キーボードマップと色の凡例KまたはP: 一時停止/再開,/.: 0.1×〜5×の速度調整1〜8: clients/backends/shared buffers/WAL/storage/checkpointer/autovacuum/standby区域へ移動
ライセンスと商標
- Apache-2.0ライセンスで配布されている
- SimCityのコード/アセット/画像/ロゴ/キャラクター/音声/ゲームコンテンツを含まない
- Electronic ArtsおよびPostgreSQLプロジェクトとの提携/後援/承認関係のない独立した教育プロジェクトである
1件のコメント
Hacker Newsの意見
ここで試みている方向性は本当に気に入っていますが、ツアー機能にはノイズが多すぎます。画面上で無数の箱や要素が絶えず変わり、何が起きているのか把握しにくく、次のトピックへ自動で切り替えるのではなく、ユーザーが自分で進められるようにすべきです
一度に押し寄せる情報を受け身で眺めているだけだと混乱します。技術の内部動作を見せるというアプローチ自体は有用ですが、データやグラフ、情報ボックスを増やすより、焦点を絞る必要があります
人間の脳の限界は、開発者にもユーザーにも同じです。LLMで複雑なものを作れるとしても、装飾的な複雑さであるグリーブルが一定の水準を超えると、他の人間が体験するよう設計されたものには感じられません
LLMなしで作っていたなら、開発者自身が全体のメンタルモデルを頭の中に収めきれず、複雑さを減らしていたはずですが、ユーザーも同じ限界を持っています。アニメーションや点滅する光の比喩を理解しようとしても、意味が埋もれてしまいます
新しいプロセスがなぜ管を通って建物に到着する四角形なのか、その後ピンボールのスイッチが赤く光るのか分かりません。何かをクリックすると、
"sessions is the victim"という小さなポップアップが段落とともに一瞬現れて消え、さらに混乱します教育用ではないのかもしれませんし、単に私の知識不足の可能性もありますが、ただ不思議な作品として見るならかなりクールです
最初の画面を見た瞬間、クエリを入力すれば入力の構文解析から結果の返却まで全体の流れを段階的に見せてくれ、クエリとは無関係に並列で常時動いている自律プロセスも理解できるのだろうと期待しました
試み自体は素晴らしいですが、どこから始めてどこで終えればいいのか分かりません
Tを押してみるといいですデータベース内部のスケジューリングを理解するには、以前なら大量のアーキテクチャ図が必要でした。PGSimCityは複雑な技術実装の過程を興味深く表現していて驚きます
オープンソースである以上、同じ発想をクラウドコンピューティングやKubernetesのような他の領域にも再利用できそうです
gdbでプログラムをデバッグしながら深く集中しているときに頭の中で描くものと非常によく似ています。こうしたグラフィックでVRデバッグを体験できるなら、コードベースを学ぶのにこれ以上の方法はなさそうです
任意のコードから3Dマップを生成すると、どの程度よい体験を作れるのか気になります
48時間にも満たないバイブコーディングの成果物だとすれば、内容が本当に正確なのか疑問です。誤った結論や半知識につながる危険はないのか気になります
"Rendering The First Frame..."が"Reticulating Splines..."ではないなんて信じがたいです。UIはかっこいいですPostgresの内部構造はかなりよく知っていますが、むしろ混乱しました。画面があまりに忙しくて理解しにくく、少なくとも速度を下げるボタンがあるとよさそうです
transactions/sでも確認しました見た目は本当にかっこいいです。数週間前から、Beam VMを工場の床のように歩き回り、モジュールと関数のつながり、実行負荷、火花が散るエラーを確認できるBeam用Doomをバイブコーディングし始めました
まだあまり作れていませんが、VRヘッドセットを買う口実として開発を続けたいです
AIの助けを借りて作られたように見えます。私もAIを活用して破滅的忘却を説明する似たようなバイブコーディングプロジェクトを進めました
今では何かを本当に学びたいなら、いつでもAIの助けを得られるので満足しています。以前は良い資料を探すのが難しかったのですが、今やボトルネックは資料ではなく、個人の集中力と主体性へ移っています