Explore o conteúdo

O que você procura?

Pesquise por assunto, palavra ou título.

Arquitetura e Boas Práticas

Bug do WAL-reset do SQLite: pelo menos 16 anos escondido, 19 casos de corrupção na Tailscale

Como a Tailscale descobriu e investigou um bug crítico de 16 anos no modo WAL do SQLite. Um case real de debugging de baixo nível.

Thiago Pereira4 min de leitura

Atualizado em 30 de outubro de 2026

⏱ 4 min de leitura
Neste artigo
  1. O que acontece
  2. Como chegaram lá
  3. Impacto e correção
  4. O que serve de lição
  5. O que eu tiro desse caso como dev
  6. Três coisas que eu faria hoje se usasse SQLite em produção
  7. E onde entra a IA nessa história?

A Tailscale contou como achou o bug WAL-reset do SQLite, texto assinado por Alex Chan. É uma condição de corrida rara que, segundo a estimativa deles, existia no código do SQLite havia pelo menos 16 anos.

O que acontece

Quando uma escrita ocorre em um momento específico durante um checkpoint do WAL, o processo de checkpoint se confunde: acredita que páginas foram copiadas do WAL para o banco, mas elas nunca foram. Esses dados se perdem de forma permanente e o banco fica corrompido. A Tailscale era especialmente exposta porque assume o controle manual do checkpoint e o executa de forma agressiva.

Como chegaram lá

O sinal inicial foi corrupção recorrente em backups: 19 instâncias em 6 meses. A equipe contratou o suporte profissional do SQLite, e os desenvolvedores do SQLite criaram uma ferramenta de depuração chamada tmstmpvfs. Logs adicionais confirmaram a condição de corrida. Depois, a Tailscale implementou alertas para detectar tentativas ativas de corrupção.

Impacto e correção

Os efeitos incluíram indisponibilidade do plano de controle em shards afetados, dispositivos novos sem conseguir conectar durante a recuperação, perda temporária de acesso ao console de administração e à API, e alguns dados de configuração que não persistiam. Segundo o texto, as versões anteriores à 3.51.3 são afetadas. A correção adiciona uma verificação extra na função de checkpoint, para detectar quando o WAL foi resetado por outra thread.

O que serve de lição

O caso mostra o custo de um padrão incomum de uso: o bug era raro, e só um usuário que controla o checkpoint manualmente e o executa com frequência o encontrava com regularidade. O texto também registra o desgaste causado por vários incidentes seguidos na página de status.

O que eu tiro desse caso como dev

A tentação é ler isso como “até o SQLite tem bug” e seguir a vida. Acho que a lição é mais incômoda: o bug ficou escondido por mais de uma década porque quase ninguém usava o SQLite daquele jeito. Quem sai do caminho feliz de uma ferramenta madura — checkpoint manual, agressivo, sob carga — vira, sem querer, o time de QA dela. Não tem problema fazer isso, mas é preciso saber que você está fazendo.

Toda vez que eu configuro algo “mais avançado” do que o padrão (pool de conexão customizado, modo de journal diferente, flush manual), anoto em algum lugar que aquilo é um desvio consciente. Quando aparecer um problema estranho, essa lista é o primeiro lugar onde eu olho.

Três coisas que eu faria hoje se usasse SQLite em produção

  • Conferir a versão. Pelo relato, versões anteriores à 3.51.3 são afetadas. Lembre que o SQLite costuma vir embutido no runtime ou na biblioteca da linguagem — a versão do sistema operacional pode não ser a que seu app usa. Pergunte ao próprio driver.
  • Testar o backup, não só gerar. O sinal que salvou a Tailscale foi corrupção aparecendo nos backups. Backup que nunca é restaurado e checado (um PRAGMA integrity_check na cópia já ajuda) é só um arquivo ocupando disco.
  • Alertar sobre o raro. Dezenove ocorrências em seis meses parece pouco até você perceber que cada uma derrubou parte do plano de controle. Erro raro com impacto alto merece alerta próprio, não uma linha perdida no log.

E onde entra a IA nessa história?

Em lugar nenhum — e é isso que eu acho interessante. A solução veio de telemetria, paciência, suporte pago e mantenedores que conhecem o código há anos, criando uma ferramenta de depuração específica para o problema. Condição de corrida em checkpoint de banco é o tipo de bug em que modelos de linguagem são fracos: o erro não aparece no texto do código, aparece na intercalação de eventos no tempo.

Não é argumento contra usar IA. É argumento para não terceirizar para ela as partes que exigem modelo mental do sistema. Se um agente sugerir mudança em código concorrente — locks, filas, checkpoints, retries —, eu trato como trecho de alto risco, com teste de estresse antes do merge. Isso está no meu checklist de segurança antes de colar código do ChatGPT em produção, e é o mesmo motivo pelo qual eu insisto que IA não entende o sistema que você mantém.

Para mim, o texto da Tailscale vale mais como modelo de postmortem do que como notícia de bug: sintoma, investigação, causa, correção e o desgaste humano, tudo documentado. Se o seu time não escreve postmortem assim, esse é um bom exemplo para copiar.

Compartilhe conhecimento

Este conteúdo foi útil para você?

Envie para alguém que também pode aproveitar.

Conteúdo recomendado

Continue explorando