PGSimCity - Memvisualisasikan cara kerja PostgreSQL sebagai kota 3D yang bisa dijelajahi

 (nikolays.github.io)
2 poin oleh GN⁺ 3 jam lalu | 1 komentar | Bagikan ke WhatsApp
  • Simulasi edukatif 3D yang merepresentasikan koneksi/backend/shared memory/WAL/storage/checkpoint/autovacuum/replikasi PostgreSQL sebagai bangunan dan distrik, dengan tiap bangunan dan animasi dipetakan ke mekanisme database yang nyata
  • Angka dan skala diperkecil agar perilaku internal bisa diamati dalam skala waktu yang lambat, seperti penggantian clock-sweep pada shared_buffers, pencatatan dan flush WAL, checkpoint pacing, horizon xmin, dan pembengkakan tabel
  • Ini bukan emulator yang menjalankan kode PostgreSQL asli, melainkan model yang ditulis manual; telah melalui tiga kali peninjauan ahli dan audit visual terpisah berdasarkan dokumentasi dan source PostgreSQL, serta mengunci perhitungan utama dan nilai batas dengan 210 pengujian
  • Anda dapat menjalankan skenario seperti kekurangan buffer, transaksi berjalan lama, badai checkpoint, synchronous_commit=off, dan replay replikasi yang lambat untuk melihat langsung bagaimana pengaturan operasional memengaruhi latensi/pembengkakan/durabilitas/lag replikasi
  • Aplikasi WebGL2 statis yang dibuat dengan three.js/TypeScript/Vite, dan ke depannya juga mempertimbangkan arah arsitektur hibrida yang menghubungkan hasil eksekusi kueri dan rencana dari PostgreSQL WebAssembly nyata ke model internal saat ini

Cara merepresentasikan PostgreSQL sebagai kota

  • PGSimCity adalah proyek visualisasi edukatif independen/nonkomersial yang memungkinkan Anda berjalan-jalan dan menjelajahi struktur internal PostgreSQL
  • Alun-alun pusat merepresentasikan shared_buffers; tinggi 1.024 page frame menunjukkan clock-sweep usage_count, dan warnanya menampilkan status buffer yang sebenarnya
  • Distrik oranye di timur adalah WAL, area galian di bawah alun-alun adalah direktori data, dan kota di selatan merepresentasikan server standby yang memutar ulang WAL dari server utama dengan sedikit keterlambatan
  • Dirancang agar engineer yang belum pernah mengoperasikan database secara langsung dapat memahami fenomena berikut
    • Mengapa checkpoint dapat menyebabkan lonjakan latensi
    • Bagaimana transaksi yang tidak selesai terus menyebabkan pembengkakan tabel
    • Biaya apa yang dikenakan synchronous_commit saat commit

Akurasi dan batasan model

  • PGSimCity masih merupakan model tahap 0.x, bukan emulator PostgreSQL
    • Tidak menjalankan source code PostgreSQL
    • Menyesuaikan angka dan skala waktu agar perubahan bisa dilihat manusia
    • Tidak melakukan parsing SQL atau menghitung hasil kueri nyata
  • Telah melalui tiga kali peninjauan ahli yang mencocokkan akurasi perilaku PostgreSQL dengan postgresql.org/docs dan source code, dan setiap temuan diperiksa ulang oleh peninjau terpisah yang ditugaskan untuk membantahnya
  • Klaim implisit yang muncul dari tata letak bangunan/hubungan kedekatan/animasi juga diaudit secara terpisah
  • Mencakup 210 pengujian, dan build CI akan dihentikan jika ada pengujian yang gagal
    • Titik awal checkpoint berbasis WAL: max_wal_size / (1 + checkpoint_completion_target)
    • Cache hit ratio: blks_hit / (blks_hit + blks_read)
    • Nilai maksimum clock-sweep usage_count: 5
  • Kesalahan yang ditemukan dan proses perbaikannya tercatat dalam riwayat commit
  • Operasi sentuh baru diverifikasi di emulasi mobile Chrome
  • Perilaku yang disederhanakan dijelaskan secara eksplisit di inspector tiap komponen

Kemungkinan dipadukan dengan engine nyata

  • Saat ini menggunakan simulasi yang ditulis langsung untuk menampilkan langkah internal yang tidak diekspos di luar PostgreSQL, seperti proses clock-sweep memilih halaman korban per frame
  • Jika PostgreSQL nyata dijalankan di WebAssembly seperti PGlite, hasil kueri dan execution plan bisa diserahkan ke engine nyata
  • Informasi yang dapat disediakan engine nyata di browser terbatas pada apa yang diekspos PostgreSQL ke luar, seperti catalog, view pg_stat_*, dan EXPLAIN
  • Pendekatan hibrida di mana eksekusi nyata dan plan nyata menggerakkan pergerakan di dalam model juga dimungkinkan, tetapi itu adalah arah masa depan, bukan komitmen pengembangan yang sudah pasti

