PGSimCity - Visualiser le fonctionnement de PostgreSQL comme une ville 3D explorable

 (nikolays.github.io)
2 points par GN⁺ 3 시간 전 | 1 commentaires | Partager sur WhatsApp
  • Simulation 3D éducative qui représente les connexions / backends / mémoire partagée / WAL / stockage / checkpoints / autovacuum / réplication de PostgreSQL sous forme de bâtiments et de quartiers, chaque bâtiment et animation correspondant à un mécanisme réel de la base de données
  • Les valeurs et les échelles ont été réduites afin de pouvoir observer les mécanismes internes sur une échelle de temps ralentie, comme le remplacement clock-sweep de shared_buffers, l’écriture et le flush du WAL, le pacing des checkpoints, l’horizon xmin et le gonflement des tables
  • Il ne s’agit pas d’un émulateur exécutant le vrai code PostgreSQL, mais d’un modèle écrit à la main ; il a fait l’objet de trois revues expertes fondées sur la documentation et le code source de PostgreSQL, ainsi que d’un audit visuel séparé, et 210 tests verrouillent les principaux calculs et seuils
  • Il est possible d’exécuter des scénarios comme une pénurie de buffers, une transaction longue, une tempête de checkpoints, synchronous_commit=off ou un rejeu de réplication lent pour observer directement l’impact des paramètres d’exploitation sur la latence, le gonflement, la durabilité et le retard de réplication
  • Application WebGL2 statique réalisée avec three.js / TypeScript / Vite ; le projet étudie aussi à terme une architecture hybride qui relierait les résultats et plans d’exécution d’un vrai PostgreSQL en WebAssembly au modèle interne actuel

Représenter PostgreSQL comme une ville

  • PGSimCity est un projet de visualisation éducative indépendant et non commercial qui permet d’explorer en se déplaçant dans les structures internes de PostgreSQL
  • La place centrale représente shared_buffers ; la hauteur des 1 024 cadres de page indique le usage_count du clock-sweep, et leur couleur exprime l’état réel des buffers
  • Le quartier orange à l’est représente le WAL, l’excavation sous la place correspond au répertoire de données, et la ville au sud représente un serveur standby qui rejoue avec un léger retard le WAL envoyé par le serveur principal
  • Le projet est conçu pour aider les ingénieurs n’ayant jamais exploité directement une base de données à comprendre les phénomènes suivants
    • pourquoi les checkpoints provoquent des pics de latence
    • comment une transaction non terminée entretient le gonflement d’une table
    • quel coût synchronous_commit impose au moment du commit

Précision et limites du modèle

  • PGSimCity est encore un modèle en phase 0.x et non un émulateur PostgreSQL
    • il n’exécute pas le code source de PostgreSQL
    • il ajuste les valeurs et l’échelle du temps pour rendre les changements visibles à l’œil humain
    • il ne parse pas le SQL et ne calcule pas de vrais résultats de requêtes
  • Trois revues expertes ont comparé le comportement de PostgreSQL à postgresql.org/docs et au code source ; chaque point relevé a ensuite été revérifié par un autre relecteur chargé de le contester
  • Les affirmations implicites créées par la disposition des bâtiments, leurs relations de voisinage et les animations ont aussi fait l’objet d’un audit séparé
  • 210 tests sont inclus, et tout test en échec interrompt le build CI
    • point de départ des checkpoints fondés sur le WAL : max_wal_size / (1 + checkpoint_completion_target)
    • taux de hit du cache : blks_hit / (blks_hit + blks_read)
    • valeur maximale de usage_count pour le clock-sweep : 5
  • Les erreurs identifiées et leur correction figurent dans l’historique des commits
  • Les interactions tactiles n’ont été vérifiées que dans l’émulation mobile de Chrome
  • Les comportements simplifiés sont explicités dans l’inspector de chaque composant

Possibilité de couplage avec le vrai moteur

  • Aujourd’hui, le projet utilise une simulation écrite à la main afin de montrer des étapes internes non exposées en dehors de PostgreSQL, comme la sélection image par image d’une page victime par le clock-sweep
  • En exécutant un vrai PostgreSQL en WebAssembly, comme PGlite, il serait possible de confier au moteur réel les résultats de requêtes et les plans d’exécution
  • Les informations qu’un vrai moteur peut fournir dans le navigateur restent limitées à ce que PostgreSQL expose vers l’extérieur, comme le catalogue, les vues pg_stat_* ou EXPLAIN
  • Une approche hybride où l’exécution réelle et les plans piloteraient les mouvements à l’intérieur du modèle est aussi envisageable, mais cela reste une direction future plutôt qu’un engagement de développement ferme

