Este documento explica como estruturar e a escrever migrações de banco de dados para diferentes cenários que você talvez encontre. Para um material introdutório sobre migrações, veja o tópico guia.
\nQuando usar múltiplos bancos de dados, você talvez necessite entender onde rodar e onde não rodar migrações para um banco de dados em partiular. Por exemplo, você talvez queira somente rodar migrações em um banco de dados particular.
\nPara fazer isso você pode verificar o alias da conexão com o banco de dados dentro de uma operação RunPython olhando no attributo schema_editor.connection.alias:
from django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n if schema_editor.connection.alias != "default":\n return\n # Your migration code goes here\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n # Dependencies to other migrations\n ]\n\n operations = [\n migrations.RunPython(forwards),\n ]\nYou can also provide hints that will be passed to the allow_migrate()\nmethod of database routers as **hints:
myapp/dbrouters.pyclass MyRouter:\n def allow_migrate(self, db, app_label, model_name=None, **hints):\n if "target_db" in hints:\n return db == hints["target_db"]\n return True\nEntão para aproveitar isso em suas migrações, faça o seguinte:
\nfrom django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n # Your migration code goes here\n ...\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n # Dependencies to other migrations\n ]\n\n operations = [\n migrations.RunPython(forwards, hints={"target_db": "default"}),\n ]\nSe você executar RunPython ou RunSQL as operações só irão afetar um modelo, e é uma boa prática passar model_name como uma dica para que fique tão transparente quanto possível para o roteador. Isso é especialmente importante para reutilização e aplicações de terceiros.
Aplicar uma migração “sem customizações” que adicione um campo não nulo e “unique” a uma table com registros existentes irá emitir um erro porque o valor usado para popular os registros existente é gerado somente uma vez, então quebrando a regra de “unique”.
\nPortanto, os seguintes passos devem ser seguidos. Neste exemplo, nós iremos adicionar um UUIDField não-nulo com um valor padrão. Modifique o campo respectivo de acordo com suas necessidades.
Adicione o campo no seu modelo com default=uuid.uuid4 e argumentos unique=True (escolha um padrão apropriado para o tipo de campor que você está adicionando).
Execute o comando makemigrations . Isso deve gerar uma migração com uma operação AddField.
Gera dois arquivos de migrações vazios para a mesma aplicação rodando makemigrations myapp --empty duas vezes. Renomeamos os arquivos de migração para dara eles nomes significativos nos exemplos abaixo
Copie a operação AddField da migração gerada automatcamente (a primeira dos três arquivos novos) para a última migração, troque AddField para AlterField, e adicione as importações de uuid e models`. Por exemplo:
0006_remove_uuid_null.py# Generated by Django A.B on YYYY-MM-DD HH:MM\nfrom django.db import migrations, models\nimport uuid\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0005_populate_uuid_values"),\n ]\n\n operations = [\n migrations.AlterField(\n model_name="mymodel",\n name="uuid",\n field=models.UUIDField(default=uuid.uuid4, unique=True),\n ),\n ]\nEdite o primeiro arquivo da migração. A classe de migração gerada deve se parecer com isso:
\n0004_add_uuid_field.pyclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0003_auto_20150129_1705"),\n ]\n\n operations = [\n migrations.AddField(\n model_name="mymodel",\n name="uuid",\n field=models.UUIDField(default=uuid.uuid4, unique=True),\n ),\n ]\nMude unique=True para null=True – isso irá criar o campo nullo imtermediário e adiar a criação da restrição “unique” até que tenhamos populado os valores únicos em todas os registros.
No primeiro arquivo de migração vazio, adicione a operação RunPython ou a RunSQL para gerar um valor único (UUID por exemplo) para cada linha existente. Também adicione uma importação de uuid. Por exemplo:
0005_populate_uuid_values.py# Generated by Django A.B on YYYY-MM-DD HH:MM\nfrom django.db import migrations\nimport uuid\n\n\ndef gen_uuid(apps, schema_editor):\n MyModel = apps.get_model("myapp", "MyModel")\n for row in MyModel.objects.all():\n row.uuid = uuid.uuid4()\n row.save(update_fields=["uuid"])\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0004_add_uuid_field"),\n ]\n\n operations = [\n # omit reverse_code=... if you don't want the migration to be reversible.\n migrations.RunPython(gen_uuid, reverse_code=migrations.RunPython.noop),\n ]\nAgora você pode aplicar as migrações como de costume com o comando migrate.
Note que há uma condição de concorrência se você deixar com que objetos sejam criados enquanto essa migração está rodando. Objetos criados depois do AddField``e antes do ``RunPython terão seus uuid’s sobrescritos.
Em banco de dados que suportam transações DDL (SQLite e PostgreSQL), as migrações são executadas por padrão dentro de uma transação. Em casos como migrações de dados em grandes tabelas, você talvez queira evitar que uma migração rode em uma transação definindo o atributo atomic como False:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n atomic = False\nWithin such a migration, all operations are run without a transaction. It’s\npossible to execute parts of the migration inside a transaction using\natomic() or by passing atomic=True to\nRunPython.
Aqui um exemplo de uma migração de dados não atômica que atualiza uma grande tabela em pequenas partes.
\nimport uuid\n\nfrom django.db import migrations, transaction\n\n\ndef gen_uuid(apps, schema_editor):\n MyModel = apps.get_model("myapp", "MyModel")\n while MyModel.objects.filter(uuid__isnull=True).exists():\n with transaction.atomic():\n for row in MyModel.objects.filter(uuid__isnull=True)[:1000]:\n row.uuid = uuid.uuid4()\n row.save()\n\n\nclass Migration(migrations.Migration):\n atomic = False\n\n operations = [\n migrations.RunPython(gen_uuid),\n ]\nO atributo atomic não tem nenhum efeito em bancos de dados que não suportam transações DDL (ex. MySQL, Oracle). (O suporte para transações DDL atômicas do MySQL refere-se a instruções individuais, em vez de várias instruções envolvidas em uma transação que pode ser revertida.)
O django determina a ordem em que as migrações devem ser aplicadas não pelo nome do arquivo de cada migração, mas através da construção de um gráfico usando duas propriedade na classe Migration: dependencies e run_before.
Se você estiver usando o comando makemigration você provavelmente já viu dependencies em ação por conta das migrações auto-criadas possuirem esta definição como parte do processo de criação.
A propridade dependencies está declarada como isto:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ]\nNormalmente isso será o bastante, mas de tempos em tempos você poderá precisar se assegurar de que sua migração execute antes de outras migrações. Isso é útil, por exemplo, para fazer migrações de aplicações de terceiros executem depois de substituir seu AUTH_USER_MODEL.
Para conseguir isso, coloque todas as migrações que devem depender das suas no atributo run_before na sua classe Migration:
class Migration(migrations.Migration):\n ...\n\n run_before = [\n ("third_party_app", "0001_do_awesome"),\n ]\nPrefira usar dependencies ao run_before quando possível. Você deve somente usar o run_before se não é desejável ou impraticável especificar dependencies na migração qual você quer rodar depois da que está escrevendo.
Pode-se usar migração de dados para mover dados de um aplicativo de terceiros até outro aplicativo.
\nSe você planeja remover o aplicativo antigo depois, você vai precisar definir propriedades de dependencies baseadas em se o aplicativo está ou não instalado. Caso contrário, você terá dependências faltando uma vez que o aplicativo antigo seja desinstalado. De forma similar, você precisa prestar atenção no LookupError na função apps.get_model() que retorna modelos do aplicativo antigo. Esta abordagem lhe permite implementar o seu projeto em qualquer lugar sem precisar instalar primeiro e depois desinstalar o aplicativo antigo.
Este é um exemplo de migração:
\nfrom django.apps import apps as global_apps\nfrom django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n try:\n OldModel = apps.get_model("old_app", "OldModel")\n except LookupError:\n # The old app isn't installed.\n return\n\n NewModel = apps.get_model("new_app", "NewModel")\n NewModel.objects.bulk_create(\n NewModel(new_attribute=old_object.old_attribute)\n for old_object in OldModel.objects.all()\n )\n\n\nclass Migration(migrations.Migration):\n operations = [\n migrations.RunPython(forwards, migrations.RunPython.noop),\n ]\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ("new_app", "0001_initial"),\n ]\n\n if global_apps.is_installed("old_app"):\n dependencies.append(("old_app", "0001_initial"))\nConsidere também o que você quer que aconteça quando uma migração não for aplicada. Você pode não fazer nada (como no exemplo acima) ou remover alguns ou todos os dados da nova aplicação. Ajuste o segundo argumento da operação RunPython de acordo.
ManyToManyField to use a through modelLink para este cabeçalho#If you change a ManyToManyField to use a through\nmodel, the default migration will delete the existing table and create a new\none, losing the existing relations. To avoid this, you can use\nSeparateDatabaseAndState to rename the existing table to the new\ntable name while telling the migration autodetector that the new model has\nbeen created. You can check the existing table name and constraint name through\nsqlmigrate or dbshell. You can check the new table name\nwith the through model’s _meta.db_table property. Your new through\nmodel should use the same names for the ForeignKeys as Django did. Also if\nit needs any extra fields, they should be added in operations after\nSeparateDatabaseAndState.
For example, if we had a Book model with a ManyToManyField linking to\nAuthor, we could add a through model AuthorBook with a new field\nis_primary, like so:
from django.db import migrations, models\nimport django.db.models.deletion\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("core", "0001_initial"),\n ]\n\n operations = [\n migrations.SeparateDatabaseAndState(\n database_operations=[\n # Old table name from checking with sqlmigrate, new table\n # name from AuthorBook._meta.db_table.\n migrations.RunSQL(\n sql="ALTER TABLE core_book_authors RENAME TO core_authorbook",\n reverse_sql="ALTER TABLE core_authorbook RENAME TO core_book_authors",\n ),\n ],\n state_operations=[\n migrations.CreateModel(\n name="AuthorBook",\n fields=[\n (\n "id",\n models.AutoField(\n auto_created=True,\n primary_key=True,\n serialize=False,\n verbose_name="ID",\n ),\n ),\n (\n "author",\n models.ForeignKey(\n on_delete=django.db.models.deletion.DO_NOTHING,\n to="core.Author",\n ),\n ),\n (\n "book",\n models.ForeignKey(\n on_delete=django.db.models.deletion.DO_NOTHING,\n to="core.Book",\n ),\n ),\n ],\n options={\n "constraints": [\n models.UniqueConstraint(\n fields=["author", "book"],\n name="unique_author_book",\n )\n ],\n },\n ),\n migrations.AlterField(\n model_name="book",\n name="authors",\n field=models.ManyToManyField(\n to="core.Author",\n through="core.AuthorBook",\n ),\n ),\n ],\n ),\n migrations.AddField(\n model_name="authorbook",\n name="is_primary",\n field=models.BooleanField(default=False),\n ),\n ]\nSe quiser alterar um modelo não gerenciado (managed=False) para gerenciado, você deve remover managed=False e gerar uma migração antes de fazer outras mudanças no modelo relacionadas ao esquema, uma vez que alterações que aparecem na migração que contém a operação para alterar o Meta.managed podem não ser aplicadas.