Quando o agente escreve migration, o banco precisa dizer não

Migration de banco gerada por agente de IA não é só mais um diff no PR. Ela muda estado persistente, pode apagar dados e costuma falhar por detalhes que o teste unitário não vê: ordem de deploy, locks, dados duplicados, coluna obrigatória, rollback ruim e permissão excessiva.

Em 2026, o Stack Overflow em "2025 Developer Survey: AI" informou que 84% dos respondentes usam ou planejam usar IA no desenvolvimento, contra 76% no ano anterior; entre profissionais, 51% usam diariamente (Stack Overflow, "2025 Developer Survey: AI", 2025, consultado em 2026-07-22). O volume deixou de ser novidade. A pergunta agora é onde o agente pode tocar.

Resumo prático

• Agente pode propor migration, mas não deve aplicar no banco real.
• O CI precisa simular, lintar e exigir prova antes do merge.
• Mudança destrutiva pede revisão humana, mesmo com teste verde.
• Rollback não é promessa do agente; é contrato testado.

Por que migration de agente merece um gate próprio?

Em 2026, o GitHub Blog em "Agent pull requests are everywhere" relatou mais de 60 milhões de revisões com Copilot code review, crescimento de 10 vezes em menos de um ano e mais de uma em cada cinco revisões envolvendo agente (GitHub Blog, "Agent pull requests are everywhere", 2026, consultado em 2026-07-22). Migration merece gate próprio porque o custo do erro não fica só no código.

Um agente consegue alterar modelo, ORM, query, teste e arquivo SQL na mesma sessão. Isso parece eficiência. O risco é que o PR mostre coerência local enquanto o banco real tem dados antigos, tenants ativos, jobs atrasados e versões diferentes da aplicação rodando em paralelo.

O gate próprio separa três perguntas. A migration aplica em um banco descartável? Ela é compatível com a versão anterior da aplicação? Ela contém operação destrutiva, data-dependent ou bloqueante? Se qualquer resposta falhar, o agente volta para o loop sem tocar em produção.

Cápsula citável: Migration gerada por agente precisa de gate próprio porque revisão de código não prova segurança de estado. Com mais de 60 milhões de revisões de código por Copilot no GitHub, a escala do agente exige CI que simule banco, bloqueie risco e preserve revisão humana.

Esse assunto continua o harness de agentes de código para PRs confiáveis. Lá, o foco é o fluxo completo. Aqui, o corte é o ponto mais caro: estado persistente.

O que o CI deve fazer antes de aceitar a migration?

Em 2026, o arXiv em "AI Agent Pull Requests on GitHub" analisou 33.596 PRs de agentes em 2.807 repositórios e encontrou pares coativos em 40,2% dos repositórios no recorte de sobreposição exata (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-22). O CI precisa detectar concorrência e risco antes do revisor humano.

O primeiro passo é tratar migration como artefato executável, não como texto. O CI deve subir banco descartável, aplicar estado base, rodar a migration, executar smoke tests de leitura e escrita, comparar schema final e anexar evidência curta ao PR.

O segundo passo é separar permissão de análise. O agente pode gerar arquivo e rodar dry-run. Ele não recebe credencial de produção. Se a tarefa precisa inspecionar dados reais, use réplica sanitizada, snapshot ou consulta read-only revisada por humano.

Cápsula citável: O CI de migration agentic precisa executar a mudança, não apenas ler SQL. O estudo do arXiv mediu 33.596 PRs agentic; quando agentes trabalham em paralelo, banco descartável, lint e resumo de prova reduzem erro que merge textual não vê.

Para runs longos, o custo de contexto vira parte desse contrato. Eu uso RemoteCode para manter continuidade em fluxos agentic de Codex e Claude Code com menos repetição de contexto quando o agente precisa atravessar schema, logs e evidências de CI; é uma ferramenta minha, então a menção aqui é editorial e ligada ao problema de tokens.

Como montar dry-run com shadow database?

Em 2026, a documentação do Prisma em "About the shadow database" descreve a shadow database como um segundo banco temporário criado e apagado automaticamente no prisma migrate dev, usado para detectar drift e potencial perda de dados (Prisma, "About the shadow database", 2026, consultado em 2026-07-22). Use esse padrão como ideia, mesmo fora do Prisma.