Distrik dan komponen kota

  • Client sky: koneksi yang masuk dari lapisan aplikasi
  • Postmaster: proses pengawas yang membuat proses backend untuk tiap koneksi, tetapi tidak mengakses data pengguna secara langsung
  • Backend row: 16 proses backend, dengan pencahayaan yang menampilkan status saat ini termasuk idle in transaction
  • Shared memory plaza
    • shared_buffers
    • wal_buffers
    • ProcArray
    • tabel lock
    • CLOG
    • tabel pemetaan buffer
  • The excavation: batas antara area memori dan area disk
  • Storage
    • file heap yang terdiri dari halaman 8KiB
    • B-tree dalam bentuk pohon yang nyata
    • TOAST
    • FSM
    • visibility map
    • page cache sistem operasi
    • disk
  • WAL district: walwriter → pg_wal segment → archiver → walsender
  • Maintenance yard: checkpointer/background writer/autovacuum launcher dan worker
  • Standby: walreceiver/proses startup yang memutar ulang WAL/lag antara kedua proses itu
  • Query lab: menampilkan statement backend yang dipilih dalam tahapan parse → rewrite → plan → execute

Warna dan makna visual

  • Warna bukan dekorasi, melainkan menyampaikan status dan mekanisme
    • WAL: oranye
    • dirty page: merah
    • clean page: biru
    • vacuum: ungu
    • checkpoint: merah muda
    • background writer: hijau kebiruan
    • replication: oranye
    • storage: hijau
    • index: aqua
    • lock: merah
  • Struktur digambarkan matte, sementara elemen yang punya makna ditampilkan dengan neon, dan hanya material emissive yang dibuat melewati ambang bloom

Skenario yang bisa dicoba langsung

  • Perkecil shared_buffers menjadi 64 halaman
    • usage_count runtuh dan clock hand berputar cepat
    • Ketika clean page yang bisa digusur makin sedikit, backend mulai menulis dirty page-nya sendiri secara langsung
  • Aktifkan transaksi berjalan lama
    • Horizon xmin ProcArray turun dan berubah merah
    • Worker autovacuum terus berputar, tetapi tidak bisa menghapus tuple yang seharusnya dibersihkan
    • Tabel sessions membengkak dan tidak pulih
  • Jalankan checkpoint storm
    • Checkpointer dipercepat dan tahap fsync bergetar
    • Setelah itu, full-page write mengalir deras ke distrik WAL
  • Atur synchronous_commit=off
    • Backend tidak lagi menunggu di commit_wait
    • Anda bisa melihat syarat durabilitas yang ditukar dengan respons instan
  • Aktifkan replay lambat
    • LSN sent/written/flushed/applied pada server standby makin berjauhan
    • Selisih ini sesuai dengan lag replikasi yang diamati di pg_stat_replication
  • Tekan tombol G untuk turun ke sudut pandang pejalan kaki setinggi 1,7 m dan melihat buffer serta bangunan sejajar mata

Navigasi dan kontrol

  • Kontrol mouse dan sentuh
    • Drag kiri: bergerak seperti menggeser peta
    • Drag kanan: memutar mengelilingi kota
    • Wheel: zoom in/out berdasarkan posisi kursor
    • Satu jari: bergerak
    • Dua jari: zoom, rotasi, ubah kemiringan
  • Mode pergerakan
    • W/A/S/D atau tombol arah: bergerak
    • Space/E: naik
    • C/Q: turun
    • Shift: bergerak cepat
    • Alt: pergerakan presisi
  • Tombol utama
    • F: ganti kamera terbang/orbit
    • G: berjalan di permukaan
    • H: kembali ke tampilan awal
    • T: tur 14 bab yang memandu seluruh kota
    • / atau Ctrl-K: cari komponen/pengaturan/skenario
    • ?: peta keyboard dan legenda warna
    • K atau P: jeda/lanjutkan
    • ,/.: atur kecepatan 0,1×~5×
    • 1~8: pindah ke distrik clients/backends/shared buffers/WAL/storage/checkpointer/autovacuum/standby

Lisensi dan merek dagang

  • Didistribusikan di bawah lisensi Apache-2.0
  • Tidak mencakup kode/aset/ilustrasi/logo/karakter/audio/konten game dari SimCity
  • Proyek edukatif independen yang tidak berafiliasi/disponsori/disetujui oleh Electronic Arts maupun proyek PostgreSQL

Bacaan terkait

