PGSimCity - Visualizando o funcionamento do PostgreSQL como uma cidade 3D explorável

 (nikolays.github.io)
2 pontos por GN⁺ 3 시간 전 | 1 comentários | Compartilhar no WhatsApp
  • Simulação educacional 3D que representa conexões/backends/memória compartilhada/WAL/armazenamento/checkpoints/autovacuum/replicação do PostgreSQL como prédios e distritos, em que cada construção e animação corresponde a mecanismos reais do banco de dados
  • Reduz números e escalas para permitir observar o funcionamento interno em um ritmo mais lento, como a substituição clock-sweep de shared_buffers, registro e flush de WAL, pacing de checkpoints, horizonte xmin e inchaço de tabelas
  • Não é um emulador que executa código real do PostgreSQL, mas um modelo escrito manualmente; passou por três revisões especializadas com base na documentação e no código-fonte do PostgreSQL, além de uma auditoria visual separada, e fixa cálculos principais e limites com 210 testes
  • É possível executar cenários como falta de buffers, transações longas, tempestade de checkpoints, synchronous_commit=off e replay lento de replicação para observar diretamente como configurações operacionais afetam latência, inchaço, durabilidade e atraso de replicação
  • Aplicação WebGL2 estática feita com three.js/TypeScript/Vite, com estudo de uma possível arquitetura híbrida que conecte, no futuro, resultados e planos de execução de um PostgreSQL real em WebAssembly ao modelo interno atual

Como o PostgreSQL é representado como uma cidade

  • PGSimCity é um projeto independente e não comercial de visualização educacional no qual se pode caminhar e explorar a estrutura interna do PostgreSQL
  • A praça central representa shared_buffers; a altura de 1.024 page frames mostra o clock-sweep usage_count, e as cores representam o estado real dos buffers
  • A área laranja a leste representa o WAL, a escavação sob a praça representa o diretório de dados, e a cidade ao sul representa um servidor standby que reproduz com pequeno atraso o WAL enviado pelo servidor principal
  • Foi projetado para ajudar engenheiros que nunca operaram diretamente um banco de dados a entender os seguintes fenômenos
    • por que checkpoints fazem a latência disparar
    • como transações não encerradas continuam causando inchaço de tabelas
    • qual custo synchronous_commit impõe no momento do commit

Precisão e limitações do modelo

  • O PGSimCity ainda está em um modelo na fase 0.x e não é um emulador de PostgreSQL
    • não executa o código-fonte do PostgreSQL
    • ajusta números e escala de tempo para que humanos possam enxergar as mudanças
    • não faz parsing de SQL nem calcula resultados reais de consultas
  • Passou por três revisões especializadas que compararam a exatidão do comportamento do PostgreSQL com postgresql.org/docs e com o código-fonte, e cada ponto encontrado foi verificado novamente por um revisor separado encarregado de contestá-lo
  • As afirmações implícitas criadas pelo posicionamento dos prédios, relações de adjacência e animações também passaram por auditoria separada
  • Inclui 210 testes, e a build de CI é interrompida se algum falhar
    • ponto inicial de checkpoint baseado em WAL: max_wal_size / (1 + checkpoint_completion_target)
    • taxa de acerto de cache: blks_hit / (blks_hit + blks_read)
    • valor máximo de clock-sweep usage_count: 5
  • Erros encontrados e seu processo de correção estão registrados no histórico de commits
  • As interações por toque foram validadas apenas na emulação móvel do Chrome
  • Comportamentos simplificados são explicitados no inspector de cada componente

Possibilidade de integração com um motor real

  • Atualmente usa uma simulação escrita manualmente para mostrar etapas internas que o PostgreSQL não expõe externamente, como o processo em que o clock-sweep escolhe uma página vítima a cada frame
  • Se um PostgreSQL real for executado em WebAssembly, como no PGlite, os resultados de consultas e planos de execução podem ser delegados ao motor real
  • As informações que um motor real pode fornecer no navegador se limitam ao que o PostgreSQL expõe externamente, como catalog, views pg_stat_* e EXPLAIN
  • Também é possível um modo híbrido em que a execução real e os planos conduzam os movimentos dentro do modelo, mas isso é uma direção futura, não um compromisso de desenvolvimento definido

