Diretrizes para ferramenta de backfill de execução única para scripts internos seguros

Por que scripts de backfill precisam de guardrails

Um backfill é um trabalho único que atualiza registros existentes para que correspondam a uma nova regra. Talvez você tenha adicionado uma nova coluna e precise preenchê-la. Talvez esteja corrigindo linhas ruins de uma release com bug. Ou reestruturando dados após uma migração.

Mesmo quando a lógica é simples, o risco não é. Backfills tocam dados reais em produção, muitas vezes em alta velocidade. Um WHERE errado pode atualizar milhões de linhas. Um loop que assume “um usuário = um registro” pode criar duplicatas. Um script que roda ao meio-dia pode sobrecarregar o banco e tirar sua aplicação do ar.

Scripts internos ainda precisam de regras de segurança porque normalmente contornam proteções como revisão de código, testes, rollout gradual e monitoramento. E diferentemente de uma requisição web, um backfill continua até terminar ou travar.

Gatilhos comuns incluem:

• Adicionar um novo campo (como status ou normalized_email) e preenchê-lo para usuários existentes
• Corrigir dados criados por automações (incluindo protótipos gerados por IA que escreveram linhas inconsistentes)
• Recalcular valores derivados após um bug ou mudança de lógica

“Execução única” não significa “alguém promete rodar só uma vez.” Significa que a ferramenta evita reruns acidentais, mostra o que vai mudar antes de alterar qualquer coisa e deixa evidência do que aconteceu. Guardrails transformam um script arriscado em uma operação controlada que você pode explicar, repetir com segurança se necessário e auditar depois.

Defina o escopo como uma pequena mudança em produção

Trate um backfill de execução única como uma pequena release em produção. Se você mantiver vago, ele vai crescer até se tornar um script arriscado que toca mais dados do que deveria.

Comece com uma meta de uma frase que seja específica o suficiente para gerar debate. Nomeie o que vai mudar, quais registros se qualificam e o que não será tocado. “Atualizar todos os usuários” não é escopo. “Definir email_verified=true para usuários criados antes de 2025-01-01 que já têm um token verificado, e deixar todos os outros inalterados” é um escopo.

Decida desde o início como provará que funcionou. Sucesso deve ser mensurável, não uma sensação depois que o script termina. Combine totais com algumas verificações pontuais para detectar erros de lógica cedo.

Um plano de sucesso simples geralmente inclui contagens esperadas, alguns IDs exemplo para inspecionar antes e depois, e pelo menos uma checagem de sanidade (por exemplo, sem nulos introduzidos e sem duplicatas criadas). Se a mudança for reversível, descreva como revertê-la. Se não for facilmente reversível, trate como execução de maior risco e aperte os guardrails.

Escolha a janela de tempo e a abordagem de rollout mais segura. Se a mudança pode impactar logins, cobrança ou permissões, evite pico de tráfego. Se possível, execute um lote pequeno primeiro, verifique os resultados e então continue.

Por fim, seja explícito sobre quem pode rodar e quem deve revisar. “Qualquer pessoa do time” é como acontecem escritas acidentais em produção. Uma linha de base boa é: uma pessoa prepara e explica o plano, uma segunda revisa a query e o escopo, e apenas um pequeno conjunto de contas confiáveis pode executar.

Se você herdou um protótipo gerado por IA (por exemplo, de Cursor, v0, ou Replit), assuma que há casos de borda no modelo de dados e nos caminhos de auth. Isso torna escopo apertado e revisão real ainda mais importantes.

Controle de acesso e aprovações que funcionam de verdade

Uma ferramenta de backfill de execução única é perigosa principalmente porque é rápida. Uma pessoa pode mudar muitos dados antes de alguém notar. O padrão mais seguro é separar quem pode executar, quem pode aprovar e quem pode inspecionar o que aconteceu.

Comece com privilégio mínimo. Trate o backfill como um “mini sistema” com um conjunto de permissões apertado. Para muitas equipes, três papéis são suficientes:

• Runner: pode executar o job apenas com parâmetros aprovados
• Approver: pode revisar o plano e desbloquear uma única execução
• Observer: pode ver logs e resultados, mas não executar

Para execuções de maior risco (pagamentos, autenticação, PII, deletes), adicione um passo claro de break-glass. Torne propositalmente incômodo: uma segunda aprovação, um token com tempo limitado e um motivo explícito que seja salvo. Isso evita acidentes do tipo “vou só rodar rápido” às 2 da manhã.