O dry-run precisa nascer limpo. Suba Postgres, MySQL ou outro banco em container, aplique migrations já aceitas, rode a migration nova e compare o estado final. Depois repita a partir de um snapshot parecido com produção, com dados sanitizados suficientes para acionar constraints.

O agente deve receber a saída resumida. Não devolva dump inteiro para o modelo. Dê erro, comando, nome da migration, tipo de falha, tabela afetada e próximo limite. Isso alimenta um loop self-correcting sem vazar dados e sem gastar contexto com ruído.

{
  "migration": {
    "origem": "agente",
    "ambiente": "banco_descartavel",
    "dry_run": "obrigatorio",
    "dados_reais": "bloqueados",
    "producao": "sem_credencial"
  }
}

Cápsula citável: Shadow database é o modelo operacional para migration de agente: criar um banco temporário, aplicar histórico, testar o diff e descartar o ambiente. A documentação do Prisma usa esse mecanismo para drift e perda de dados; no CI, ele vira limite de segurança.

Esse desenho encaixa com loop self-correcting de agente no CI. O agente pode corrigir a migration, mas só a partir de feedback pequeno e verificável.

Quais mudanças destrutivas devem bloquear o agente?

Em 2026, a documentação do Atlas em "Migration Analyzers" define mudança destrutiva como alteração de schema que resulta em perda de dados, como ALTER TABLE users DROP COLUMN email_address (Atlas, "Migration Analyzers", 2026, consultado em 2026-07-22). O bloqueio deve começar por drop, rename inseguro e constraint que depende dos dados atuais.

Nem todo risco parece destrutivo no diff. Adicionar índice único pode falhar se já houver duplicatas. Tornar coluna obrigatória pode falhar se existem nulos. Renomear coluna pode quebrar a versão antiga da aplicação durante deploy azul-verde ou rolling.

O agente pode sugerir plano expand-contract: criar coluna nova, escrever nos dois lugares, backfill, trocar leitura e remover depois. Mas a remoção final precisa de pre-check e aprovação. Se o agente tenta comprimir tudo em uma migration só, o CI deve devolver a falha.

Cápsula citável: O lint de migration deve bloquear mais que DROP. Atlas lista mudanças destrutivas, data-dependent e incompatíveis; para agentes, esses alertas precisam virar erro de CI, porque o modelo tende a otimizar o diff, não a janela operacional.

Para risco de ferramenta, combine isso com allowlist de MCP para agentes de código. Migration segura começa antes do SQL: começa na permissão que impede o agente de achar credencial errada.

Onde entram hooks, JSONL e revisão humana?

Em 2026, a documentação de permissões do Claude Code afirma que hooks PreToolUse podem negar, forçar prompt ou permitir uma chamada de ferramenta, sem burlar as regras de permissão (Claude Code Docs, "Configure permissions", 2026, consultado em 2026-07-22). Use hooks para negar comando perigoso antes que vire hábito.

Um hook simples pode bloquear psql contra host de produção, negar DROP DATABASE, exigir confirmação para ALTER TABLE, ou impedir que arquivos de migration antigos sejam editados fora do último timestamp. A regra deve viver fora do prompt, porque prompt é conselho. Hook é política executável.

Em 2026, a documentação da OpenAI em "Non-interactive mode" diz que codex exec --json emite JSON Lines com eventos como thread.started, turn.started, turn.completed, turn.failed, item.* e error (OpenAI Developers, "Non-interactive mode", 2026, consultado em 2026-07-22). Guarde esse JSONL como artefato restrito e publique só o resumo seguro no PR.

Cápsula citável: Prompt não é controle de mudança. Claude Code permite hooks que negam tool calls, e Codex emite JSONL para auditoria; juntos, eles criam trilha e bloqueio para migrations agentic antes de qualquer credencial sensível aparecer.

Esse ponto conversa com observabilidade de agentes de código no CI. Se a migration falha, o revisor precisa saber se foi erro de schema, permissão, dado ou tentativa repetida.

Qual contrato mínimo cabe no próximo PR?

Em 2026, o arXiv em "AI Agent Pull Requests on GitHub" mediu conflito textual de 41,7% em pares cross-agent contra 19,8% em pares intra-agent ao simular merges reais (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-22). Para migration, conflito textual é só o começo; o contrato mínimo precisa provar execução.