Distritos e componentes da cidade

  • Client sky: conexões que chegam da camada de aplicação
  • Postmaster: processo supervisor que cria um backend por conexão, mas não acessa diretamente os dados do usuário
  • Backend row: 16 processos backend, com iluminação indicando o estado atual, incluindo idle in transaction
  • Shared memory plaza
    • shared_buffers
    • wal_buffers
    • ProcArray
    • tabela de locks
    • CLOG
    • tabela de mapeamento de buffers
  • The excavation: fronteira entre as áreas de memória e de disco
  • Storage
    • arquivos heap compostos por páginas de 8KiB
    • B-tree em forma de árvore real
    • TOAST
    • FSM
    • visibility map
    • page cache do sistema operacional
    • disco
  • WAL district: walwriter → pg_wal segments → archiver → walsender
  • Maintenance yard: checkpointer/background writer/autovacuum launcher e workers
  • Standby: walreceiver/processo startup que reproduz WAL/atraso entre os dois processos
  • Query lab: expande a instrução do backend selecionado em etapas de parse → rewrite → plan → execute

Cores e significado visual

  • As cores não são decorativas; elas transmitem estado e mecanismo
    • WAL: laranja
    • dirty page: vermelho
    • clean page: azul
    • vacuum: roxo
    • checkpoint: rosa
    • background writer: turquesa
    • replication: laranja
    • storage: verde
    • index: água-marinha
    • lock: vermelho
  • As estruturas são mostradas com acabamento fosco, enquanto elementos com significado usam neon, e apenas materiais emissivos ultrapassam o limiar de bloom

Cenários para testar diretamente

  • Reduzir shared_buffers para 64 páginas
    • o usage_count entra em colapso e o clock hand passa a circular rapidamente
    • com poucas clean pages disponíveis para remoção, os backends começam a gravar diretamente suas próprias dirty pages
  • Ativar Long-running transaction
    • o horizonte xmin do ProcArray desce e muda para vermelho
    • o worker de autovacuum continua circulando, mas não consegue remover os tuples para limpeza
    • a tabela sessions incha e não se recupera
  • Executar Checkpoint storm
    • o checkpointer acelera e a etapa de fsync oscila
    • depois disso, há uma grande entrada de full-page writes no distrito WAL
  • Definir synchronous_commit=off
    • o backend deixa de esperar em commit_wait
    • é possível ver a condição de durabilidade trocada por resposta imediata
  • Ativar Slow replay
    • os LSNs sent/written/flushed/applied do servidor standby se afastam entre si
    • essa diferença corresponde ao atraso de replicação observado em pg_stat_replication
  • Ao pressionar a tecla G, você desce para uma visão de caminhada no nível do chão, a 1,7 m de altura, para observar buffers e prédios ao nível dos olhos

Navegação e controles

  • Operações com mouse e toque
    • arrastar com o botão esquerdo: mover como se estivesse empurrando o mapa
    • arrastar com o botão direito: girar ao redor da cidade
    • roda do mouse: ampliar/reduzir com base na posição do cursor
    • um dedo: mover
    • dois dedos: ampliar/reduzir, girar e alterar inclinação
  • Modo de movimento
    • W/A/S/D ou setas: mover
    • Space/E: subir
    • C/Q: descer
    • Shift: movimento rápido
    • Alt: movimento preciso
  • Teclas principais
    • F: alternar entre câmera de voo/órbita
    • G: caminhada no solo
    • H: voltar para a visão inicial
    • T: tour de 14 cenas guiando pela cidade inteira
    • / ou Ctrl-K: buscar componentes/configurações/cenários
    • ?: mapa do teclado e legenda de cores
    • K ou P: pausar/retomar
    • ,/.: ajustar velocidade entre 0,1× e 5×
    • 1~8: mover para os distritos clients/backends/shared buffers/WAL/storage/checkpointer/autovacuum/standby

Licença e marcas

  • Distribuído sob a licença Apache-2.0
  • Não inclui código/assets/ilustrações/logotipos/personagens/áudio/conteúdo de jogo de SimCity
  • É um projeto educacional independente, sem afiliação, patrocínio ou aprovação da Electronic Arts ou do projeto PostgreSQL

Leituras relacionadas