Proteja também contra a falha mais comum no mundo real: rodar no ambiente errado. Adicione checagens rígidas antes de qualquer escrita. Verifique o host do banco, o nome do ambiente e um valor canário conhecido (por exemplo, uma configuração exclusiva de produção) e recuse continuar se algo não bater. Se você suportar múltiplos tenants, exija uma allowlist de tenants explícita.

Armazene uma trilha de auditoria imutável para responder “quem rodou o quê, quando e por quê” em segundos. Registre a identidade do operador, versão do código, parâmetros, contagens de linhas, início/fim e as aprovações usadas.

Modo dry-run: torne as mudanças visíveis antes de acontecerem

Um dry-run é a forma mais barata de capturar erros antes que toquem produção. Para uma ferramenta de backfill de execução única, trate dry-run como recurso de primeira classe, não um extra.

A saída do dry-run deve responder quatro perguntas rapidamente:

• Quantas linhas vão mudar
• O que vai mudar (com exemplos)
• Aproximadamente quanto tempo vai levar
• Se não fará nada

Esse último ponto importa. Se seus filtros estão errados, você quer que a ferramenta diga “0 updates” em destaque antes de perder uma hora assistindo logs.

Faça do dry-run o padrão. Exija uma flag explícita (por exemplo, --execute) para realmente escrever mudanças. Essa única escolha previne o clássico “testei e esqueci de remover as credenciais reais”.

Um bom relatório de dry-run não precisa ser longo. Deve mostrar totais (scanned, matched, will change) e uma pequena amostra de valores antes/depois para alguns IDs, com as diferenças exatas de campo. Se a ferramenta gera SQL ou monta joins complexos, imprimir o SQL final e os parâmetros frequentemente revela filtros faltando, tabela errada ou bug de fuso horário.

Exemplo: você planeja backfill user.status = 'active' para contas que verificaram email. Dry-run deve mostrar “Matched: 12,430; Will change: 12,429” e destacar o registro que não mudaria porque já está ativo. Esse número único é uma checagem de sanidade.

Logs de progresso e observabilidade da execução

Um backfill de execução única é mais seguro quando você pode responder, em segundos: o que ele está fazendo agora, o que mudou e o que fazer se ele parar. Saída no terminal sozinho não é suficiente. Trate a execução como um pequeno job de produção com trilha documental.

Comece com logs estruturados fáceis de buscar. Cada linha de log deve incluir um run ID, um timestamp e os parâmetros de lançamento (ambiente, flag de dry-run, tamanho do batch, filtros de escopo). Assim, quando alguém perguntar “tocamos o cliente X?”, você consegue provar.

Registre alguns eventos consistentemente: início (quem, versão, parâmetros), progresso por lote (scanned, updated, skipped, errors), qualquer throttling/backoff e fim (totais, duração, sucesso ou falha). Se uma checagem de segurança parar o run, registre isso claramente como “motivo_da_parada”, não um erro genérico.

O progresso deve ser visível enquanto o script roda, não só depois. Uma linha a cada N registros é suficiente, mas inclua números acionáveis: lotes processados, taxa atual, ETA aproximada e contagem de erros.

Grave progresso em local durável caso o terminal morra. Opções comuns são uma tabela no banco (uma linha por run mais checkpoints por lote) ou um arquivo de log enviado ao seu sistema normal de logs. O registro durável deve incluir o último checkpoint completado para decidir se retomar ou parar.

Por fim, adicione hooks de alerta para os resultados que importam: runs falhados, conclusão parcial e runs travados (sem progresso por um tempo definido). Se um lote fica re-tentando por 10 minutos, alerte para que alguém pause o job antes que cause carga extra ou mudanças pela metade.

Evitar reruns e double-processing

Uma ferramenta de backfill de execução única deve assumir que alguém vai clicar “run” duas vezes. Pode ser você cinco minutos depois por causa de timeout. Ou outro colega que não viu sua mensagem. Seu trabalho é tornar a segunda tentativa inofensiva.

Comece com idempotência quando possível. Se o backfill define um campo para um valor calculado, escreva de modo que reexecutar produza o mesmo estado final. Se o backfill cria linhas, prefira um upsert com chave estável em vez de um insert cego. Se não der para ser totalmente idempotente, facilite detectar e pular “já processado”.

Um run ledger é o próximo guardrail. Crie uma pequena tabela que registre cada execução, incluindo uma assinatura do run (inputs + versão do código + escopo alvo). Antes de qualquer trabalho, verifique o ledger e pare rigidamente se essa assinatura já tiver sido concluída com sucesso.