1 komentar

 
GN⁺ 3 jam lalu
Komentar Hacker News

  • Saya sangat menyukai arah yang dicoba di sini, tetapi fitur tur-nya terlalu banyak noise. Banyak sekali kotak dan elemen di layar terus berubah sehingga sulit memahami apa yang sedang terjadi, dan sebaiknya dibuat agar pengguna maju sendiri alih-alih otomatis berpindah ke topik berikutnya.
    Kalau hanya secara pasif melihat informasi yang ditumpahkan sekaligus, rasanya membingungkan. Pendekatan untuk menunjukkan cara kerja internal teknologi itu sendiri berguna, tetapi perlu mempersempit fokus, bukan menambahkan data, grafik, dan kotak informasi.

    • 80% dari layar 3D yang keren tertutup popup. Akan bagus jika ada fitur yang mudah terlihat untuk mengurangi noise dan popup dibuat semi-transparan.
    • Layak mencoba menambahkan TTS ke tur.
    • Jika sebuah perangkat lunak membutuhkan fitur tur, itu bisa jadi tanda bahwa UX perlu diperbaiki. Meski ingin memperkenalkan fitur baru, pengguna akan menemukannya secara alami saat membutuhkannya.

  • Batasan otak manusia sama bagi pengembang maupun pengguna. Meski kita bisa membuat sesuatu yang kompleks dengan LLM, jika kompleksitas dekoratif berupa greeble melewati tingkat tertentu, rasanya tidak seperti dirancang untuk dialami manusia lain.
    Jika dibuat tanpa LLM, pengembangnya mungkin tidak bisa menampung seluruh model mentalnya di kepala dan akan mengurangi kompleksitas; pengguna juga punya batasan yang sama. Bahkan saat mencoba memahami metafora animasi dan lampu berkedip, maknanya tertimbun.
    Saya tidak mengerti mengapa proses baru berbentuk kotak yang melewati pipa lalu tiba di gedung, dan setelah itu sakelar pinball menyala merah. Ketika mengklik sesuatu, popup kecil bertuliskan "sessions is the victim" muncul sebentar bersama sebuah paragraf lalu menghilang, membuatnya makin membingungkan.
    Mungkin ini memang bukan untuk edukasi, atau mungkin saya yang kurang pengetahuan, tetapi jika dilihat sebagai karya yang unik, ini cukup keren.

  • Begitu melihat layar awal, saya berharap kalau memasukkan kueri, alurnya akan ditunjukkan tahap demi tahap dari parsing input hingga pengembalian hasil, dan saya juga bisa memahami proses otonom yang selalu berjalan paralel terlepas dari kueri.
    Upayanya sendiri bagus, tetapi saya tidak tahu harus mulai dari mana dan berhenti di mana.

    • Coba tekan T.

  • Dulu, untuk memahami scheduling di dalam database, dibutuhkan banyak diagram arsitektur. PGSimCity mengejutkan karena menyajikan proses implementasi teknis yang kompleks dengan cara yang menarik.
    Karena open source, gagasan yang sama tampaknya bisa digunakan ulang di bidang lain seperti cloud computing atau Kubernetes.

    • Saya selalu ingin membuat alat yang menjelaskan sistem deployment dan pelacakan status Fly.io dengan metafora visual Factorio.
    • Saya terus ingin membuat alat visualisasi Kubernetes. Memang sudah ada alat yang ada, tetapi terakhir kali saya melihatnya, tidak tampak terlalu bagus.

  • Ini sangat mirip dengan gambaran di kepala saat saya sedang sangat fokus men-debug program dengan gdb. Jika bisa mengalami debugging VR dengan grafis seperti ini, sepertinya tidak ada cara yang lebih baik untuk mempelajari sebuah codebase.
    Saya penasaran seberapa bagus pengalaman yang bisa dibuat jika menghasilkan peta 3D dari kode sembarang.

  • Kalau ini adalah hasil vibe coding kurang dari 48 jam, saya bertanya-tanya apakah isinya benar-benar akurat. Apakah tidak ada risiko berujung pada kesimpulan keliru atau semacam pengetahuan semu?

    • Tidak bisa sepenuhnya yakin, tetapi orang yang membuatnya cukup sangat memahami Postgres.
    • Saya penasaran apakah ada hal konkret yang Anda temukan atau pelajari dari sini. Bagi saya ini terlihat seperti ornamen bergaya brutalisme.
    • Akurasi LLM saat ini tidak seburuk itu.

  • Sulit dipercaya "Rendering The First Frame..." bukan "Reticulating Splines...". UI-nya keren.

  • Saya cukup memahami struktur internal Postgres, tetapi justru merasa bingung. Layarnya terlalu ramai sehingga sulit dipahami, dan setidaknya akan bagus jika ada tombol untuk menurunkan kecepatan.

    • Di kiri bawah ada jeda dan dua tombol untuk menyesuaikan kecepatan hingga 0,1x. Beberapa elemen kota bisa diklik untuk mengubah nilainya, dan saya juga melihatnya di transactions/s.

  • Kelihatannya benar-benar keren. Sejak beberapa minggu lalu saya mulai melakukan vibe coding untuk Doom untuk Beam, yang memungkinkan kita berjalan-jalan di Beam VM seperti di lantai pabrik, melihat hubungan modul dan fungsi, beban eksekusi, serta error yang memercikkan api.
    Belum banyak yang saya buat, tetapi saya ingin terus mengembangkannya sebagai alasan untuk membeli headset VR.

  • Sepertinya dibuat dengan bantuan AI. Saya juga menggunakan AI untuk mengerjakan proyek vibe coding serupa yang menjelaskan catastrophic forgetting.
    Sekarang kalau benar-benar ingin mempelajari sesuatu, saya senang karena selalu bisa mendapat bantuan AI. Dulu sulit menemukan materi yang bagus, tetapi sekarang bottleneck-nya bergeser dari materi ke fokus dan inisiatif pribadi.