Quartiers et composants de la ville

  • Client sky : connexions arrivant depuis la couche applicative
  • Postmaster : processus superviseur qui crée un processus backend par connexion sans accéder directement aux données utilisateur
  • Backend row : 16 processus backend, avec un éclairage indiquant leur état courant, y compris idle in transaction
  • Shared memory plaza
    • shared_buffers
    • wal_buffers
    • ProcArray
    • table des verrous
    • CLOG
    • table de mappage des buffers
  • The excavation : frontière entre les zones mémoire et disque
  • Storage
    • fichiers heap composés de pages de 8 KiB
    • B-tree en forme de véritable arbre
    • TOAST
    • FSM
    • visibility map
    • cache de pages du système d’exploitation
    • disque
  • WAL district : walwriter → segments pg_wal → archiver → walsender
  • Maintenance yard : checkpointer / background writer / autovacuum launcher et workers
  • Standby : walreceiver / processus startup qui rejoue le WAL / retard entre les deux processus
  • Query lab : déplie la requête du backend sélectionné selon les étapes parse → rewrite → plan → execute

Couleurs et signification visuelle

  • Les couleurs ne sont pas décoratives, elles transmettent un état et un mécanisme
    • WAL : orange
    • dirty page : rouge
    • clean page : bleu
    • vacuum : violet
    • checkpoint : rose
    • background writer : turquoise
    • réplication : orange
    • stockage : vert
    • index : aqua
    • verrou : rouge
  • Les structures sont rendues en mat, tandis que les éléments porteurs de sens sont en néon, avec un seuil de bloom franchi uniquement par les matériaux émissifs

Scénarios à essayer soi-même

  • Réduire shared_buffers à 64 pages
    • le usage_count s’effondre et l’aiguille du clock hand tourne rapidement
    • faute de pages propres à évincer, les backends commencent à écrire eux-mêmes leurs pages sales
  • Activer Long-running transaction
    • l’horizon xmin du ProcArray descend et devient rouge
    • le worker autovacuum continue à tourner, mais ne peut pas supprimer les tuples à nettoyer
    • la table sessions gonfle sans jamais se résorber
  • Lancer Checkpoint storm
    • le checkpointer accélère et la phase fsync devient instable
    • ensuite, un afflux massif de full-page writes se déverse vers la zone WAL
  • Définir synchronous_commit=off
    • le backend n’attend plus dans commit_wait
    • on peut voir en même temps la condition de durabilité échangée contre une réponse immédiate
  • Activer Slow replay
    • les LSN sent / written / flushed / applied du serveur standby s’écartent les uns des autres
    • cet écart correspond au retard de réplication observé dans pg_stat_replication
  • En appuyant sur G, on descend à une vue piétonne à 1,7 m de hauteur pour observer buffers et bâtiments à hauteur d’yeux

Navigation et commandes

  • Contrôles souris et tactiles
    • glisser à gauche : se déplacer comme en faisant glisser la carte
    • glisser à droite : tourner autour de la ville
    • molette : zoomer / dézoomer autour de la position du curseur
    • un doigt : déplacement
    • deux doigts : zoom, rotation et changement d’inclinaison
  • Modes de déplacement
    • W/A/S/D ou flèches : déplacement
    • Space/E : monter
    • C/Q : descendre
    • Shift : déplacement rapide
    • Alt : déplacement de précision
  • Touches principales
    • F : basculer entre caméra volante et orbitale
    • G : marche au sol
    • H : revenir à la vue initiale
    • T : visite guidée en 14 scènes couvrant toute la ville
    • / ou Ctrl-K : recherche de composants / paramètres / scénarios
    • ? : carte du clavier et légende des couleurs
    • K ou P : pause / reprise
    • ,/. : réglage de la vitesse de 0.1× à 5×
    • 1~8 : aller aux zones clients / backends / shared buffers / WAL / stockage / checkpointer / autovacuum / standby

Licence et marques

  • Distribué sous licence Apache-2.0
  • N’inclut ni code, ni assets, ni illustrations, ni logos, ni personnages, ni audio, ni contenu de jeu de SimCity
  • Projet éducatif indépendant, sans affiliation, sponsoring ni approbation de la part d’Electronic Arts ou du projet PostgreSQL

À lire aussi

