Duas consultas corretas podem montar um total que nunca existiu
Um agente consulta a primeira conta, aguarda outra ferramenta e depois consulta a segunda. Entre as duas leituras, uma transferência altera os saldos. O relatório soma o valor antigo de uma conta com o novo da outra.
Cada resposta representa um estado legítimo. A combinação, porém, pode mostrar dinheiro que nunca esteve disponível naquele conjunto.
Um snapshot de leitura oferece uma visão estável dentro de uma fronteira documentada. Ele permite reunir as partes de uma análise sem trocar silenciosamente a referência de dados no meio da coleta. O desenho deve ficar no conector ou no serviço de dados, antes de o modelo interpretar o pacote.
Separe estabilidade, atualidade e cobertura
Essas propriedades respondem a perguntas diferentes:
- estabilidade: as consultas observam a mesma visão dos dados?
- atualidade: quão recente é essa visão para a decisão?
- cobertura: todos os registros do escopo foram coletados?
Uma exportação completa pode estar desatualizada. Uma consulta recente pode cobrir apenas a primeira página. Um snapshot pode ser estável e conter uma projeção que já chegou atrasada da origem.
A paginação de APIs governa a travessia. A freshness dos dados define idade tolerável. Este guia trata da visão comum usada para combinar várias leituras. O artefato final é um pacote de análise materializado, com uma garantia de consistência declarada.
Escolha uma fronteira que o sistema realmente consegue oferecer
No PostgreSQL, a documentação distingue Read Committed, padrão do produto, de Repeatable Read. Duas consultas sucessivas em Read Committed podem observar alterações confirmadas entre elas, mesmo dentro da mesma transação.
Em Repeatable Read, as consultas usam a visão estabelecida no primeiro comando que não seja de controle transacional. Mudanças posteriores de outras transações ficam fora dessa visão. Isso não transforma toda regra empresarial em uma execução serial: o próprio manual descreve limites de isolamento e anomalias possíveis.
No SQLite em modo WAL, uma transação de leitura mantém seu snapshot enquanto outro acesso pode confirmar alterações. Encerrar a transação e começar outra permite observar a versão posterior.
Esses contratos pertencem a produtos e configurações específicos. Colocar BEGIN ao redor de qualquer integração não cria a mesma garantia. Muito menos estende a transação a um CRM, um ERP e uma planilha externos.
Materialize os dados antes de chamar o modelo
Uma arquitetura útil executa este procedimento no serviço autorizado:
- fixa cliente, filtros, campos e permissões;
- abre a leitura sob o isolamento escolhido;
- executa as consultas necessárias na mesma fronteira;
- copia o resultado para um artefato protegido e imutável para aquela análise;
- confirma a cobertura e encerra a transação;
- entrega ao agente os dados e o manifesto de coleta.
Evite manter a transação aberta enquanto o modelo pensa ou enquanto uma pessoa aprova. Leitores longos podem dificultar limpeza de versões ou checkpoints, conforme o banco. Também ocupam recursos e aumentam o custo de uma tarefa que poderia trabalhar sobre uma cópia delimitada.
O acesso ao banco deve permanecer numa ferramenta de leitura com contrato conhecido. O artigo sobre acesso direto de agentes a bancos discute os limites dessa escolha. O modelo não precisa receber credencial administrativa nem liberdade para alterar o isolamento.
O manifesto deve explicar o que foi congelado
Exemplo sintético de contrato para um relatório:
pacote: carteira-unidade-sul-20261022-01
origem: serviço de relatórios autorizado
cliente: tenant de teste
escopo: contas A e B, valores inteiros sintéticos
consistencia: snapshot da mesma transação de leitura
cobertura: completa para o escopo declarado
referencia: identificador da coleta e da versão materializada
inicio_coleta: instante registrado pelo serviço
fim_coleta: instante registrado pelo serviço
pendencias: nenhuma na fixture
uso: análise, sem autorização de transferência
Horários ajudam a investigar. Eles não provam sozinhos que as consultas compartilharam o snapshot. O serviço precisa vincular manifesto, consultas e artefato à mesma execução.
Restrinja o acesso à cópia e defina seu descarte. A retenção de dados continua valendo mesmo quando o arquivo foi criado apenas para um relatório.
Ficha do laboratório: como duas leituras somam um total inexistente
EXEMPLO SINTÉTICO — duas conexões SQLite em modo WAL Escopo: contas fictícias A e B. Estado inicial A=100, B=100, total=200. A escrita muda para A=60 e B=140, preservando o total. Trilha sem snapshot compartilhado: [ ] Ler A antes da escrita: 100. [ ] Outra conexão confirma a transferência sintética. [ ] Ler B depois da escrita: 140. Conferência didática: 100+140=240 mistura momentos; não representa aumento real do total. Trilha com snapshot: [ ] Restaurar a fixture e abrir transação de leitura em WAL. [ ] Ler A=100 para estabelecer a visão. [ ] Outra conexão confirma a mesma transferência. [ ] Ler B=100 na mesma visão; soma=200. [ ] Materializar os dados e encerrar a leitura antes de chamar o modelo. Manifesto a preencher no serviço real: origem, cliente, escopo, referência da coleta, garantia de consistência, cobertura, início/fim e pendências. Horários sozinhos não provam visão comum. Limite: este laboratório local não congela CRM ou ERP externos. O pacote serve à análise; uma escrita posterior exige revalidar estado e autoridade.
Laboratório local com duas conexões SQLite
Em 22 de outubro de 2026, na preparação editorial original, foi executado um teste local com SQLite 3.53.1, modo WAL, duas conexões e dados sintéticos. Nenhum modelo, PostgreSQL ou sistema empresarial externo participou.
O estado inicial continha A = 100 e B = 100. Uma transação de escrita alterou os valores para A = 60 e B = 140, preservando o total.
Na primeira execução, as leituras ocorreram sem uma transação de leitura compartilhada:
consulta de A antes da alteração: 100
consulta de B depois da alteração: 140
soma das respostas: 240
Na segunda execução, restauramos o estado inicial, abrimos a transação de leitura e consultamos A. A outra conexão confirmou a mesma transferência. A consulta seguinte de B permaneceu na visão inicial:
consulta de A no snapshot: 100
consulta de B no mesmo snapshot: 100
soma das respostas: 200
nova consulta após encerrar o snapshot: total 200
O teste demonstra a mistura de momentos e a estabilidade da leitura nessa configuração local. Ele não homologa um serviço distribuído, uma API SaaS ou o comportamento de outro banco. A equipe deve repetir o cenário no caminho de coleta efetivamente usado pelo agente.
Quando as fontes são independentes
Um snapshot do banco de relatórios não congela automaticamente os sistemas que o alimentam. Se o CRM foi atualizado recentemente e o ERP está com atraso, a cópia pode preservar essa diferença com perfeita estabilidade.
Para combinar fontes sem transação comum, prefira uma destas estratégias conforme a necessidade:
- exportações coordenadas com corte que cada origem consiga sustentar;
- histórico versionado que permita consultar o mesmo instante, quando disponível;
- projeção consolidada com posição de atualização por origem;
- pacote com janelas distintas explicitamente registradas e conclusão limitada.
Sem garantia comum, descreva a coleta como observação durante uma janela. Bloqueie conclusões que dependam de simultaneidade não demonstrada. Um timestamp comum escrito no prompt não corrige a integração.
Uma análise estável ainda pode vencer antes da ação
O agente pode preparar uma boa recomendação sobre o pacote congelado. Se a etapa seguinte altera um objeto, a aplicação deve consultar e validar o estado atual no momento do compromisso.
O controle de concorrência protege essa escrita. Um snapshot útil para explicar a carteira não autoriza reservar estoque ou conceder crédito minutos depois sem revalidação.
Antes de liberar a integração, teste alteração entre consultas, inclusão e remoção durante a coleta, falha antes da materialização e expiração do pacote. Confira também a política para mudança de permissão depois da coleta: uma cópia antiga não pode servir para contornar uma revogação.
Fontes oficiais verificadas em 22 de outubro de 2026
- PostgreSQL 18: transaction isolation, para as diferenças entre snapshots por comando e por transação e os limites de
Repeatable Read. - SQLite: isolation in SQLite, para isolamento entre conexões, leitura em WAL e renovação do snapshot.
A materialização, o manifesto e os critérios de bloqueio são recomendações de arquitetura da publicação original. O primeiro passo de implementação é escolher uma análise real e verificar se suas consultas conseguem compartilhar uma visão demonstrável. Quando não conseguem, essa limitação precisa acompanhar o relatório.