Para o lock, use algo distribuído (lock de linha no banco, advisory lock ou uma “linha de lock” no ledger). A regra é simples: se já existe um run “em execução” para aquela chave de lock, saia.

Exemplo concreto: você está backfilling status=active para contas com faturas pagas. A assinatura inclui a data de corte e o filtro. Se alguém rerodar com a mesma assinatura, a ferramenta se recusa. Se rerodarem com nova data de corte, a ferramenta permite e a atualização idempotente mantém contas anteriores inalteradas.

Projetar para falhas parciais e retries seguros

Assuma que seu backfill vai falhar no meio. Redes falham, linhas têm surpresas e o app principal continua servindo tráfego. O objetivo não é “nunca falhar.” É “falhar sem fazer bagunça”.

Comece com batching que tenha ordem clara e um checkpoint. Escolha uma ordenação estável (geralmente pela PK ou created time) e registre o que foi completado após cada lote. Mantenha lotes pequenos para que um único lote termine rápido, assim você não segura locks muito tempo nem cria rollbacks enormes. Se preciso retomar, o checkpoint deve dizer onde continuar sem adivinhações.

Retries precisam de política. Problemas temporários (timeouts, sobrecarga breve) podem re-tentar. Rate limits devem re-tentar com backoff. Erros de validação e incompatibilidade de esquema não devem re-tentar. Erros de permissão devem pausar e alertar. Qualquer coisa que sugira que você pode estar escrevendo dados errados deve falhar rápido.

Proteja o app principal com backpressure. Adicione uma limitação simples (linhas por segundo) e reduza automaticamente quando o banco estiver mais lento. Se a latência ou taxa de erro do app subir, o backfill deve desacelerar ou parar. Um backfill nunca vale uma queda.

Prefira padrões de escrita seguros: transações curtas por lote, checks “update somente se não estiver atualizado” e upserts quando apropriado. Evite transações longas que travem tabelas grandes. Evite varreduras completas quando uma query direcionada resolve.

Passo a passo: blueprint de uma ferramenta segura de backfill de execução única

Uma ferramenta de backfill deve ser entediante de operar. O objetivo é tornar o caminho seguro o mais fácil e ações arriscadas ruidosas e difíceis.

1. Defina o contrato antes de escrever código. Anote os inputs exatos (intervalo de datas, IDs de tenant, filtros de status), os registros que espera tocar e o que significa “feito”. Adicione um preflight que imprime contagens e falhe rápido se o filtro for muito amplo.

2. Construa o dry-run primeiro e depois bloqueie a execução. O dry-run deve fazer tudo, exceto as escritas: carregar candidatos, aplicar regras e mostrar um resumo das mudanças planejadas. Coloque a execução real atrás de uma flag explícita como --execute para esquecer a flag ser seguro.

3. Crie um run ID, lock e run ledger. Gere um run ID único e salve quem iniciou, quando, parâmetros e status (started, completed, failed). Pegue um lock para que duas pessoas não rodem o mesmo job ao mesmo tempo.

4. Adicione logs de progresso, checkpoints e resume. Logue quantos itens foram scanned, updated, skipped e errored a cada N registros. Salve checkpoints (como “último ID processado”) para poder retomar após um crash.

5. Prove em staging, então faça canary em produção. Rode contra dados de staging primeiro. Em produção, comece com um batch pequeno (por exemplo, 50 linhas) e verifique o resultado com uma query simples ou relatório antes de processar tudo.

Exemplo concreto: se você está preenchendo created_by ausente, o dry-run deve mostrar quantas linhas mudariam por tenant e a execução deve gravar apenas essas linhas enquanto registra o run ID no ledger.

Exemplo: consertando um erro de dados em produção sem pânico

Um time lança um protótipo gerado por IA em produção. Uma semana depois nota algo assustador: muitos usuários foram salvos com o papel errado. Alguns admins viraram “member” e alguns membros viraram “admin”. Ninguém quer “rodar um script” e torcer para dar certo.

Eles constroem uma ferramenta de backfill de execução única que prova o que vai mudar antes de alterar qualquer coisa. Primeiro, o dry-run lê os papéis atuais, calcula os papéis corretos da fonte da verdade e imprime um resumo claro: quantos usuários vão mudar, alguns exemplos antes/depois (com IDs de usuário, não emails) e um detalhamento do que está indo para onde.

