PGSimCity: visualiza cómo funciona PostgreSQL como una ciudad 3D explorable

 (nikolays.github.io)
2 puntos por GN⁺ 3 시간 전 | 1 comentarios | Compartir por WhatsApp
  • Una simulación educativa 3D que representa las conexiones, backends, memoria compartida, WAL, almacenamiento, checkpoints, autovacuum y replicación de PostgreSQL como edificios y zonas; cada edificio y animación corresponde a un mecanismo real de la base de datos
  • Reduce los números y la escala para permitir observar los mecanismos internos en una escala de tiempo lenta, como el reemplazo clock-sweep de shared_buffers, la escritura y el flush de WAL, el pacing de checkpoints, el horizonte xmin y el crecimiento de tablas
  • No es un emulador que ejecute código real de PostgreSQL, sino un modelo escrito a mano; fue sometido a tres revisiones expertas y una auditoría visual independiente con base en la documentación y el código fuente de PostgreSQL, y 210 pruebas fijan los cálculos principales y valores límite
  • Permite ejecutar escenarios como falta de buffers, transacciones de larga duración, tormentas de checkpoints, synchronous_commit=off y reproducción lenta de replicación para ver directamente cómo la configuración operativa cambia la latencia, el crecimiento, la durabilidad y el retraso de replicación
  • Es una aplicación WebGL2 estática hecha con three.js/TypeScript/Vite; a futuro también se considera como posible rumbo una arquitectura híbrida que conecte los resultados y planes de ejecución de consultas de un PostgreSQL real en WebAssembly con el modelo interno actual

Cómo se representa PostgreSQL como una ciudad

  • PGSimCity es un proyecto independiente, no comercial y educativo de visualización que permite recorrer y explorar la estructura interna de PostgreSQL
  • La plaza central representa shared_buffers; la altura de sus 1,024 marcos de página indica el usage_count de clock-sweep, y el color representa el estado real del buffer
  • La zona naranja al este representa WAL, la excavación bajo la plaza representa el directorio de datos, y la ciudad al sur representa un servidor en espera que reproduce con algo de retraso el WAL enviado por el servidor primario
  • Está diseñado para ayudar a ingenieros que no han operado directamente bases de datos a entender los siguientes fenómenos
    • Por qué los checkpoints disparan la latencia
    • Cómo una transacción que no termina mantiene el crecimiento de las tablas
    • Qué costo impone synchronous_commit al hacer commit

Precisión y límites del modelo

  • PGSimCity sigue siendo un modelo en etapa 0.x y no es un emulador de PostgreSQL
    • No ejecuta el código fuente de PostgreSQL
    • Ajusta números y escalas de tiempo para que las personas puedan ver los cambios
    • No parsea SQL ni calcula resultados reales de consultas
  • Pasó por tres revisiones expertas que contrastaron la precisión del comportamiento de PostgreSQL con postgresql.org/docs y el código fuente; cada hallazgo fue vuelto a verificar por otro revisor designado para refutarlo
  • La distribución de edificios, las relaciones de proximidad y las afirmaciones implícitas creadas por las animaciones también recibieron una auditoría independiente
  • Incluye 210 pruebas, y si alguna falla se detiene el build de CI
    • Punto de inicio de checkpoints basados en WAL: max_wal_size / (1 + checkpoint_completion_target)
    • Tasa de acierto de caché: blks_hit / (blks_hit + blks_read)
    • Valor máximo de usage_count en clock-sweep: 5
  • Los errores encontrados y el proceso de corrección quedan registrados en el historial de commits
  • La interacción táctil solo ha sido verificada en la emulación móvil de Chrome
  • Los comportamientos simplificados se indican explícitamente en el inspector de cada componente

Posibilidad de combinarlo con un motor real

  • Actualmente usa una simulación escrita directamente para mostrar pasos internos que PostgreSQL no expone hacia afuera, como el proceso en que clock-sweep elige una página víctima cuadro por cuadro
  • Ejecutar PostgreSQL real en WebAssembly, como PGlite, permitiría delegar los resultados de consultas y los planes de ejecución al motor real
  • La información que un motor real puede entregar en el navegador se limita al alcance que PostgreSQL expone al exterior, como el catálogo, las vistas pg_stat_* y EXPLAIN
  • También sería posible un enfoque híbrido en el que la ejecución y los planes reales impulsen los movimientos dentro del modelo, pero es una dirección futura, no un compromiso de desarrollo confirmado

