PGSIMCITY : comprendre PostgreSQL en visitant une ville en 3D

https://nikolays.github.io/PGSimCity/

📌 PGSIMCITY est une visualisation éducative en 3D qui transforme l’architecture interne de PostgreSQL en une ville explorable, avec ses backends, son buffer pool, son WAL, son stockage et ses standbys.

PostgreSQL est souvent appris par les commandes SQL, les schémas et les plans d’exécution. C’est nécessaire, mais cela laisse parfois dans l’ombre ce qui se passe derrière une requête. Pourquoi un checkpoint ralentit-il une machine ? Comment une transaction oubliée fait-elle grossir une table ? Que signifie vraiment attendre un commit synchrone ? PGSimCity propose de regarder ces mécanismes comme un espace que l’on peut parcourir.

La ville représente un cluster PostgreSQL. Le postmaster supervise les connexions, les backends apparaissent comme des bâtiments, le buffer pool devient un quartier de mémoire, et les fichiers de stockage sont représentés sous terre. Le district WAL montre les écritures et la réplication. Plus loin, le checkpointer, l’autovacuum et les standbys rendent visibles les opérations de maintenance et de continuité.

Les choses à essayer :

• 🗺️ Suivre une visite guidée en 14 chapitres avec la touche T
• 🔍 Tracer une requête avec Enter et observer parse, planification et exécution
• 💾 Voir le buffer pool, le WAL, les checkpoints et le stockage comme des quartiers
• 🧹 Déclencher des scénarios de cache, autovacuum, checkpoint ou réplication
• 🚶 Descendre à hauteur d’humain avec G et visiter la ville en marchant
• 🖥️ Ouvrir les parcours clavier et la machine PostgreSQL optionnelle en WebAssembly

Les scénarios rendent l’expérience plus concrète qu’une simple carte annotée. Un cache thrash réduit le buffer pool et fait courir le clock sweep. Une transaction longue bloque l’avancée du xmin et empêche l’autovacuum de supprimer les lignes obsolètes. Un checkpoint storm met en évidence les écritures de pages complètes et l’activité du checkpointer. Chaque manipulation relie donc un réglage PostgreSQL à une conséquence visuelle.

PGSimCity fait une distinction saine entre le modèle et le vrai moteur. La ville ne lance pas le code source de PostgreSQL et ses nombres sont adaptés pour rester lisibles. Le projet cible PostgreSQL 18 et documente la version de référence 18.4, mais annonce clairement les simplifications encore présentes. La vue Query et la Machine peuvent, après accord, charger PGlite pour exécuter un PostgreSQL réel en mémoire. Les résultats réels et la représentation pédagogique restent alors identifiés séparément.

Je trouve l’idée excellente pour expliquer PostgreSQL à quelqu’un qui sait déjà utiliser une base mais n’a jamais eu à l’opérer. Les couleurs, les quartiers et les animations donnent des repères mémorisables à des sujets qui restent souvent abstraits. Ce n’est pas un outil de diagnostic de production, et il ne faut pas prendre ses proportions comme des mesures réelles. C’est plutôt une carte mentale interactive, suffisamment sérieuse pour signaler ses limites et corriger ses erreurs.

Le projet est gratuit, open source sous licence Apache-2.0 et fonctionne dans un navigateur compatible WebGL2. À ouvrir quand vous voulez comprendre ce qui se passe après l’envoi d’une requête, sans commencer par lire tout le code de PostgreSQL.

Sources

Ville 3D interactive

Dépôt GitHub