O que é o PGSimCity

O PGSimCity e uma ferramenta educacional interativa que simula o funcionamento interno do PostgreSQL de forma visual. Em vez de ler páginas de documentação técnica, você acompanha animações que mostram o que acontece dentro do banco de dados quando você executa uma query.

A ferramenta foi criada para desenvolvedores que usam PostgreSQL no dia a dia mas nunca entenderam de verdade o que acontece quando executam um SELECT ou UPDATE. O projeto ganhou mais de 800 pontos no Hacker News em julho de 2026, mostrando que essa demanda por visualização de sistemas complexos e real na comunidade.

O nome faz referência a SimCity, o clássico jogo de simulação de cidades: assim como no jogo você ve a cidade funcionando, no PGSimCity você ve o banco de dados funcionando internamente, com cada componente em ação.

Como funciona

O PGSimCity e uma aplicação web estática que roda direto no navegador. Não precisa instalar nada, não precisa de um PostgreSQL rodando. A simulação e baseada no comportamento documentado do PostgreSQL, representando os principais componentes da arquitetura interna.

A ferramenta visualiza o fluxo de uma query desde o momento em que ela chega ao banco até o retorno do resultado. Você ve o parser transformando o SQL em uma árvore de nos, o planner/optimizer escolhendo o melhor plano de execução, o executor percorrendo as páginas de dados, e o buffer pool gerenciando quais páginas estão na memoria.

Cada componente e animado de forma independente, e você pode pausar, avançar passo a passo e inspecionar o estado interno em qualquer momento da execução simulada.

💡
Dica

Use o PGSimCity junto com o comando EXPLAIN ANALYZE no PostgreSQL real. A simulação te ajuda a entender o que os termos do plano de execução significam na prática.

Principais recursos

O PGSimCity cobre vários aspectos da arquitetura interna do PostgreSQL:

  • Visualização do query planner: veja como o PostgreSQL escolhe entre Sequential Scan, Índex Scan e Bitmap Scan dependendo das estatísticas da tabela.
  • Simulação do MVCC: entenda como o Multiversion Concurrency Control funciona, como versões de linhas são criadas em updates e como o VACUUM recupera espaço.
  • Buffer pool interativo: acompanhe quais páginas de disco estão em cache na shared_buffers e o que acontece quando ocorre um cache miss.
  • WAL (Write-Ahead Log): veja como o PostgreSQL garante durabilidade gravando primeiro no log antes de modificar os dados reais.
  • Transações e locks: simule cenários de concorrência e veja como o PostgreSQL gerência bloqueios entre transações.

O diferencial em relação a tutoriais e vídeos e a interatividade: você controla o ritmo, pode repetir qualquer parte e experimentar diferentes cenários para ver como o comportamento muda.

Como começar: acesso e uso

O PGSimCity e acessível direto pelo navegador, sem cadastro e sem instalação:

Passo 1: Acesse nikolays.GitHub.io/PGSimCity/ no seu navegador. A aplicação carrega completamente no cliente, funciona offline após o primeiro carregamento.

Passo 2: Escolha um cenário de simulação no menu lateral. Os cenários vao de operações básicas (SELECT simples) até situações complexas (joins com índices, updates concorrentes).

Passo 3: Use os controles de reprodução para avançar passo a passo ou assistir a animação completa. Clique em cada componente para ver detalhes do estado interno naquele momento.

# Para acompanhar na prática enquanto usa o PGSimCity,
# abra um PostgreSQL real e execute:
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT * FROM sua_tabela WHERE coluna = 'valor';

-- Compare o plano real com a simulação visual
⚠️
Atenção

O PGSimCity e uma simulação educacional, não um profiler real. Os tempos e números mostrados são ilustrativos. Para performance real, use EXPLAIN ANALYZE e pg_stat_statements no seu banco de dados.

Exemplo prático

Imagine que você tem uma query lenta e quer entender por que o PostgreSQL esta fazendo Sequential Scan em vez de usar o índice que você criou. O PGSimCity ajuda a entender esse comportamento.

No cenário de Índex Scan vs Sequential Scan, a simulação mostra:

  • Como o planner usa as estatísticas de distribuição de dados para estimar o custo de cada abordagem
  • Por que com baixa seletividade (buscar 60% das linhas) o Sequential Scan e mais barato do que o Índex Scan
  • Como o ANALYZE atualiza as estatísticas e pode mudar a decisão do planner

