HOWTO · Django

Redefinir migrações no Django

Aprenda como redefinir migrações no Django

Nesta página

As migrações do Django são instruções versionadas para alterar o esquema de um banco de dados. O Django também registra no banco quais migrações foram aplicadas. Portanto, “redefinir migrações” pode significar várias coisas: voltar um aplicativo a uma migração conhecida, desfazer as migrações desse aplicativo, apagar linhas mantendo o esquema ou substituir um banco de desenvolvimento. Escolha a operação conforme o resultado desejado; apagar arquivos de migração não substitui nenhuma delas.

Antes de uma operação destrutiva, confirme qual arquivo de configurações e qual banco de dados serão usados pelo comando, confira o estado atual das migrações com python manage.py showmigrations e faça um backup que possa ser restaurado se os dados forem importantes. Os comandos abaixo usam AppName como marcador para o rótulo do aplicativo, por exemplo, blog; use o rótulo reconhecido pelo Django, que pode ser diferente do caminho completo do pacote Python.

O que muda ao redefinir migrações

Um arquivo de migração descreve operações no esquema e também pode mover ou transformar dados. A tabela de migrações registra os nomes das migrações aplicadas. Reverter um aplicativo altera o estado registrado do esquema executando operações inversas, quando disponíveis; isso não reescreve os arquivos de migração. Limpar linhas com flush mantém o esquema e o histórico de migrações. Substituir um banco de desenvolvimento remove seus dados e registros de migração; depois, é preciso aplicar as migrações novamente.

Essas operações têm escopos diferentes. Se você precisa desfazer uma alteração recente no esquema, indique uma migração anterior como destino. Se o aplicativo não deve ter nenhuma migração aplicada, use zero. Se você quer apenas deixar vazios os dados da aplicação, use flush. Se o banco local é descartável e você quer reconstruí-lo do zero, substitua esse banco e execute as migrações do projeto novamente. Não apague arquivos de migração para fazer o banco parecer redefinido: os ambientes existentes e seus colegas de equipe ainda dependem dos arquivos que definem o histórico de migrações compartilhado.

Reverter um aplicativo para uma migração anterior

Encontre a migração de destino com showmigrations AppName ou consulte os arquivos de migração desse aplicativo. Em seguida, use python manage.py migrate AppName 0004 para levar o aplicativo até a migração 0004; substitua os dois marcadores pelo rótulo real do aplicativo e pela migração de destino. Quando esse for o nome exibido para a migração, você também pode usar um nome como initial em vez de um número.

O destino corresponde ao estado após essa migração, portanto as migrações posteriores desse aplicativo são revertidas. As operações inversas podem alterar ou remover colunas e apagar os dados armazenados nelas. O Django também pode precisar ajustar migrações dependentes para manter o grafo de migrações consistente. Antes de executar o comando, confira as alterações planejadas e qual banco de dados está selecionado pelas configurações ativas, principalmente quando outros aplicativos dependem do aplicativo de destino.

Um pequeno trecho de Python pode deixar explícito o modelo do comando antes de você adaptá-lo ao projeto. Substitua o aplicativo e o destino de exemplo pelos valores da sua própria lista de migrações.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

app_label = "blog"
target_migration = "0004"
print(f"python manage.py migrate {app_label} {target_migration}")
python manage.py migrate blog 0004

O exemplo imprime um modelo de comando; ele não se conecta ao Django nem altera um banco de dados.

Redefinir um aplicativo para zero

Para desfazer todas as migrações de um aplicativo, use python manage.py migrate AppName zero. Isso afeta o estado das migrações desse aplicativo e reverte as operações feitas no esquema; não é uma redefinição de todo o banco. Dependendo das migrações e dos relacionamentos envolvidos, a reversão pode remover tabelas ou dados e talvez também exija desfazer migrações dependentes. Quando não tiver certeza do resultado, examine os efeitos previstos primeiro em um ambiente descartável.

Não apague em seguida os arquivos de migração do aplicativo em um projeto compartilhado ou implantado. O Django usa esses arquivos como histórico para construir o esquema em outros bancos de dados. Se a equipe decidir intencionalmente consolidar ou substituir o histórico de migrações, coordene um procedimento separado de manutenção de migrações para todos os ambientes; não trate zero como autorização para apagar esse histórico.

Redefinir um banco de desenvolvimento

Para deixar o banco vazio e manter suas tabelas e migrações aplicadas, execute python manage.py flush. O comando apaga os dados do banco e redefine as sequências, mas mantém o esquema e os registros de migração. Em geral, é a opção adequada quando você quer carregar fixtures novamente ou começar com os dados da aplicação vazios; ela não reconstrói o esquema a partir dos arquivos de migração.

Para reconstruir completamente um banco local, pare os processos que o utilizam, confirme que as configurações ativas apontam para um banco de desenvolvimento descartável e substitua esse banco seguindo o procedimento adequado para o mecanismo usado. Com SQLite, isso pode significar remover o arquivo local do banco de dados; com um banco servidor, normalmente significa descartar e recriar um banco de desenvolvimento usando as credenciais apropriadas. Depois, execute python manage.py migrate para criar o esquema e aplicar as migrações do projeto. Os comandos para excluir bancos variam conforme o mecanismo; siga o procedimento documentado para o banco em questão e nunca use em produção um comando de redefinição destinado ao desenvolvimento sem um plano explícito de recuperação.

Remover arquivos de migração e criar novos a partir dos modelos atuais é uma reescrita de histórico separada, que precisa ser coordenada. Isso pode quebrar instalações implantadas, cópias de trabalho dos colegas e dependências entre migrações, mesmo que um banco local tenha sido reconstruído com sucesso. Mantenha os arquivos de migração sob controle de versão e use novas migrações para alterações comuns nos modelos.

Lidar com segurança com migrações irreversíveis

Algumas migrações não podem ser revertidas porque suas operações descartam informações ou não têm uma operação inversa definida. O Django pode interromper uma reversão com IrreversibleError. O estado do banco após a falha depende da atomicidade da migração e do comportamento transacional do banco; a reversão pode ter efeitos parciais. Não presuma que um comando de reversão restaurará dados apagados ou transformados.

Antes de tentar uma reversão, revise as operações da migração e faça backup dos dados que precisam ser preservados. Teste a reversão em uma cópia recente do banco, confira o esquema resultante e os registros importantes e confirme novamente o ambiente de destino imediatamente antes de aplicá-la. Se a migração for irreversível, restaure um backup adequado ou escreva uma migração deliberada para avançar até o estado desejado; não apague registros de migração manualmente para ocultar a divergência.