
Yurumi: a memória que travava o próprio banco
A frase que aparecia em todo lugar menos onde importava
sqlite3.OperationalError: database is locked tem uma característica que a torna caríssima de diagnosticar: ela nunca aponta o culpado. Diz que o arquivo está ocupado, mas não diz por quem, nem por quanto tempo, nem desde quando. Quando o banco é local e o processo é único, a resposta é óbvia. Quando seis processos dividem o mesmo arquivo, a mensagem vira um bilhete sem assinatura.
No Yurumi — a camada de memória que guarda o que os agentes conversaram, decidiram e aprenderam — esse arquivo único é o centro de tudo. É onde ficam as memórias, o índice de busca textual, os anúncios de trabalho entre agentes e o estado dos jobs. Quatro dias seguidos, quatro commits, e cada um revelou que a causa estava num lugar diferente. Todos tinham a mesma assinatura no log.
As ferramentas que uso neste projeto ficam na loja de skills — a primeira é grátis.
O primeiro: 39 descritores abertos por um código que nunca fechava
Onze de novembro. O sintoma que chegou primeiro foi um teste de ida-e-volta quebrando por causa do serviço, não do teste. A rota que publica e encerra um anúncio de trabalho entre agentes passou a demorar trinta segundos — o tempo exato do timeout de espera do lock — para então falhar.
A medição explicou o resto. O armazenamento de anúncios criava a conexão sob demanda, de forma preguiçosa, e nunca chamava o fechamento. Cada anúncio publicado por uma requisição HTTP deixava uma conexão aberta. Em seis horas de vida, um único worker acumulou 39 descritores abertos no mesmo arquivo, sendo 17 deles apontando para um arquivo de escrita pendente que já tinha sido removido do disco. O processo segurava locks sobre um arquivo que não existia mais.
A cura foi chata e é exatamente por isso que ela funciona: fechamento explícito, suporte a gerenciamento de contexto, e finally nos três pontos de entrada. Um detalhe importou mais do que os outros: só fecha o que é seu. A store pode ser injetada de fora, e quem injeta é o dono da conexão — fechar o que não abriu é trocar um vazamento por um uso depois da liberação. Os dois tratadores de exceção que engoliam tudo em silêncio passaram a registrar o tipo e o motivo. Prova medida: cinco ciclos de abrir, encerrar e listar deixavam 4 descritores antes e deixam 4 depois, em vez de crescer um por chamada.
O segundo e o terceiro: o mesmo vazamento em outro lugar, e um schema que pedia a escrita
Treze de novembro, dois commits no mesmo dia. O primeiro foi o mesmo defeito em outro ponto: o laço do agente instanciava a store e não a fechava. O job roda a cada dez minutos. Cada execução deixava uma conexão aberta com transação pendente, e a execução seguinte morria no mesmo erro — código de saída 1 em todo tick, um journal de 52 KB pendente no disco e o arquivo principal já em 801 MB.
store = MemoryStore(collection=args.collection)
try:
loop = AgentLoop(store)
summary = loop.run_once(dry_run=args.dry_run)
finally:
store.close()
O segundo commit do dia foi o mais instrutivo, porque o defeito não era um vazamento: era o oposto. O schema era criado em todo boot da store, e cada job de cron instancia a store. A criação de tabela exige lock de escrita. Com seis processos dividindo o arquivo, o script de criação estourava o lock e o construtor morria antes de fazer qualquer coisa útil.
A parte que surpreende é por que o timeout de espera de trinta segundos não salvava. Aquele script não é uma transação única: ele faz commit implícito a cada comando. O timeout vale para esperar o lock, não para desfazer o que já foi parcialmente confirmado.
A cura teve três partes, e a primeira é a mais importante:
ja_existe = conn.execute(
"SELECT 1 FROM sqlite_master WHERE type='table' AND name='memories'"
).fetchone() is not None
if ja_existe:
return
Se a tabela existe, não há schema a criar — então não há motivo para pedir lock de escrita. Só quem precisa criar é que espera, com backoff de seis tentativas. E a última parte é uma concessão deliberada: falha de lock ao inicializar não derruba o construtor. O store nasce assim mesmo e quem reporta o problema é o primeiro INSERT. Prova: cinco inicializações passaram com um lock de escrita retido por outro processo (antes: exceção), um banco novo criou tabela e índice de busca textual, e oito de oito escritas passaram sem lock, contra duas de três antes.
O que isso muda
O banco nunca esteve corrompido. Ele estava ocupado — e a ocupação era feita pelo próprio código, que esquecia conexões abertas e pedia escrita sem precisar. A mensagem de erro estava tecnicamente correta e completamente inútil, porque o culpado e a vítima eram o mesmo programa.
A lição transferível é sobre onde olhar primeiro. Diante de um lock, o instinto é aumentar o timeout. O timeout só compra tempo para um processo que vai demorar o que precisa; quando o problema é vazamento de descritor, aumentar a espera só faz o sintoma chegar mais tarde e mais caro. A pergunta certa não é quanto esperar, é quem está segurando. A segunda pergunta, menos óbvia: essa operação precisava de escrita? Um schema já existente não precisa.
Fechar isso exigiu tratar todos os pontos de abertura, não o principal. Curar o laço do agente e deixar o caminho de anúncios vazando dá o mesmo lock, com metade do diagnóstico. Vazamento é sempre uma soma — e uma soma não fecha pela parcela maior.
O quarto: quando o guard e a fonte brigavam
Catorze de novembro trouxe um defeito de outra natureza, no mesmo arquivo de fundo. Um limitador de tempo no caminho de prefetch existia porque o trabalho de anúncio, sem teto, estourava o orçamento de resposta — medido em 24,79 segundos contra um orçamento de 20. O trecho foi aplicado no espelho do plugin, e um guard reaplicava aquele trecho a cada quinze minutos. O sincronizador copiava a fonte por cima logo em seguida, sem o trecho. Guerra infinita: o job saía com código 4 em todo tick e a divergência de hash entre fonte e espelho era permanente.
A cura foi parar de consertar o espelho e mudar a fonte — o lugar de onde o sincronizador copia. Prova: treze cópias com o mesmo hash, guard limpo em duas rodadas seguidas sem reaplicação, e o estado estável 45 segundos depois. Enquanto o conserto morar numa cópia derivada, ele vai ser desfeito pelo próximo sincronizador. Isso vale para arquivo gerado, imagem de container e configuração replicada.
Próximo passo
Os quatro consertos fecharam o sintoma, não a classe do problema. O que falta é medição contínua: acompanhar a contagem de descritores por processo ao longo do tempo, para que um vazamento novo apareça como número crescente antes de virar lock. Um guard que só olha se o serviço responde não distingue saudável de vazando devagar — e o segundo estado foi exatamente o que custou quatro dias.
Leia também
Mesmo projeto, mesma trilha — as histórias se conectam.
Próximo passo
Se isto te serviu, tem mais: escrevo sobre o mesmo assunto nos outros projetos, e a loja tem as ferramentas que eu uso aqui.
Anotado — aviso quando sair artigo novo.
Sem spam, descadastro de um clique. Também estou aqui: Loja de skills · Portfólio