Depois de ver isso na simulação, você entende por que o comando SET enable_seqscan = off e um hack que força o índice mas não necessariamente melhora a performance. Esse tipo de intuição e o que separa um dev que usa SQL de um que entende SQL.

-- Verificar estatísticas da tabela no PostgreSQL real
SELECT
  schemaname,
  tablename,
  n_live_tup,
  n_dead_tup,
  last_analyze
FROM pg_stat_user_tables
WHERE tablename = 'sua_tabela';

Comparação com alternativas

Existem outras formas de aprender o funcionamento interno do PostgreSQL:

  • Documentação oficial do PostgreSQL: completa e precisa, mas densa. Exige muito esforço para transformar texto em entendimento real. O PGSimCity e o complemento visual ideal para a doc.
  • The Internals of PostgreSQL (livro online de Hironobu Suzuki): excelente recurso técnico em inglês, com diagramas estáticos. Mais profundo que o PGSimCity, mas sem interatividade.
  • pgAdmin Query Planner visual: mostra o plano de execução de queries reais, mas não explica o mecanismo interno. Serve para otimização, não para aprendizado.
  • Cursos e vídeos no YouTube: bons para conceitos, mas difíceis de pausar e inspecionar no detalhe que a simulação permite.

O PGSimCity se destaca por ser gratuito, sem cadastro e interativo. Para quem esta aprendendo PostgreSQL a serio, e o melhor ponto de partida visual disponível.

Pontos positivos e limitações

O que funciona bem: animações claras do fluxo de uma query, explicações contextuais de cada componente, acesso imediato sem cadastro, funciona no navegador em qualquer sistema operacional.

Limitações reais: a simulação e simplificada e não cobre todos os casos extremos do PostgreSQL real. Alguns comportamentos específicos de versões mais recentes podem não estar representados. Não substitui o uso do EXPLAIN ANALYZE para tuning de performance em produção.

🔴
Cuidado

Não tome decisões de otimização de banco de dados baseado apenas na simulação. Sempre meça com dados reais do seu ambiente usando EXPLAIN ANALYZE e extensões de monitoramento como pg_stat_statements.

Casos de uso reais

O PGSimCity e mais útil em contextos de aprendizado e entendimento profundo:

  • Dev júnior aprendendo PostgreSQL: entender por que uma query e lenta antes de sair adicionando índices aleatoriamente. A simulação mostra o impacto real de cada decisão.
  • Tech lead em code review: usar como material de ensino durante revisões de código que envolvem queries complexas ou decisões de modelagem de dados.
  • Preparação para entrevista: candidatos a vagas backend que precisam entender MVCC, WAL e o planner para responder perguntas técnicas com profundidade.
  • Equipe migrando para PostgreSQL: times vindos de MySQL ou SQL Server que precisam entender as diferenças arquiteturais do Postgres antes de colocar em produção.

Dicas e boas práticas

💡
Dica

Comece pelo cenário mais simples do PGSimCity e avance para os mais complexos na ordem sugerida. Pular direto para MVCC sem entender o buffer pool vai deixar lacunas de entendimento.

🚀
Pro tip

Combine o PGSimCity com a extensão auto_explain do PostgreSQL para logar automaticamente o plano de queries lentas em produção. Depois use a simulação para entender o que o plano esta dizendo.

⚠️
Atenção

O VACUUM e um dos conceitos mais mal entendidos do PostgreSQL. Use o cenário de MVCC do PGSimCity para entender por que tabelas com muitos updates podem acumular bloat e precisam de manutenção regular.

Vale a pena?

Para qualquer desenvolvedor que usa PostgreSQL e quer ir além do básico, o PGSimCity e uma visita obrigatória. Em 30 minutos explorando os cenários disponíveis você vai entender mais sobre o funcionamento interno do banco do que em horas lendo documentação.

Se você já e experiente em PostgreSQL e conhece MVCC, WAL e o planner de cor, talvez o PGSimCity seja mais para revisar conceitos ou ensinar o time do que para aprender algo novo. Mas mesmo assim vale dar uma olhada para ver se a visualização confirma seu entendimento ou revela alguma surpresa.

Próximo passo: acesse nikolays.GitHub.io/PGSimCity/, escolha um cenário que te intriga (MVCC e um bom começo) e acompanhe a animação com o EXPLAIN ANALYZE do seu PostgreSQL real aberto em paralelo.