1 commentaires

 
GN⁺ 3 시간 전
Commentaires sur Hacker News

  • J'aime beaucoup la direction tentée ici, mais la fonction de visite guidée a beaucoup trop de bruit. D'innombrables boîtes et éléments changent sans cesse à l'écran, ce qui rend difficile de comprendre ce qu'il se passe, et au lieu de passer automatiquement au sujet suivant, il faudrait laisser l'utilisateur avancer lui-même
    Regarder passivement un flot d'informations d'un seul coup est déroutant. L'approche consistant à montrer le fonctionnement interne de la technologie est utile en soi, mais il faut resserrer le focus plutôt que d'ajouter davantage de données, de graphiques et d'encadrés d'information

    • 80 % du superbe écran 3D est masqué par des pop-ups. Ce serait bien de proposer de façon visible une option pour réduire facilement le bruit et de rendre les pop-ups semi-transparents
    • Cela vaudrait peut-être le coup d'ajouter du TTS à la visite guidée
    • Si un logiciel a besoin d'une visite guidée, c'est peut-être le signe qu'il faut améliorer l'UX. Même si l'on veut mettre en avant de nouvelles fonctionnalités, les utilisateurs les découvriront naturellement quand ils en auront besoin

  • Les limites du cerveau humain sont les mêmes pour les développeurs que pour les utilisateurs. Même si on peut créer des choses complexes avec des LLM, quand la complexité décorative du greeble dépasse un certain seuil, on n'a plus l'impression que c'est conçu pour être expérimenté par d'autres humains
    Sans LLM, le développeur aurait sans doute réduit la complexité parce qu'il n'aurait pas pu garder tout le modèle mental en tête lui-même, et les utilisateurs ont la même limite. Même si l'on essaie de comprendre la métaphore des animations et des lumières clignotantes, le sens finit par se perdre
    Je ne comprends pas pourquoi un nouveau processus est un rectangle qui passe dans un tuyau pour arriver à un bâtiment, puis pourquoi un interrupteur de flipper s'allume en rouge ensuite. Quand on clique sur quelque chose, une petite pop-up avec "sessions is the victim" apparaît brièvement avec un paragraphe puis disparaît, ce qui rend l'ensemble encore plus confus
    Ce n'est peut-être pas fait pour l'enseignement, et c'est peut-être juste mon manque de connaissances, mais si on le regarde comme une œuvre curieuse, c'est plutôt cool

  • En voyant l'écran initial, je m'attendais à pouvoir saisir une requête et voir tout le flux de l'analyse de l'entrée jusqu'au retour du résultat étape par étape, ainsi qu'à comprendre les processus autonomes qui tournent en permanence en parallèle, indépendamment de la requête
    La tentative est excellente, mais je ne sais pas où commencer ni où m'arrêter

    • Il suffit d'appuyer sur T

  • Autrefois, il fallait une multitude de diagrammes d'architecture pour comprendre le scheduling à l'intérieur d'une base de données. PGSimCity est impressionnant dans sa manière de représenter de façon captivante un processus d'implémentation technique complexe
    Comme c'est open source, on pourrait sans doute réutiliser la même idée dans d'autres domaines comme le cloud computing ou Kubernetes

    • J'ai toujours voulu créer un outil qui explique le système de déploiement et le suivi d'état de Fly.io à l'aide de la métaphore visuelle de Factorio
    • J'ai toujours envie de créer un outil de visualisation Kubernetes. Il en existe déjà, mais la dernière fois que j'ai regardé, ils ne m'ont pas semblé formidables

  • Cela ressemble beaucoup à l'image mentale que je me fais quand je débogue un programme avec gdb et que je suis en concentration profonde. Si on pouvait découvrir du débogage VR avec ce type de graphismes, il n'y aurait sans doute pas de meilleure façon d'apprendre une codebase
    Je me demande quelle qualité d'expérience on pourrait obtenir en générant une carte 3D à partir d'un code arbitraire

  • Si c'est un résultat de vibe coding de moins de 48 heures, je me demande si le contenu est réellement exact. Y a-t-il un risque d'aboutir à de mauvaises conclusions ou à une semi-connaissance ?

    • Je ne peux pas l'affirmer totalement, mais la personne qui a fait ça connaît très bien Postgres
    • Je me demande si quelqu'un a effectivement découvert ou appris quelque chose de précis ici. Pour moi, cela ressemble à un ornement brutaliste
    • De nos jours, la précision des LLM n'est pas si mauvaise

  • J'ai du mal à croire que "Rendering The First Frame..." ne soit pas "Reticulating Splines...". L'UI est cool

  • Je connais assez bien l'architecture interne de Postgres, mais j'ai justement trouvé cela encore plus déroutant. L'écran est trop agité pour être facile à comprendre, et au minimum un bouton pour ralentir la vitesse serait utile

    • En bas à gauche, il y a deux boutons pour mettre en pause et régler la vitesse jusqu'à 0,1x. On peut cliquer sur certains éléments de la ville pour ajuster des valeurs, et je l'ai aussi vu sur transactions/s

  • Visuellement, c'est vraiment très cool. Depuis quelques semaines, j'ai commencé à vibe coder un Doom pour Beam dans lequel on se promène sur la VM Beam comme sur un sol d'usine pour voir les liens entre modules et fonctions, la charge d'exécution et les erreurs qui projettent des étincelles
    Je n'en ai pas encore fait beaucoup, mais j'ai envie de continuer à le développer pour me donner une bonne excuse d'acheter un casque VR

  • Cela semble avoir été fait avec l'aide de l'IA. Moi aussi, j'ai utilisé l'IA pour un projet de vibe coding similaire expliquant l'oubli catastrophique
    Je trouve satisfaisant de pouvoir désormais solliciter l'aide de l'IA dès qu'on veut vraiment apprendre quelque chose. Avant, il était difficile de trouver de bonnes ressources, mais désormais le goulot d'étranglement n'est plus l'accès aux ressources, mais la concentration et l'initiative personnelles