Detta dokument förklarar hur man strukturerar och skriver databasmigreringar för olika scenarier som du kan stöta på. För inledande material om migreringar, se the topic guide.
\nNär du använder flera databaser kan du behöva ta reda på om du ska köra en migrering mot en viss databas eller inte. Du kanske till exempel vill köra en migrering endast på en viss databas.
\nFör att göra det kan du kontrollera databasanslutningens alias i en RunPython-operation genom att titta på attributet 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 ]\nDu kan också ange tips som kommer att skickas till allow_migrate()-metoden för databasroutrar som **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\nGör sedan följande för att utnyttja detta i dina migreringar:
\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 ]\nOm din RunPython eller RunSQL operation bara påverkar en modell är det god praxis att skicka model_name som en ledtråd för att göra det så transparent som möjligt för routern. Detta är särskilt viktigt för återanvändbara appar och tredjepartsappar.
Om du använder en ”vanlig” migrering som lägger till ett unikt icke-nullbart fält i en tabell med befintliga rader kommer det att uppstå ett fel eftersom det värde som används för att fylla i befintliga rader genereras endast en gång, vilket bryter den unika begränsningen.
\nDärför bör följande steg vidtas. I det här exemplet lägger vi till ett icke-nullbart UUIDField med ett standardvärde. Modifiera respektive fält efter dina behov.
Lägg till fältet i din modell med argumenten default=uuid.uuid4 och unique=True (välj en lämplig standard för den typ av fält du lägger till).
Kör kommandot makemigrations. Detta bör generera en migrering med en AddField operation.
Generera två tomma migreringsfiler för samma app genom att köra makemigrations myapp --empty två gånger. Vi har döpt om migreringsfilerna så att de får meningsfulla namn i exemplen nedan.
Kopiera åtgärden AddField från den autogenererade migreringen (den första av de tre nya filerna) till den sista migreringen, ändra AddField till AlterField och lägg till import av uuid och models. Ett exempel:
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 ]\nRedigera den första migreringsfilen. Den genererade migreringsklassen bör se ut ungefär så här:
\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 ]\nÄndra unique=True till null=True - detta kommer att skapa det mellanliggande null-fältet och skjuta upp skapandet av den unika begränsningen tills vi har fyllt i unika värden på alla rader.
I den första tomma migreringsfilen lägger du till en RunPython eller RunSQL operation för att generera ett unikt värde (UUID i exemplet) för varje befintlig rad. Lägg också till en import av uuid. För att ta ett exempel:
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 ]\nNu kan du tillämpa migreringarna som vanligt med kommandot migrate.
Observera att det finns ett tävlingsförhållande om du tillåter att objekt skapas medan denna migrering körs. Objekt som skapas efter AddField och före RunPython kommer att få sina ursprungliga uuid överskrivna.
På databaser som stöder DDL-transaktioner (SQLite och PostgreSQL) kommer migreringar att köras i en transaktion som standard. För användningsfall som att utföra datamigreringar på stora tabeller kanske du vill förhindra att en migrering körs i en transaktion genom att ställa in attributet atomic till False:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n atomic = False\nInom en sådan migrering körs alla operationer utan en transaktion. Det är möjligt att köra delar av migreringen inuti en transaktion med atomic() eller genom att skicka atomic=True till RunPython.
Här är ett exempel på en icke-atomisk datamigrering som uppdaterar en stor tabell i mindre satser:
\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 ]\nAttributet atomic har ingen effekt på databaser som inte stöder DDL-transaktioner (t.ex. MySQL, Oracle). (MySQL:s atomic DDL statement support hänvisar till enskilda uttalanden snarare än flera uttalanden som är insvepta i en transaktion som kan rullas tillbaka)
Django bestämmer i vilken ordning migreringar ska tillämpas, inte genom filnamnet för varje migrering, utan genom att bygga en graf med hjälp av två egenskaper för klassen Migration: dependencies och run_before.
Om du har använt kommandot makemigrations har du förmodligen redan sett dependencies i aktion eftersom automatiskt skapade migreringar har detta definierat som en del av deras skapandeprocess.
Egenskapen dependencies deklareras på följande sätt:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ]\nVanligtvis räcker det, men ibland kan du behöva se till att din migrering körs före andra migreringar. Detta är till exempel användbart för att få migreringar av tredjepartsappar att köras efter din AUTH_USER_MODEL-ersättning.
För att uppnå detta, placera alla migreringar som bör bero på din i run_before-attributet på din Migration-klass:
class Migration(migrations.Migration):\n ...\n\n run_before = [\n ("third_party_app", "0001_do_awesome"),\n ]\nAnvänd hellre dependencies än run_before när det är möjligt. Du bör endast använda run_before om det inte är önskvärt eller opraktiskt att ange dependencies i den migrering som du vill köra efter den du skriver.
Du kan använda en datamigrering för att flytta data från en tredjepartsapplikation till en annan.
\nOm du planerar att ta bort den gamla appen senare måste du ställa in egenskapen dependencies baserat på om den gamla appen är installerad eller inte. Annars kommer du att sakna beroenden när du avinstallerar den gamla appen. På samma sätt måste du fånga LookupError i anropet apps.get_model() som hämtar modeller från den gamla appen. Med det här tillvägagångssättet kan du distribuera ditt projekt var som helst utan att först installera och sedan avinstallera den gamla appen.
Här är ett exempel på en migrering:
\nmyapp/migrations/0124_move_old_app_to_new_app.pyfrom 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"))\nFundera också på vad du vill ska hända när migreringen inte tillämpas. Du kan antingen inte göra någonting (som i exemplet ovan) eller ta bort vissa eller alla data från den nya applikationen. Justera det andra argumentet i RunPython-operationen i enlighet med detta.
ManyToManyField så att den använder en through-modellLink to this heading#Om du ändrar en ManyToManyField för att använda en through-modell, kommer standardmigreringen att radera den befintliga tabellen och skapa en ny, vilket innebär att befintliga relationer går förlorade. För att undvika detta kan du använda SeparateDatabaseAndState för att byta namn på den befintliga tabellen till det nya tabellnamnet samtidigt som du meddelar migreringsautodetektorn att den nya modellen har skapats. Du kan kontrollera det befintliga tabellnamnet och begränsningsnamnet genom sqlmigrate eller dbshell. Du kan kontrollera det nya tabellnamnet med genom-modellens _meta.db_table-egenskap. Din nya through-modell bör använda samma namn för ForeignKeys som Django gjorde. Om den behöver några extra fält bör dessa läggas till i operationer efter SeparateDatabaseAndState.
Om vi till exempel hade en Book-modell med ett ManyToManyField som länkar till Author, skulle vi kunna lägga till en genomgående modell AuthorBook med ett nytt fält is_primary, så här:
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 ]\nOm du vill ändra en ohanterad modell (managed=False) till hanterad måste du ta bort managed=False och generera en migrering innan du gör andra schemarelaterade ändringar i modellen, eftersom schemaändringar som visas i den migrering som innehåller åtgärden för att ändra Meta.managed kanske inte tillämpas.