Adote um arquivo agent-migration-report.json por PR. Ele deve declarar ferramenta, commit base, migration nova, banco descartável usado, comando de dry-run, resultado do lint, risco detectado, plano de rollback ou roll-forward, e pessoa responsável pela aprovação final.

Também proíba três atalhos. O agente não edita migration antiga sem motivo explícito. O agente não recebe URL de produção. O agente não marca rollback como pronto sem executar o caminho de volta ou documentar que a estratégia real é roll-forward.

Cápsula citável: O contrato mínimo para migration de agente é um relatório executável por PR. Como cross-agent conflict chegou a 41,7% no arXiv, o time precisa declarar escopo, dry-run, lint, isolamento de dados e aprovação humana.

Se você já escreveu evals de regressão para agentes de código, adicione um caso específico para schema. O teste não precisa provar tudo. Ele precisa impedir que o agente trate banco como arquivo temporário.

FAQ sobre migration de banco gerada por agente

Agente pode criar migration de produção?

Pode propor a migration, mas não deve aplicar no banco real. Em 2026, o Stack Overflow informou que 51% dos desenvolvedores profissionais usam IA diariamente (Stack Overflow, "2025 Developer Survey: AI", 2025, consultado em 2026-07-22). Esse uso pede separação entre geração de código e permissão operacional.

Dry-run substitui revisão de DBA ou backend sênior?

Não. Em 2026, o arXiv analisou 33.596 PRs de agentes, mas conflito de merge ainda não cobre semântica de dados (arXiv, "AI Agent Pull Requests on GitHub", 2026, consultado em 2026-07-22). Dry-run reduz erro mecânico; revisão humana avalia impacto, janela e rollback.

Posso deixar o agente usar snapshot de produção?

Só se o snapshot for sanitizado e tiver acesso controlado. Em 2025, o AI Incident Database catalogou o caso Replit como incidente de comandos destrutivos durante code freeze com perda de dados de produção (AI Incident Database, "Incident 1152", 2025, consultado em 2026-07-22). O agente deve ver dados mínimos.

Qual ferramenta usar para lint de migration?

Use a que combina com sua stack. Em 2026, Atlas documenta atlas migrate lint para analisar migration localmente e em CI contra operações destrutivas, mudanças incompatíveis e locks (Atlas, "Verifying Migration Safety", 2026, consultado em 2026-07-22). Prisma, Flyway e Liquibase pedem gates equivalentes.

Fechamento

Agente de código acelera migration quando o pipeline trata banco como sistema vivo. Ele atrapalha quando o time confunde SQL válido com mudança segura.

O caminho pragmático é pequeno: branch isolada, dry-run em banco descartável, lint destrutivo como erro, JSONL restrito, hook de permissão e aprovação humana para irreversível. Depois disso, o agente continua útil. Ele só deixa de ser dono da última palavra.

Fontes consultadas

• Stack Overflow, "2025 Developer Survey: AI", consultado em 2026-07-22, https://survey.stackoverflow.co/2025/ai
• GitHub Blog, "Agent pull requests are everywhere. Here's how to review them", consultado em 2026-07-22, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
• arXiv, "AI Agent Pull Requests on GitHub: Frequency, Structure, and Merge Conflict Rates", consultado em 2026-07-22, https://arxiv.org/abs/2607.04697
• Prisma, "About the shadow database", consultado em 2026-07-22, https://www.prisma.io/docs/orm/prisma-migrate/understanding-prisma-migrate/shadow-database
• Atlas, "Migration Analyzers", consultado em 2026-07-22, https://atlasgo.io/lint/analyzers
• Atlas, "Verifying Migration Safety", consultado em 2026-07-22, https://atlasgo.io/versioned/lint
• Claude Code Docs, "Configure permissions", consultado em 2026-07-22, https://code.claude.com/docs/en/permissions
• OpenAI Developers, "Non-interactive mode", consultado em 2026-07-22, https://learn.chatgpt.com/docs/non-interactive-mode
• AI Incident Database, "Incident 1152", consultado em 2026-07-22, https://incidentdatabase.ai/cite/1152/
• The Register, "Vibe coding service Replit deleted user's production database, faked data, told fibs galore", consultado em 2026-07-22, https://www.theregister.com/software/2025/07/21/vibe-coding-service-replit-deleted-production-database/719783