Migrações sem drama começam antes da primeira linha. Ao planejar o rollback, a equipe define como desfazer a mudança, quais dados precisam de proteção e como validar o caminho de volta antes de alterar o banco.
Migrações sem drama começam pelo caminho de volta
Rollback não é uma instrução genérica para usar quando algo falhar. É um procedimento com pré-condições, ordem de execução e um critério claro para saber se a reversão terminou.
Antes de escrever a migration, registre:
- qual estado do banco existe hoje;
- qual mudança será aplicada;
- qual versão da aplicação continua funcionando durante a transição;
- como desfazer cada alteração e quais dados podem ser perdidos;
- como verificar o estado esperado depois da migração e depois do rollback.
O Migration Style Guide do GitLab orienta que migrações sejam reversíveis, testadas e documentadas. Quando a operação é transacional, uma falha em uma etapa pode deixar o banco sem as alterações daquela operação.
O rollback precisa de um plano executável
Uma descrição como voltar à versão anterior não basta. O plano precisa dizer qual versão será restaurada, quais comandos serão executados e que estado dos dados deve existir no fim.
Em uma simulação, suponha que uma migration remova a coluna legacy_code depois que o código deixa de consultá-la. A simulação parte destas premissas: não existe outra cópia desses valores e o rollback precisa recuperar a versão anterior do sistema.
- confirme antes da remoção quais dados precisam de cópia e como essa cópia será restaurada;
- execute a migration em um ambiente de teste e verifique o estado esperado;
- execute o rollback e confirme se a coluna e os dados necessários voltaram;
- registre o que fazer se a restauração não puder recuperar os valores.
Mesmo que um script de undo recrie a coluna, ele não recupera automaticamente os valores que foram apagados. Se esses valores forem necessários, o caminho de volta depende de uma cópia testada.
Teste a migração e o rollback no mesmo fluxo
A revisão não deve parar quando a migração termina sem erro. O caminho de volta também precisa ser executado, verificado e documentado.
As Database Review Guidelines do GitLab recomendam revisar a execução e o rollback de cada migração, com procedimento de retorno e validação automatizada no CI.
- aplique a migration em uma base com dados representativos;
- confira a estrutura do banco e o comportamento esperado pela aplicação;
- execute o rollback;
- compare o estado final com o estado anterior documentado.
Se uma etapa falhar dentro de uma migração transacional, o teste deve confirmar que o banco não ficou parcialmente alterado. Isso não elimina a necessidade de testar o fluxo completo, sobretudo quando há mudanças de aplicação ou dados fora da transação.
Defina os limites antes de liberar a mudança
Nem todo rollback cabe em um script de undo. A documentação do Redgate Flyway destaca que o pipeline pode preparar o rollback com antecedência, mas um undo não substitui uma estratégia testada de backup e restauração e não recupera dados de tabelas ou colunas removidas.
Documente antes da execução:
- o sinal que interrompe a migração;
- quem decide o rollback;
- quais dados precisam ser preservados antes da mudança;
- quais verificações liberam a retomada.
Se uma migration é reversível apenas na estrutura do banco, escreva isso com clareza. O time precisa saber quando o retorno depende de backup e restauração e quando a reversão pode acontecer no próprio banco.
Se uma migração está no backlog, converse com a LYPES sobre o gargalo atual do produto. O próximo passo é mapear a mudança, o caminho de volta e o modelo de execução mais adequado antes de abrir o pull request.