Zonas y componentes de la ciudad

  • Client sky: conexiones entrantes desde la capa de aplicación
  • Postmaster: proceso supervisor que crea un proceso backend por cada conexión, pero no accede directamente a los datos de usuario
  • Backend row: 16 procesos backend; las luces muestran el estado actual, incluido idle in transaction
  • Shared memory plaza
    • shared_buffers
    • wal_buffers
    • ProcArray
    • tabla de locks
    • CLOG
    • tabla de mapeo de buffers
  • The excavation: frontera entre las áreas de memoria y disco
  • Storage
    • archivos heap compuestos por páginas de 8 KiB
    • B-tree con forma de árbol real
    • TOAST
    • FSM
    • visibility map
    • caché de páginas del sistema operativo
    • disco
  • WAL district: walwriter → segmentos pg_wal → archiver → walsender
  • Maintenance yard: checkpointer/background writer/autovacuum launcher y workers
  • Standby: walreceiver/proceso startup que reproduce WAL/retraso entre ambos procesos
  • Query lab: despliega la sentencia del backend seleccionado en las etapas parse → rewrite → plan → execute

Colores y significado visual

  • Los colores no son decoración: transmiten estados y mecanismos
    • WAL: naranja
    • dirty page: rojo
    • clean page: azul
    • vacuum: morado
    • checkpoint: rosa
    • background writer: turquesa
    • replication: naranja
    • storage: verde
    • index: aqua
    • lock: rojo
  • Las estructuras se representan con acabado mate, y los elementos con significado se muestran en neón; solo los materiales emisivos superan el umbral de bloom

Escenarios para probar directamente

  • Reducir shared_buffers a 64 páginas
    • El usage_count colapsa y la manecilla del reloj circula rápidamente
    • Al faltar clean pages para expulsar, los backends empiezan a escribir directamente sus propias dirty pages
  • Activar Long-running transaction
    • El horizonte xmin de ProcArray baja y se vuelve rojo
    • El worker de autovacuum sigue recorriendo, pero no puede eliminar las tuplas que debería limpiar
    • La tabla sessions se infla y no se recupera
  • Ejecutar Checkpoint storm
    • El checkpointer se acelera y la etapa de fsync se vuelve inestable
    • Después, los full-page writes entran masivamente en la zona de WAL
  • Configurar synchronous_commit=off
    • Los backends dejan de esperar en commit_wait
    • También se pueden comprobar las condiciones de durabilidad intercambiadas por una respuesta inmediata
  • Activar Slow replay
    • Los LSN sent/written/flushed/applied del servidor en espera se separan entre sí
    • Esa diferencia corresponde al retraso de replicación observado en pg_stat_replication
  • Al presionar la tecla G, se baja a una vista peatonal de 1.7 m de altura para examinar buffers y edificios a nivel de la vista

Navegación y controles

  • Controles con mouse y táctiles
    • Arrastrar con botón izquierdo: moverse como si se arrastrara el mapa
    • Arrastrar con botón derecho: girar alrededor de la ciudad
    • Rueda: acercar/alejar tomando como referencia la posición del cursor
    • Un dedo: mover
    • Dos dedos: acercar/alejar, rotar y cambiar la inclinación
  • Modo de movimiento
    • W/A/S/D o flechas: moverse
    • Space/E: subir
    • C/Q: bajar
    • Shift: movimiento rápido
    • Alt: movimiento preciso
  • Teclas principales
    • F: cambiar entre cámara de vuelo/órbita
    • G: caminar a nivel del suelo
    • H: volver a la vista general inicial
    • T: tour de 14 capítulos que guía por toda la ciudad
    • / o Ctrl-K: buscar componentes/configuraciones/escenarios
    • ?: mapa del teclado y leyenda de colores
    • K o P: pausar/reanudar
    • ,/.: ajustar velocidad de 0.1× a 5×
    • 1~8: ir a las zonas clients/backends/shared buffers/WAL/storage/checkpointer/autovacuum/standby

Licencia y marcas registradas

  • Se distribuye bajo la licencia Apache-2.0
  • No incluye código, assets, imágenes, logos, personajes, audio ni contenido de juego de SimCity
  • Es un proyecto educativo independiente, sin afiliación, patrocinio ni aprobación de Electronic Arts ni del proyecto PostgreSQL

Lecturas relacionadas