1 comentários

 
GN⁺ 3 시간 전
Opiniões no Hacker News

  • Gosto muito da direção que estão tentando seguir aqui, mas o tour tem ruído demais. Há tantas caixas e elementos mudando o tempo todo na tela que fica difícil entender o que está acontecendo, e deveria permitir que o usuário avançasse por conta própria em vez de passar automaticamente para o próximo tópico.
    Ficar apenas assistindo passivamente a uma enxurrada de informações de uma só vez é confuso. A abordagem de mostrar o funcionamento interno da tecnologia em si é útil, mas é preciso estreitar o foco em vez de acrescentar mais dados, gráficos e caixas de informação.

    • Pop-ups cobrem 80% da tela 3D incrível. Seria bom oferecer de forma bem visível um recurso para reduzir facilmente o ruído e tornar os pop-ups semitransparentes.
    • Valeria a pena adicionar TTS ao tour.
    • Se um software precisa de um tour, pode ser um sinal de que a UX precisa melhorar. Mesmo que você queira divulgar novos recursos, os usuários acabam descobrindo-os naturalmente quando precisam deles.

  • Os limites do cérebro humano são os mesmos para desenvolvedores e usuários. Mesmo que seja possível criar coisas complexas com LLMs, quando a complexidade decorativa, os greebles, passa de certo ponto, não parece algo projetado para ser experienciado por outro ser humano.
    Se isso tivesse sido feito sem LLM, o próprio desenvolvedor provavelmente não conseguiria manter todo o modelo mental na cabeça e teria reduzido a complexidade; os usuários têm a mesma limitação. Mesmo tentando entender a metáfora das animações e luzes piscando, o significado fica enterrado.
    Não sei por que um novo processo é um retângulo que passa por um cano e chega a um prédio, e depois um interruptor de pinball acende em vermelho. Quando clico em algo, um pequeno pop-up dizendo "sessions is the victim" aparece por um instante com um parágrafo e desaparece, o que deixa tudo ainda mais confuso.
    Talvez não seja educativo, ou talvez seja falta de conhecimento da minha parte, mas, se visto apenas como uma obra curiosa, é bem legal.

  • Assim que vi a primeira tela, esperava que, ao digitar uma consulta, ele mostrasse passo a passo todo o fluxo, da análise da sintaxe de entrada até o retorno do resultado, e que também fosse possível entender os processos autônomos que rodam continuamente em paralelo, independentemente da consulta.
    A tentativa em si é excelente, mas não sei por onde começar nem onde terminar.

    • É só apertar T.

  • Para entender o agendamento interno de um banco de dados, antigamente eram necessários muitos diagramas de arquitetura. O PGSimCity impressiona por representar de forma interessante um processo técnico complexo de implementação.
    Como é open source, parece que a mesma ideia poderia ser reutilizada em outras áreas, como computação em nuvem ou Kubernetes.

    • Sempre quis criar uma ferramenta que explicasse o sistema de deploy e rastreamento de estado da Fly.io usando Factorio como metáfora visual.
    • Continuo querendo criar uma ferramenta de visualização para Kubernetes. Já existem ferramentas, mas, da última vez que olhei, não pareciam muito boas.

  • É muito parecido com a imagem que formo na cabeça quando estou profundamente concentrado depurando um programa com gdb. Se fosse possível experimentar depuração em VR com esse tipo de gráfico, não haveria maneira melhor de aprender uma base de código.
    Fico curioso para saber quão boa seria a experiência ao gerar um mapa 3D a partir de código arbitrário.

  • Se isto é um resultado de vibe coding feito em menos de 48 horas, fico em dúvida se o conteúdo é realmente correto. Será que não há risco de levar a conclusões erradas ou a semiconhecimento?

    • Não dá para ter certeza absoluta, mas a pessoa que fez isso conhece muito bem o Postgres.
    • Fico curioso para saber se alguém descobriu ou aprendeu algo concreto aqui. Para mim, parece um objeto decorativo brutalista.
    • A precisão dos LLMs hoje em dia não é tão ruim assim.

  • Difícil acreditar que "Rendering The First Frame..." não seja "Reticulating Splines...". A UI é bonita.

  • Conheço razoavelmente bem a estrutura interna do Postgres, mas mesmo assim achei confuso. A tela é movimentada demais para entender, e seria bom ter pelo menos um botão para reduzir a velocidade.

    • No canto inferior esquerdo há dois botões para pausar e ajustar a velocidade até 0,1x. Alguns elementos da cidade podem ser clicados para ajustar valores, e também vi isso em transactions/s.

  • Visualmente é muito legal. Algumas semanas atrás comecei a fazer vibe coding de um Doom para Beam, em que você poderia andar pela VM Beam como se fosse um chão de fábrica e ver as relações entre módulos e funções, a carga de execução e erros soltando faíscas.
    Ainda não avancei muito, mas quero continuar desenvolvendo para ter uma justificativa para comprar um headset VR.

  • Parece ter sido feito com ajuda de IA. Eu também fiz, usando IA, um projeto semelhante de vibe coding para explicar esquecimento catastrófico.
    Fico satisfeito que agora, se eu realmente quiser aprender algo, posso contar com ajuda de IA a qualquer momento. Antes era difícil encontrar bons materiais; agora o gargalo deixou de ser o material e passou a ser a concentração e a iniciativa de cada pessoa.