Após revisão, a execução roda em lotes pequenos (por exemplo, 500 usuários por vez). Cada lote escreve logs de progresso: número do lote, início, quantos foram alterados e quaisquer erros. Também escreve uma entrada no run ledger com um run ID único, quem acionou e a versão exata do código. Esse ledger impede que alguém rode duas vezes por acidente.

Quando o run termina, eles verificam em vez de adivinhar: contagens conferem com o dry-run, um punhado de usuários em diferentes papéis está correto, telas admin ainda exigem admin e erros de permissão não dispararam. É muito cuidado, mas sai mais barato que um rollback.

Erros comuns que causam incidentes evitáveis

A maioria dos incidentes com backfills não vem de bugs “difíceis”. Acontecem porque um script que deveria ser tratado como uma pequena mudança em produção é tratado como um one-off rápido.

Uma falha comum é rodar contra produção sem salvaguardas. Alguém aponta o script para prod “só dessa vez”, mas não há checagem de ambiente, passo de confirmação ou limite de permissão. Uma boa ferramenta de execução única deve dificultar mirar produção por engano e facilitar provar quem rodou e por quê.

Erros no dry-run são igualmente arriscados. Um dry-run que usa queries diferentes, filtros diferentes ou pula validação gera confiança falsa. Então a execução real toca mais linhas do que esperado. Dry-run deve executar a mesma seleção e lógica do run real, com a etapa de escrita substituída por preview.

Reruns silenciosos causam dano. Duas pessoas podem rodar ao mesmo tempo ou alguém reroda após timeout. Sem lock ou marcador de idempotência, você obtém processamento duplo: duplicatas, valores sobrescritos ou contadores quebrados.

Logging é outro ponto cego. Logs só no console somem quando o terminal fecha. Depois de um incidente você fica sem timeline, sem contagens e sem registro dos parâmetros.

Os padrões por trás da maioria dos incidentes evitáveis são simples:

• Sem checagens rígidas de ambiente (prod parece staging)
• Dry-run não bate com a execução
• Sem lock ou run ledger, então pode rodar duas vezes
• Logs não são salvos em lugar durável
• Sem batching ou checkpoints, então falhas exigem reinícios completos

Exemplo: um fundador preenche IDs de cliente “faltando” e roda como um update gigante. Dá timeout no meio, então reroda. Agora metade das linhas foi alterada duas vezes e o time não consegue dizer quais foram.

Checklist rápido antes de apertar “run”

Antes de começar, faça uma checagem rápida e entediante. A maioria dos incidentes acontece porque alguém confiou no prompt do terminal, pulou o dry-run ou esqueceu que o script pode rodar duas vezes.

• Confirme o ambiente de duas formas: o que você pensa que é (config/CLI) e o que a ferramenta verifica (ela deve recusar rodar a menos que veja o host ou project ID esperados).
• Revise a saída do dry-run e salve o resumo em algum lugar para referência. Se o dry-run diz 10.000 linhas e você esperava 1.000, pare.
• Certifique-se de que as aprovações estão registradas (quem aprovou e quando) e que verificações de lock/run-ledger estão habilitadas para essa assinatura exata.
• Confirme que você vê contadores de progresso se movendo (processed, updated, skipped, failed) e que alguém está observando o run.

Depois que terminar, não chame de concluído até fazer as checagens pós-run (contagens reconciliam, amostras estão corretas e erros são zero ou entendidos).

Próximos passos: torne repetível e peça uma segunda opinião

Uma ferramenta de backfill de execução única é “one-time” apenas na execução, não na forma cuidadosa como é construída. Trate a primeira execução como ensaio para o próximo incidente: torne o processo repetível, documentado e fácil para outra pessoa revisar.

Saiba quando parar e pedir ajuda. Se descobrir edge cases no esquema, qualidade de dados confusa (nulls, duplicatas, IDs incompatíveis) ou qualquer coisa envolvendo auth e permissões, pause. Esses são os momentos em que uma segunda opinião rápida evita suposições que viram escritas irreversíveis.

Mantenha a documentação curta e auditável: quais dados foram alvo, quais filtros foram usados, em qual ambiente rodou, quem aprovou e o que você checou antes e depois. Inclua a versão do script e uma cópia do resumo do dry-run.

Se estiver lidando com uma base de código gerada por IA e não se sentir seguro quanto ao backfill, FixMyMess (fixmymess.ai) faz diagnóstico e fortalecimento de codebase para problemas como queries inseguras, risco de rerun e falhas de segurança antes de você mexer nos dados de produção.