1 comentarios

 
GN⁺ 3 시간 전
Comentarios de Hacker News

  • Me gusta mucho la dirección que intentan aquí, pero hay demasiado ruido en la función de recorrido. Hay tantas cajas y elementos cambiando constantemente en pantalla que cuesta entender qué está pasando, y en vez de cambiar automáticamente al siguiente tema, debería dejar que el usuario avance por su cuenta
    Ver pasivamente toda la información llegando de golpe resulta confuso. El enfoque de mostrar el funcionamiento interno de la tecnología en sí es útil, pero hace falta acotar más el foco en lugar de agregar más datos, gráficos y cuadros informativos

    • El 80% de la genial pantalla 3D está tapado por popups. Estaría bien ofrecer de forma visible una opción para reducir fácilmente el ruido y hacer los popups semitransparentes
    • Podría valer la pena agregar TTS al recorrido
    • Si un software necesita una función de recorrido, puede ser señal de que hay que mejorar la UX. Aunque quieras presentar funciones nuevas, el usuario las termina descubriendo de forma natural cuando las necesita

  • Los límites del cerebro humano son los mismos tanto para desarrolladores como para usuarios. Aunque con un LLM se puedan crear cosas complejas, si la complejidad ornamental tipo greeble supera cierto nivel, deja de sentirse como algo diseñado para que otro ser humano lo experimente
    Si esto se hubiera hecho sin un LLM, el propio desarrollador no habría podido sostener en la cabeza el modelo mental completo y habría reducido la complejidad; el usuario tiene la misma limitación. Aunque uno intente entender la metáfora de las animaciones y luces parpadeantes, el significado termina enterrado
    No entiendo por qué un proceso nuevo es un rectángulo que pasa por una tubería y llega a un edificio, ni por qué después un interruptor tipo pinball se ilumina en rojo. Si haces clic en algo, aparece por un momento un pequeño popup con un párrafo que dice "sessions is the victim" y desaparece, lo que lo vuelve aún más confuso
    Puede que no sea algo educativo, y también puede ser falta de conocimiento de mi parte, pero viéndolo simplemente como una obra curiosa está bastante genial

  • Apenas vi la pantalla inicial, esperaba que al ingresar una consulta mostrara paso a paso todo el flujo desde el análisis de entrada hasta la devolución del resultado, y que también ayudara a entender los procesos autónomos que se ejecutan siempre en paralelo independientemente de la consulta
    El intento en sí es excelente, pero no sé por dónde empezar ni dónde terminar

    • Solo hay que presionar T

  • Antes, para entender el scheduling dentro de una base de datos, hacían falta muchísimos diagramas de arquitectura. PGSimCity sorprende por lo interesante que resulta su forma de representar un proceso de implementación técnica complejo
    Como es open source, da la impresión de que la misma idea podría reutilizarse en otras áreas como cloud computing o Kubernetes

    • Siempre quise hacer una herramienta que explicara el sistema de despliegue y seguimiento de estado de Fly.io usando a Factorio como metáfora visual
    • Sigo queriendo hacer una herramienta de visualización de Kubernetes. Ya existen algunas, pero la última vez que revisé no me parecieron muy buenas

  • Se parece muchísimo a la imagen mental que me hago cuando depuro un programa con gdb y estoy profundamente concentrado. Si se pudiera experimentar debugging en VR con gráficos como estos, no habría mejor forma de aprender un codebase
    Me pregunto qué tan buena experiencia podría lograrse generando un mapa 3D a partir de código arbitrario

  • Si esto es un resultado de vibe coding de menos de 48 horas, me pregunto si el contenido es realmente correcto. Me da curiosidad si no existe el riesgo de llegar a conclusiones erróneas o a un conocimiento a medias

    • No puedo asegurarlo por completo, pero la persona que hizo esto conoce muy bien Postgres
    • Me pregunto si alguien aquí sacó o aprendió algo concreto de esto. A mí me parece un adorno brutalista
    • Hoy en día la precisión de los LLM no es tan mala

  • No puedo creer que "Rendering The First Frame..." no sea "Reticulating Splines...". La UI está genial

  • Conozco bastante bien la estructura interna de Postgres, pero igual me resultó confuso. La pantalla está demasiado cargada y cuesta entenderla; como mínimo estaría bien tener un botón para bajar la velocidad

    • En la parte inferior izquierda hay pausa y dos botones para ajustar la velocidad hasta 0.1x. También se puede hacer clic en algunos elementos de la ciudad para ajustar valores, y lo vi también en transactions/s

  • Se ve realmente genial. Desde hace unas semanas empecé a hacer vibe coding de un Doom para Beam donde puedes recorrer la Beam VM como si fuera el piso de una fábrica y ver cómo se conectan módulos y funciones, la carga de ejecución y errores soltando chispas
    Todavía no he avanzado mucho, pero quiero seguir desarrollándolo como excusa para comprarme un headset de VR

  • Parece hecho con ayuda de IA. Yo también hice un proyecto de vibe coding parecido con IA para explicar el olvido catastrófico
    Me da gusto que ahora, si de verdad quieres aprender algo, siempre puedes recurrir a la ayuda de la IA. Antes era difícil encontrar buen material, pero ahora el cuello de botella ya no son los recursos sino la concentración y la iniciativa personal