PGSimCity – Postgresの仕組みを解説する探索可能な3Dモデル
PGSimCity – an explorable 3D model that shows how Postgres works (github.com)
要約
PGSimCityは、PostgreSQLクラスタを探索、歩行、操作可能な都市として視覚化する教育用ツールです。データベース運用経験のないエンジニアが、チェックポイントによるレイテンシのスパイク、トランザクションによるテーブルの肥大化、synchronous_commitのコストなどを理解するのに役立ちます。このプロジェクトはPostgreSQLの内部構造をモデル化しており、実際のPostgreSQLコードは実行されません。
全文翻訳
PGSimCity
PostgreSQLを歩き回る。壊してみる。理由を理解する。
[画像: CI] [画像: License: Apache-2.0] [画像: Built with TypeScript] [画像: Hacker News discussion]
建物がPostgreSQLの内部構造を表し、動きがその相互作用を示す、探索可能な3D都市。クエリを追跡したり、肥大化するテーブルを調査したり、メモリ、チェックポイント、レプリケーションがボトルネックになったときに何が起こるかを見ることができます。
コミュニティディスカッション · 報道 · ここから始める · モデルの精度
インストール不要。WebGL2対応のブラウザで動作します。この都市は教育用モデルであり、実行中のPostgreSQLサーバーではありません。
[画像: ゴールデンアワーのPGSimCity:バッファプール、バックエンドアベニュー、周辺のPostgreSQL地区。クリックして都市を探索してください。]
Hacker News discussion
2026年7月27日に投稿された「PGSimCity — How PostgreSQL Works」に関するコミュニティからの質問、技術的な議論、フィードバックをご覧ください。
カウントは2026年10月11日にチェックされました。ディスカッションは当時のバージョンについて説明しています。
Press coverage
PGSimCityの選りすぐりの報道とレビュー:
| Publication | Article | Published |
|---|---|---|
| Clement Mondary · Français | PGSIMCITY : comprendre PostgreSQL en visitant une ville en 3D — 都市のビジュアル言語、インタラクティブなシナリオ、シミュレーションとPGliteの違いについての紹介。 | 2026年8月22日 |
| InfoQ | How PGSimCity Turns PostgreSQL Complexity into a Virtual City 3D Simulation — プロジェクトのアーキテクチャと教育的アプローチについてのOlimpiu Pop氏の記事。 简体中文版(田橙氏による翻訳)もあります。 | 2026年8月16日 |
| IBM Think | Someone turned PostgreSQL into a city you can walk around in — Antonia Davison氏の記事。IBM Thinkニュースレターにも掲載されました。 | 2026年7月31日 |
| Gizmodo | This SimCity-Like Visualization Turns Tech’s Most Boring Systems Into Fun — Tom Hawking氏によるハンズオンレビュー。 | 2026年7月28日 |
| GIGAZINE | データベース「PostgreSQL」がどのように実際には内部で動いているかがシムシティっぽい3Dでわかる「PGSimCity」 — 接続、クエリプランニング、バッファ、ページストレージ、WAL、バキューム、レプリケーションのスクリーンショット主導の日本語解説。 English editionもあります。 | 2026年7月28日 |
| Developers Digest | PGSimCity: A 3D Interactive City That Visualizes How PostgreSQL Works — 可視化とHacker Newsのディスカッションの概要、ユーザビリティと精度に関するコミュニティからのフィードバックを含む。 | 2026年7月27日 |
記事は公開当時のバージョンについて説明しています。
ここから始める:バキュームブロックを調査する
autovacuumが実行されているのに、テーブルが肥大化し続けています。なぜでしょうか?
- 都市を開くと、「Investigate」を選択します。これにより、ガイド付きのバキュームブロックケースが開始されます。
- テーブル、ワーカー、スナップショット、アプリケーションオーナーの証拠を検査し、記録します。介入を選択する前に、クリーンアップを妨げているものを説明してください。
- ケースが放棄されたと判断されたトランザクションを終了し、バキュームが実際にロウバージョンを回収するかどうかを確認します。スナップショットの解放自体はクリーンアップではありません。
- 「Inspect a page and its row versions」を選択して、調査をページレイアウト、タプルヘッダー、スナップショットの図に接続します。
読む時間が必要な場合は一時停止してください。その後、ガイダンスが少ないチャレンジモードを試してください。証拠とメモは現在の試行に属しており、リロードしても保持されません。
表示を選択する
| Experience | What you can do |
|---|---|
| City | エンジンを空間的に探索し、ガイドツアーに従い、バキュームインシデントを調査する。 |
| Diagnose | クエリのパスをたどり、2D診断インターフェースを通じてシミュレーションを検査する。 |
| Machine | オプトインのPGliteと2Dアーキテクチャボードを並べて、実際のSQLを実行する。測定値とモデル値は別々にラベル付けされる。 |
これをどれだけ信頼できるか
この都市はモデルであり、実行中のPostgreSQLサーバーではありません。 その数値とタイミングは、内部構造を観察可能にするためにスケーリングされています。個別のMachineとオプトインのQueryフローはPGliteを通じて実際のPostgreSQLを実行できますが、都市を本番環境のモニターに変えるわけではありません。
このプロジェクトは進化中の0.xプロトタイプであり、既知の単純化とPostgreSQLの動作に対するテストが含まれています。レビューされた参照バージョン、数式、レビュー履歴については、モデルの精度と制限を参照してください。
PGSimCityはPostgreSQL 18のメジャーラインを対象としており、PostgreSQL 18.6を参照バージョンとし、REL_18_STABLEをソースブランチとしています。4回のレビューラウンドが精度ノートに文書化されていますが、これらは完全なカバレッジを確立するものではなく、このモデルをエミュレーターにするものでもありません。PostgreSQLの不一致を報告する。
レッスンにはキーボードとテキストファーストのルートが含まれます。3Dシーンと一人称ウォークには、非視覚的な同等物はありません。タッチ検証は、物理デバイスではなくブラウザエミュレーションを使用して行われました。アクセシビリティと代替手段。
何を見ているか
| District | What it is |
|---|---|
| Client sky (north, above) | アプリケーション層から到着する接続 |
| Postmaster | スーパーバイザー。接続ごとにバックエンドをフォークし、データには一切触れない |
| Backend row | 16個のバックエンドプロセス。その照明は状態を示します — idle in transactionを含む |
Buffer pool (shared_buffers) | 最大1,024個の代表的なフレーム(デフォルトの2 GiBモデルでは256個がアクティブ;PostgreSQL 18はデフォルトで128 MiB)、wal_buffers、ProcArray、ロックテーブル、CLOG、バッファマッピングテーブルの隣 |
| The excavation | データディレクトリ:メモリが終わりストレージが始まる場所 |
| Storage (below) | ヒープファイルは8 KiBページのフィールドとして、Bツリーは実際のツリーとして、TOAST、FSMと可視性マップ、OSページキャッシュ、ディスク |
| WAL district (east) | バックエンドとwalwriterはpg_walにWALを書き込む。アーカイバは完了したセグメントをコピーし、walsenderは生成されるWALを独立してストリーミングする |
| Maintenance yard (west) | Checkpointer、background writer、autovacuumランチャーとそのワーカー |
| Standbys (south) | 2つの独立したwalreceiver、WALをリプレイするstartupプロセス、各ストリームのラグ |
| Continuity quarter (outer east and south) | WALアーカイブ、ベースバックアップ、ポイントインタイムリカバリ、遅延リプレイ、リーダーリース、再参加メカニズム |
| Query lab (above the backends) | バックエンドを選択すると、そのステートメントが展開される:parse → rewrite → plan → execute |
PostgreSQL 18のバルク読み取り戦略は、
io_combine_limit × effective_io_concurrencyで成長しますが、キャップの対象となります。この都市のアニメーションは固定の32フレームリングを使用しています。これは歴史的な単純化であり、PostgreSQL 18のサイジングルールではありません。モデルの精度とソース参照。
色はどこでも意味を持ち、装飾的ではありません:WALはアンバー、ダーティページは赤、クリーンページは青、バキュームはバイオレット、チェックポイントはピンク、background writerはティール、レプリケーションはオレンジ、ストレージはグリーン、インデックスはアクア、ロックは赤。
他に試せること
Tキーを押すと、14章からなるガイドツアーが始まります。これは、クライアントからプランニング、キャッシング、WAL、チェックポイント、バキューム、レプリケーションまでの1つの接続を追跡します。Enterキーを押して、ステートメントをトレースします。「Non-HOT UPDATE」を選択し、再生速度を遅くすると、バッファプールへの入り方、WALの作成、コミット待ちの様子が明らかになります。- シナリオメニューから「Cache thrash」を実行します。これは
shared_buffersを16 MiB(マニュアルコントロールの128 MiB最小値より下)に設定するため、クロックスイープが競合し、バックエンドは他のページを読み込む前にダーティなビクティムを書き込みます。 - 「The work_mem cliff」を実行します。固定のSortおよびHashAggregateノードは2 MiBでスピルし、4 MiBでは再プランニングなしで収まります。プライベートリザーバー、
base/pgsql_tmp、一時カウンター、レイテンシの内訳がその結果を示します。 - 「Long-running transaction」をオンにします。xminホライゾンブレードが沈み、赤くなります。autovacuumはテーブルを移動しますが、削除可能な行はゼロと報告され、
sessionsテーブルは肥大化し続けます。トランザクションを解放すると、クリーンアップが再開できます。 - 「Checkpoint storm」を実行します。チェックポインターのフライホイールが回転し始め、fsyncフェーズが震え、各チェックポイント開始後にフルページ書き込みの壁がWAL地区に flood する様子を観察します。
synchronous_commitをoffに設定し、バックエンドがcommit_waitで待機するのをやめる様子を確認します。その後、何を犠牲にしたかを読み取ります。- 「Slow replay」をオンにし、スタンバイで
sent_lsn、write_lsn、flush_lsn、replay_lsnが離れていく様子を観察します。 Gキーを押して、街を一人称視点で歩きます。確立ショットから1つのタイルに見えたバッファフレームが、頭上の構造物になります。「autovacuumレバー」または「postmasterドア」でEキーを押して操作します。内部のコントロールセンターは、都市のマップ上で6つのステートメントのうち1つをトレースできます。- オペレーターシナリオを試して、その決定を待ち、応答を選択します。スロット圧力、フェイルオーバー、リカバリにより、結果が可視化され、安全なリセットが提供されます。
コントロール
ドラッグでパン、ホイール/ピンチでズーム、Tでツアー、Kで一時停止、Hで概要に戻る、から始めます。
すべてのカメラコントロールとキーボードショートカット
都市内で?を押すと、都市コントロールマップとカラー凡例が表示されます。
Camera
| Input | Action |
|---|---|
| Left-drag | Orbitモードでパン — 地面をつかんで地図のように動かす |
Shift | |
-left-drag or Ctrl/Cmd | |
| -left-drag | 都市を中心に回転 |
| Middle-drag | Orbitモードでパン |
| Right-click or touch long-press | コンテキストメニューを開く |
| Wheel | Orbitモードでカーソルに向かってズーム · Flyモードで移動速度を調整 |
| 1 finger | Orbitモードでパン |
| 2 fingers | ピンチでズーム · ツイストで回転 · 両方を上下にドラッグして傾ける |
| First-person touch | 左親指で移動 · 右親指で視点操作 · ボタンでジャンプとしゃがみ(泳ぎながら上昇と下降) |
| Click | 建物を選択 · FlyまたはWalkモードで、視点操作のためにマウスをキャプチャする |
| Double-click | コンポーネントにフォーカス — マップスタイルのズームステップではなく、セマンティックフォーカス |
W A S D or the arrow keys | 移動 |
Shift + left/right arrow | Orbit、Fly、またはWalkモードで左/右に回転 |
Shift + up/down arrow | Orbit、Fly、またはWalkモードで上下に傾ける、または視点を上下させる |
+ / - | Orbitモードでズームイン/アウト |
Space or E · C or Q | Flyモードで上昇 · 下降;Walkモードでは、Spaceでジャンプ、Eで近くのレバー、ドア、またはコンソールを操作、Cでしゃがむ |
PageUp / PageDown | OrbitまたはFlyモードで高度を変更 |
Shift · Alt | OrbitまたはFlyモードでブースト · 精密操作;WalkモードでShiftはダッシュ |
Esc | ポインターロックを解除する |
Keys
| Key | Action |
|---|---|
F | Fly / Orbitカメラを切り替える |
G | 地面に降りて、身長1.7mで街を歩く |
H | 確立ショットに戻る |
Home | デフォルトの確立ショットに戻る |
O | 全体を真上から見下ろすオーバービュー |
T | ガイドツアー — 14章からなるコアクエリとメンテナンスパス |
Enter | Run a Queryを開く |
/ or Ctrl/Cmd+K | コマンドパレット — すべてのコンポーネント、設定、シナリオを検索する |
? | キーボードマップとカラー凡例 |
L | フローティングラベルを切り替える |
N | 夜/午後の昼光/おおよその現地時間ライトを切り替える |
M | ウォークサウンドを切り替える |
K or P | 一時停止 / 再開 |
Focus +0.1 model s, then Enter | 一時停止したワークロードを0.1モデル秒進める;一時停止状態は維持 |
, . | 遅い / 速い (0.1× – 5×) |
R | デフォルト設定にリセットする |
Esc | 最上位のオーバーレイを閉じる |
1 – 8 | ディストリクトにジャンプ:クライアント、バックエンド、バッファプール、WAL、ストレージ、クエリラボ、メンテナンス、スタンバイ |
WAL operations campaign
「Campaign」を選択するか、必須スタンバイケースと廃止されたコンシューマーチャレンジを開きます。開くと都市が保存されます。「Reset city and start」は、新しいケースを明示的に作成し、リプレイ履歴をクリアします。レコードの所有権とライブプレッシャーを記録し、介入し、その後リカバリを観察して検証します。同じスロット操作が、コンシューマーが戻る必要がある場合と廃止された場合で、なぜ異なるトレードオフを持つのかを説明してください。
観測はリクエストごとに最大300モデル秒進み、停止できます。スロットの削除は1つの保持要件を解放します。物理WALの回収は、チェックポイントの完了と他の保持者の完了を待ちます。完了は、観察されたモデル結果を記録するのであり、採点された説明や測定された学習成果ではありません。ローカルに永続化されるのは、境界付きのケース完了識別子のみです。メモ/証拠はこの試行に残り、ケースを切り替えると破棄されます。「Clear local completion history」はそのレコードを削除します。ストレージ障害が発生した場合、セッションのみの進捗が利用可能になります。
インシデントをリプレイして比較する
「Replay」を選択し、介入の前に「Save checkpoint」を選択します。結果を観察し、「Rewind to checkpoint」でモデルコントロールまたはオペレーターの決定を変更し、「Run alternative to same duration」を実行します。比較は、シードされたプレフィックスとラベル付きカウンター、現在のゲージ、モデル時間を明示的に保持します。Rewindはモデルを再構築します。保存された調査証拠とDiagnoseの前のステップボタンはナビゲーションであり、リワインドではありません。
リンクされた「Console」と「Back to city」コントロールは、現在のモデルインシデントを同じタブで転送します。これには、選択と診断トレイルが含まれます。診断サンプリングウィンドウは到着時に再開します。PGliteは引き続き個別のオプトインデータベースです。ビューを切り替える前に比較をエクスポートしてください。保存されたリプレイチェックポイント、比較ベースライン、調査メモは転送されません。ブラウザのリロード/バックはリンクされたナビゲーションではなく、期限切れまたは既に消費された転送を拒否する可能性があります。明示的な新しい都市リンクを使用して破棄してください。リプレイレコードはローカルで、境界付きで、正確なビルド固有のものであり、レコードのコピーはURL共有ではなく、レッスン回答やPGliteデータは含まれません。
プレゼンテーション画像をエクスポートする
都市のツールバーで「Export image」を選択します。モデルは都市に戻るまで一時停止します。PNGエクスポートは、現在のカメラとグラフィック品質を保持します。表示されるオブジェクト名はオプションですが、モデルの開示、バージョン、モデルクロックは常に画像フッターに残ります。リプレイ比較後、比較の説明を含めることで、シード/チェックポイント、記録された介入、元のおよび代替の期間、および資格のある結果を保持します。期間が異なる場合は、制御された比較ではないとマークされます。長いアクションリストは、明示的な省略カウントで要約されます。
デフォルトの2倍オプションは、シーンを4メガピクセルに制限します。明示的な4Kシーンオプションは、GPU制限の対象として、カメラのアスペクト比を3840 × 2160(ポートレートビュー用に回転)に合わせます。開示フッターは高さを追加します。大きなキャプチャはGPUメモリを使い果たす可能性があり、エクスポートが失敗した場合は1倍を試してください。ブラウザが自動ダウンロードをブロックした場合、準備された画像リンクが利用可能です。
構築方法
src/
core/ 共有契約、イベントバス、レジストリ、テーマ、ユーティリティ
sim/ PostgreSQLシミュレーション
world/ 都市のジオメトリ、地区ごとのモジュール
engine/ レンダラー、カメラ、フロー、ラベル、ピッキング、衝突、オーディオ
ui/ コントロール、インスペクター、ツアー、検索、テキスト説明
observability/ 同じシミュレーション上の別の診断インターフェース
machine/ 別のpsqlワークベンチと2Dアーキテクチャボード
3つのルールがそれをまとめています:
world/layout.tsが地理情報の唯一の真実の情報源です。 アンカー、テーブル定義、ルートネットワークがここにあります。どの地区も、他の地区が必要とする座標をハードコードしません。- シミュレーションはthree.jsをインポートせず、worldはシミュレーションを変更しません。 それらは
SimStateで出会います。 - レンダリングは、テーマによって異なる意味を持ちます。 夜間は構造がマットで意味がネオンですが、日中はブルームに依存せずに色相と値が意味を持ちます。ローカルタイムライトは、読者のクロックからおおよその06:00~18:00のパスをたどります。地理情報や天文緯度/季節モデルは使用しません。
スタック:three.js r185、TypeScript、Vite。three.jsは3Dアプリケーションの唯一のバンドルされたランタイム依存関係です。個別の2D QueryフローとMachineは、読者のオプトイン後にPGliteを遅延ロードする場合があります。フレームワークはなく、Plausibleアナリティクスが唯一の外部サービスです。
ブラウザコンソールでwindow.PGSIMCITYには、sim、registry、bus、rig、gfx、flowsが含まれています。数式、レビュー履歴、既知の単純化については、モデルの精度と制限を参照してください。各インスペクターは、それが重要になる時点で素材の単純化を名前で示しています。
モデルの隣にある実際のPostgreSQL
精度境界により、クロックスイープのフレームごとのビクティム選択などの内部構造を観察可能にしています。個別のQueryフローとMachineは、オプトインのPGliteモードを提供します。実際のPostgreSQLが解析、プラン、カタログ、バッファカウンター、エラー、結果を提供し、ビジュアルモデルがそれ以外の隠された内部構造を提供します。各サーフェスは、PostgreSQLが前者(公開されている)を公開し、後者(公開されていない)を公開しないため、それらのソースを別々にラベル付けしています。
ローカルで実行する
Node.js ^20.19.0 || >=22.12.0とWebGL2対応のブラウザが必要です。
npm install
npm run dev # http://localhost:5173
npm test
npm run typecheck
npm run build # dist/ に静的バンドル
npm run preview # http://localhost:4173
アプリケーションサーバーはありません。結果は静的バンドルです。3D都市とDiagnoseモデルパスは、以下に説明されているアナリティクスリクエストのみを行います。QueryフローとMachineは、明示的なクリックまたは最初のクエリ送信後に、同じオリジンのPGlite JavaScript、データ、WebAssemblyアセットをロードし、ブラウザ内でインメモリPostgreSQLを実行する場合があります。それらのモデルパスは、アナリティクスまたはPGliteがブロックされている場合でも機能します。
アナリティクスとプライバシー。 PGSimCityは、都市、オブザーバビリティ、およびMachineページのアグリゲートされたCookieフリーアナリティクスにPlausibleを使用しています。ページビュー、ユニークビジター、参照サイト、直帰率、滞在時間、およびツアー開始、再生変更、パネルオープン、ステートメントトレース、建物選択、アウトバウンドリンクフォローなどのインタラクションを記録します。PGSimCityは、名前、メールアドレス、自由形式の入力、ブラウザフィンガープリント、またはアプリケーション提供の個人データを送信せず、アナリティクスCookie、アナリティクスローカルストレージ、広告識別子、またはセッション記録を作成しません。plausible.ioをブロックしても、アプリケーションに影響を与えることなく測定が停止します。
ロードマップ
現在のマイルストーンについてはライブデリバリーロードマップを、長期的な方向性についてはテクニカルロードマップをフォローしてください。リリースで実際にリリースされたものをご確認ください。
ライセンス
PGSimCityは、PostgreSQLの内部構造に関する独立した非営利の教育用ビジュアライゼーションです。Electronic Arts Inc.とは提携、スポンサー、承認、または承認されていません。SimCityはElectronic Arts Inc.の商標です。このプロジェクトには、SimCityのコード、アセット、アートワーク、ロゴ、キャラクター、オーディオ、またはゲームコンテンツは含まれていません。
Apache-2.0。Copyright 2026 Nikolay Samokhvalov。 NOTICEを参照してください。
PostgreSQLはPostgreSQL Community Association of Canadaの商標です。PGSimCityは独立した教育プロジェクトであり、PostgreSQLプロジェクトとは提携、スポンサー、または承認されていません。