Uma migração interrompida nem sempre está simplesmente «pela metade». Ela pode ter parado antes de salvar uma unidade, depois de confirmar algumas alterações ou quando o destino respondeu de forma ambígua. Também pode ter concluído a execução e, ainda assim, deixado discrepâncias. Para decidir como prosseguir, a equipe deve reconstruir o que aconteceu com evidências verificáveis, sem confiar apenas no código de saída ou no último identificador registrado.
A questão prática não é apenas como retomar uma migração de dados com falha em PHP, mas o que é possível afirmar sobre o estado de cada unidade e quais verificações são necessárias antes de repetir uma operação. Essa distinção reduz o risco de duplicatas, relações quebradas e correções manuais difíceis de auditar.
Primeiro, diferencie uma execução interrompida de uma migração com discrepâncias
Uma execução interrompida é aquela cujo processo deixou de avançar, por exemplo, devido a uma exceção, perda de conexão ou intervenção operacional. Já uma migração com discrepâncias é aquela cujo resultado não atende às condições esperadas, embora o processo tenha sido concluído sem erros. Pode haver linhas ignoradas, chaves transformadas incorretamente ou relações incompletas.
Por isso, um estado global como concluída ou com falha é insuficiente. Convém diferenciar pelo menos entre execução em andamento, interrompida, concluída e concluída com discrepâncias. O estado global resume o trabalho, mas não substitui o registro por unidade nem a validação do resultado.
Antes de executar o comando novamente, preserve os registros disponíveis e determine qual sistema é a fonte da verdade nesta etapa. Se houver gravações posteriores à migração, alterações manuais ou processos concorrentes, identifique como eles afetam a comparação. Prosseguir sem essas informações pode transformar uma discrepância investigável em perda de rastreabilidade.
Defina unidades de trabalho e pontos de controle verificáveis
Escolha uma unidade de trabalho que faça sentido para os dados e para a recuperação: pode ser uma entidade, um grupo de registros relacionados ou uma partição estável. Evite que o ponto de controle seja simplesmente «o último ID processado». Esse ID demonstra, no máximo, que o programa chegou a determinada posição; não prova que todos os registros anteriores foram salvos corretamente nem que o destino está consistente.
Para cada unidade, mantenha uma chave de origem estável, a versão ou o identificador da execução, o estado e um resultado verificável. O ponto de controle deve poder ser comparado com o destino, por exemplo, por meio de uma chave de destino, de uma hash calculada sobre campos relevantes ou de uma consulta de verificação. Se os dados puderem mudar durante o processo, registre também o critério de seleção ou o instante de corte aplicado.
O projeto depende do ambiente. Se a origem e o destino compartilham uma transação, ela pode fornecer evidências de confirmação conjunta; se forem sistemas distintos, não presuma atomicidade entre eles. Em uma integração por API, uma resposta perdida pode deixar incerto se o servidor aplicou a operação. A estratégia deve refletir essa incerteza e oferecer uma verificação posterior, em vez de marcar automaticamente a unidade como com falha ou confirmada.
Registre por unidade o que foi tentado e o que foi confirmado
Um registro útil para o suporte permite responder quem executou a migração, qual unidade foi processada, quando seu estado mudou e com quais evidências. Diferencie processado — o código executou etapas — de confirmado — há um sinal confiável de que o resultado esperado existe no destino. Adicione o número da tentativa, uma categoria de erro e um identificador de correlação para vincular eventos do processo a chamadas externas.
Os estados devem descrever situações operacionais, não apenas etapas do algoritmo. Por exemplo: pendente, em andamento, confirmação incerta, confirmado e requer revisão. Se o processo for encerrado enquanto uma unidade estiver marcada como em andamento, ao reiniciar ela deverá ser tratada como incerta até que o destino seja verificado. Não a marque como com falha sem verificar se chegou a produzir efeitos.
Registre informações suficientes para investigar, mas não inclua credenciais, segredos nem dados pessoais desnecessários nos logs. Os erros devem permitir identificar a unidade e a operação, sem que a rastreabilidade amplie a exposição de dados. Defina também quem pode consultar e manter esses registros.
Compare invariantes antes de decidir como prosseguir
Invariantes são condições que devem ser satisfeitas independentemente de como a migração foi implementada. As contagens por tipo ou partição ajudam a localizar diferenças, mas não são suficientes: dois conjuntos podem ter o mesmo tamanho e conter registros distintos. Compare chaves de negócio, presença de registros, relações e regras relevantes, como estados permitidos ou valores recalculados.
Escolha verificações proporcionais ao impacto e ao volume. Uma amostra pode servir como diagnóstico, mas, por si só, não demonstra que o conjunto completo está correto. Para uma validação exaustiva, compare chaves ou hashes em blocos e registre quais foram verificados. Se a transformação alterar campos de forma intencional, documente quais diferenças são esperadas e quais indicam um erro.
Se a origem continuar recebendo alterações, separe as discrepâncias causadas pela concorrência daquelas causadas pela migração. Pode ser necessário definir uma janela de corte, capturar alterações posteriores ou repetir uma fase de sincronização. Sem uma regra clara para alterações concorrentes, a comparação entre sistemas pode gerar falsos positivos ou deixar de detectar novos dados.
Retome somente com evidências e trate os resultados incertos
Uma retomada segura carrega as unidades pendentes e confirmadas, mas não considera válidas aquelas cujo estado ficou incerto. Para estas últimas, consulte o destino com uma chave estável e compare o resultado com a transformação esperada. Se houver correspondência, registre a confirmação sem repetir o efeito; se o resultado não existir, pode ser adequado tentar novamente. Se existir com conteúdo diferente, interrompa o processamento dessa unidade para investigar.
Quando repetir uma operação puder criar duplicatas ou efeitos externos — como enviar uma notificação —, use uma operação idempotente ou uma chave de idempotência, se o sistema envolvido oferecer suporte. Se isso não for possível, crie uma verificação prévia e um fluxo de reconciliação. Não presuma que uma exceção significa que nada foi gravado: a falha pode ter ocorrido depois da confirmação da alteração e antes do recebimento da resposta.
Antes de retomar, valide se estão sendo usados o mesmo mapeamento, a mesma política de chaves e a versão correta do código ou da configuração. Um ponto de controle gerado por uma transformação diferente pode ser enganoso. Em PHP, o comando de migração deve aceitar uma execução identificável e emitir estados estruturados; assim, alguém pode comparar o registro com os dados, em vez de depender de mensagens genéricas no console.
Estabeleça condições de parada e encerre com um relatório
Interrompa a retomada quando houver conflitos de chaves, dados inválidos que exijam uma regra de negócio, relações órfãs, resultados incertos que não possam ser verificados ou diferenças acima dos limites aceitos. Interrompa também se as evidências disponíveis não permitirem saber o que aconteceu. Nesses casos, escalar o problema e preservar o estado costuma ser mais seguro do que tentar novamente às cegas.
Ao terminar, execute as verificações globais: unidades confirmadas em relação às unidades esperadas, contagens e chaves, relações e regras de negócio definidas para a migração. Gere um relatório que indique o que foi migrado, o que foi verificado, o que foi tentado novamente e quais discrepâncias continuam pendentes, com referências que permitam investigá-las. Não declare o trabalho concluído apenas porque o processo terminou com código zero.
O critério para retomar é simples de expressar, embora exija disciplina técnica: cada unidade deve ficar confirmada, verificada como não aplicada ou separada para revisão. Esse estado explícito, junto com invariantes comparáveis e registros úteis, permite prosseguir com uma migração PHP sem confundir progresso com sucesso nem incerteza com autorização para repetir.
