Uma migração pode modificar milhões de registros, alimentar processos ativos e gerar efeitos fora do banco de dados. Se uma transformação falhar no meio do processo, restaurar uma cópia completa nem sempre é seguro ou aceitável: talvez novos dados tenham sido gravados depois da cópia, ou o sistema não possa ficar parado pelo tempo exigido pela restauração.
Por isso, um plano de reversão para migrações de dados não deve se resumir a um comando para voltar atrás. Ele deve estabelecer como identificar o estado afetado, quais operações podem ser desfeitas, quais exigem uma compensação e quando é melhor reparar ou retomar. A decisão é preparada antes da execução da migração, com critérios que a equipe possa verificar sob pressão.
Por que restaurar uma cópia nem sempre é uma reversão viável
Um backup serve para recuperar dados em determinados incidentes, mas restaurá-lo pode eliminar alterações legítimas feitas depois de sua criação. Também pode implicar indisponibilidade, reconstrução de índices ou perda de gravações que chegaram a outros sistemas. Se houver replicação, filas, exportações ou integrações, recuperar um banco de dados não reverte automaticamente esses efeitos.
Convém distinguir três ações. Restaurar recupera uma cópia ou um ponto no tempo; reverter tenta desfazer as alterações da migração; compensar aplica novas operações que corrigem seus efeitos. Elas não são equivalentes: uma compensação pode deixar um histórico diferente do original, embora restabeleça as regras de negócio.
A escolha depende do escopo da falha, das gravações posteriores e dos objetivos de recuperação. Antes de começar, determine qual perda de dados é tolerável, por quanto tempo a interrupção pode durar e quem autoriza uma recuperação. Se esses limites não estiverem definidos, a equipe não terá critérios operacionais para decidir.
Classificar cada transformação de acordo com sua possibilidade de recuperação
Descreva cada etapa da migração e classifique-a de acordo com o modo de recuperação previsto:
- Reversível: existe uma operação inversa confiável. Por exemplo, o valor original é preservado antes da normalização de um campo e pode ser restaurado sem sobrescrever alterações posteriores.
- Compensável: não é possível reconstruir exatamente o estado anterior, mas uma nova operação pode corrigir o efeito de acordo com uma regra de negócio. A compensação deve ser explícita, auditável e, quando possível, idempotente.
- Irreversível: informações são descartadas ou ocorre um efeito que não pode ser desfeito com garantias. Isso exige uma decisão expressa sobre a aceitação do risco, a preservação dos dados de origem e validações adicionais.
O rótulo não deve ser atribuído apenas com base no tipo de instrução SQL. Uma atualização em massa pode ser reversível se o valor anterior for salvo e a concorrência for controlada; pode não ser reversível se, durante a execução, outros processos modificarem as mesmas linhas. Considere também efeitos colaterais, como notificações, chamadas a APIs, cobranças ou mensagens em filas. Muitas vezes, é preferível separar essas ações da transformação dos dados.
Definir o estado inicial e as invariantes
Antes da execução, registre o escopo da migração: entidades incluídas, filtros, versão da aplicação e regras aplicadas. Defina uma linha de base com contagens relevantes e, quando for útil, agregados ou hashes de conjuntos estáveis. Registre o momento de referência e a origem desses dados. Um número sem escopo nem contexto não permite verificar uma recuperação.
As invariantes são condições que devem continuar verdadeiras durante e depois da migração. Podem incluir relações entre tabelas, unicidade, estados permitidos, valores que precisam ser preservados ou correspondência entre registros do banco de dados e sistemas conectados. Associe a cada uma uma consulta ou procedimento reproduzível e um limite de aceitação. Se os dados mudarem legitimamente durante a execução, defina como distinguir essa atividade dos efeitos da migração.
Em uma aplicação PHP, as transformações podem ser implementadas em comandos de console ou processos de trabalho, em vez de depender de uma requisição web extensa. Essa escolha não elimina os riscos de concorrência nem os limites transacionais: determine qual unidade pode ser executada atomicamente e o que fazer se o processo terminar entre duas operações.
Projetar lotes, pontos de controle e uma execução retomável
Divida o trabalho em lotes com limites explícitos, por exemplo, usando uma chave estável e ordenada. Evite paginar por deslocamento se as linhas puderem mudar ou desaparecer durante o processo; um marcador de continuação baseado em uma chave costuma ser mais previsível. O tamanho do lote deve equilibrar a duração das transações, a carga no banco de dados e a facilidade para detectar falhas.
Depois de cada lote, salve um ponto de controle com o identificador do trabalho, o intervalo processado, o estado, o horário e os resultados da validação. A atualização dos dados e o avanço do ponto de controle devem ser coordenados para evitar declarar como processado um lote que não foi confirmado. Se as duas operações não puderem fazer parte de uma transação, projete uma reconciliação que detecte o estado intermediário.
Uma migração retomável não reaplica alterações às cegas. Cada operação deve tolerar novas tentativas ou verificar se o efeito já existe. Em PHP, isso pode se apoiar em transações, restrições únicas e operações idempotentes, de acordo com o mecanismo e o modelo de dados. Teste também interrupções deliberadas: uma implantação, uma exceção ou a perda de conexão não devem deixar o trabalho sem uma forma conhecida de continuar.
Registrar as alterações para localizar efeitos e auditar decisões
Atribua um identificador único a cada execução e registre, no mínimo, a transformação, o escopo, os lotes, as linhas afetadas, os erros e as decisões de recuperação. Para alterações que possam ser compensadas, preserve os dados anteriores necessários ou uma referência segura a eles. Não registre informações sensíveis indiscriminadamente nos logs; limite o acesso, o período de retenção e o conteúdo ao que for necessário para recuperar e auditar.
O registro deve permitir responder a perguntas concretas: quais linhas tiveram o processamento tentado, quais foram confirmadas, quais falharam e qual operação posterior as modificou. Combine logs técnicos com um histórico de alterações de negócio quando necessário. Não confunda rastreabilidade com backup: o registro deve ter detalhes suficientes para sua finalidade e também precisa de proteção contra perda ou alteração.
Escolher entre retomar, compensar ou restaurar
Defina sinais e respostas com antecedência, em vez de decidir apenas por intuição quando ocorrer um erro:
- Retomar: se a falha for transitória, as invariantes forem mantidas e os lotes confirmados estiverem identificados. Faça novas tentativas de forma limitada e monitore os erros e a carga.
- Compensar: se as alterações aplicadas forem conhecidas e houver uma operação corretiva testada. Primeiro, interrompa novas gravações incompatíveis e confirme que a compensação não sobrescreverá alterações válidas.
- Restaurar: se a corrupção for ampla, a recuperação a partir do backup estiver validada e o impacto de perder ou reconstruir alterações posteriores for aceitável. Coordene a recuperação com réplicas e integrações.
- Parar e escalar: se não for possível determinar o estado, se as contagens divergirem sem explicação ou se a compensação puder causar mais danos. Preserve as evidências antes de intervir.
Estabeleça limites para pausar o trabalho, como uma taxa de erros acima do permitido, uma invariante violada ou um desvio nas contagens. Defina quem pode autorizar a retomada e quem decide por uma restauração. Em alguns casos, a opção mais segura é isolar o fluxo afetado e manter o sistema em um estado controlado enquanto a investigação é realizada.
Validar e encerrar a migração com uma lista de verificação
A conclusão do processo não comprova que os dados estejam corretos. Compare as contagens antes e depois com o escopo esperado, execute as regras de negócio e revise as relações e os valores extremos. Use amostragens para inspecionar casos específicos, mas não como substituto de verificações completas quando estas forem possíveis. Se houver consumidores externos, verifique também seus estados e defina como reconciliar divergências.
Antes da execução: classifique as transformações, confirme o backup e a recuperação, teste lotes e novas tentativas com dados representativos, defina invariantes, limites para interrupção, responsáveis e janela operacional. Garanta que a equipe possa consultar o registro de alterações e que os procedimentos de compensação ou restauração tenham sido testados.
Depois da execução: valide as contagens e as regras, revise os erros e os efeitos externos, preserve o registro da execução e documente qualquer exceção. Mantenha as informações de recuperação disponíveis durante o período acordado e remova-as com segurança quando deixarem de ser necessárias. A migração só está encerrada quando os resultados podem ser verificados e há uma decisão explícita sobre as divergências pendentes.
