Migreringsfiler består av en eller flera ”Operation”-objekt, objekt som deklarativt registrerar vad migreringen ska göra med din databas.
\nDjango använder också dessa Operation-objekt för att räkna ut hur dina modeller såg ut historiskt och för att beräkna vilka ändringar du har gjort i dina modeller sedan den senaste migreringen så att den automatiskt kan skriva dina migreringar; det är därför de är deklarativa, eftersom det betyder att Django enkelt kan ladda dem alla i minnet och köra igenom dem utan att röra databasen för att räkna ut hur ditt projekt ska se ut.
Det finns också mer specialiserade Operation-objekt som är till för saker som datamigreringar och för avancerad manuell databasmanipulation. Du kan också skriva dina egna Operation-klasser om du vill kapsla in en anpassad förändring som du ofta gör.
Om du behöver en tom migreringsfil för att skriva in dina egna Operation-objekt i, använd python manage.py makemigrations --empty yourappname, men tänk på att manuellt tillägg av schemaändrande operationer kan förvirra migreringsautodetektorn och göra att resulterande körningar av makemigrations ger felaktig kod.
Alla Django-kärnoperationer är tillgängliga från modulen django.db.migrations.operations.
För introduktionsmaterial, se migrations topic guide.
\nSkapaModellLink to this heading#Skapar en ny modell i projekthistoriken och en motsvarande tabell i databasen för att matcha den.
\nname är modellnamnet, som det skulle skrivas i filen models.py.
fields är en lista med 2-tuples av (field_name, field_instance). Fältinstansen ska vara ett obundet fält (så bara models.CharField(...), snarare än ett fält som hämtats från en annan modell).
options är en valfri ordlista med värden från modellens Meta-klass.
bases är en valfri lista över andra klasser som den här modellen ska ärva från; den kan innehålla både klassobjekt och strängar i formatet "appname.ModelName" om du vill vara beroende av en annan modell (så att du ärver från den historiska versionen). Om den inte anges ärver den som standard från standardmodellen models.Model.
managers tar en lista med 2-tuples av (manager_name, manager_instance). Den första hanteraren i listan kommer att vara standardhanteraren för den här modellen under migreringar.
DeleteModelLink to this heading#Raderar modellen från projekthistoriken och dess tabell från databasen.
\nRenameModelLink to this heading#Byter namn på modellen från ett gammalt namn till ett nytt.
\nDu kan behöva lägga till detta manuellt om du ändrar modellens namn och en hel del av dess fält på en gång. För autodetektorn ser det ut som om du har tagit bort en modell med det gamla namnet och lagt till en ny med ett annat namn, och den migrering som skapas kommer att förlora alla data i den gamla tabellen.
\nAlterModelTableLink to this heading#Ändrar modellens tabellnamn (alternativet db_table på underklassen Meta).
AlterModelTableKommentarLink to this heading#Ändrar modellens tabellkommentar (alternativet db_table_comment på underklassen Meta).
AlterUniqueTogetherLink to this heading#Ändrar modellens uppsättning av unika begränsningar (alternativet unique_together på underklassen Meta).
AlterIndexTillsammanLink to this heading#Ändrar modellens uppsättning av anpassade index (alternativet index_together i underklassen Meta).
AlterOrderMedAvseendePåLink to this heading#Skapar eller tar bort kolumnen _order som behövs för alternativet order_with_respect_to på subklassen Meta.
AlterModelOptionsLink to this heading#Lagrar ändringar av olika modellalternativ (inställningar på en modells Meta) som permissions och verbose_name. Påverkar inte databasen, men lagrar dessa ändringar så att RunPython-instanser kan använda dem. options bör vara en ordbok som mappar alternativnamn till värden.
AlterModelManagersLink to this heading#Ändrar de chefer som är tillgängliga under migreringar.
\nAddFieldLink to this heading#Lägger till ett fält till en modell. model_name är modellens namn, name är fältets namn och field är en obunden fältinstans (det som du skulle lägga till i fältdeklarationen i models.py - till exempel models.IntegerField(null=True).
Argumentet preserve_default anger om fältets standardvärde är permanent och ska bakas in i projekttillståndet (True), eller om det är tillfälligt och bara för den här migreringen (False) - vanligtvis för att migreringen lägger till ett icke-nullbart fält i en tabell och behöver ett standardvärde att lägga in i befintliga rader. Det påverkar inte beteendet att ställa in standardvärden i databasen direkt - Django ställer aldrig in standardvärden i databasen och tillämpar dem alltid i Django ORM-koden.
Avlägsna fältLink to this heading#Tar bort ett fält från en modell.
\nTänk på att detta faktiskt innebär att ett fält läggs till i en modell när det vänds. Åtgärden är reversibel (bortsett från eventuell dataförlust, som är irreversibel) om fältet är nollställbart eller om det har ett standardvärde som kan användas för att fylla i den återskapade kolumnen. Om fältet inte är nollställbart och inte har något standardvärde är åtgärden irreversibel.
\n\nAlterFieldLink to this heading#Ändrar ett fälts definition, inklusive ändringar av dess typ, null, unique, db_column och andra fältattribut.
Argumentet preserve_default anger om fältets standardvärde är permanent och ska bakas in i projekttillståndet (True), eller om det är tillfälligt och bara för den här migreringen (False) - vanligtvis för att migreringen ändrar ett nollställbart fält till ett icke-nullställbart och behöver ett standardvärde att lägga in i befintliga rader. Det påverkar inte beteendet att ställa in standardvärden i databasen direkt - Django ställer aldrig in standardvärden i databasen och tillämpar dem alltid i Django ORM-koden.
Observera att alla ändringar inte är möjliga i alla databaser - du kan t.ex. inte ändra ett fält av texttyp som models.TextField() till ett fält av siffertyp som models.IntegerField() i de flesta databaser.
RenameFieldLink to this heading#Ändrar ett fälts namn (och, om inte db_column har angetts, dess kolumnnamn).
AddIndexLink to this heading#Skapar ett index i databastabellen för modellen med model_name. index är en instans av klassen Index.
RemoveIndexLink to this heading#Tar bort indexet med namnet name från modellen med model_name.
RenameIndexLink to this heading#Byter namn på ett index i databastabellen för modellen med model_name. Exakt ett av old_name och old_fields kan anges. old_fields är en iterabel av strängarna, som ofta motsvarar fält i index_together (alternativ före Django 5.1).
I databaser som inte stöder en indexomdöpning (SQLite och MariaDB < 10.5.2) kommer åtgärden att ta bort och återskapa indexet, vilket kan bli dyrt.
\nAddConstraintLink to this heading#Skapar en constraint i databastabellen för modellen med model_name.
Tar bort begränsningen med namnet namn från modellen med modell_namn.
AlterConstraintLink to this heading#Ändrar begränsningen med namnet name i modellen med model_name med den nya constraint utan att påverka databasen.
RunSQLLink to this heading#Gör det möjligt att köra godtycklig SQL på databasen - användbart för mer avancerade funktioner i databasbackends som Django inte stöder direkt.
\nsql, och reverse_sql om det tillhandahålls, bör vara strängar av SQL som ska köras på databasen. På de flesta databasbackends (alla utom PostgreSQL) kommer Django att dela upp SQL i enskilda uttalanden innan de körs.
Du kan också skicka en lista med strängar eller 2-tupler. Den senare används för att skicka frågor och parametrar på samma sätt som cursor.execute(). Dessa tre operationer är likvärdiga:
\nmigrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])])\nOm du vill inkludera bokstavliga procenttecken i frågan måste du dubbla dem om du skickar parametrar.
\nFrågorna reverse_sql körs när migreringen inte tillämpas. De bör ångra det som gjorts av sql-frågorna. Till exempel:, för att ångra ovanstående infogning med en borttagning:
migrations.RunSQL(\n sql=[("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])],\n reverse_sql=[("DELETE FROM musician where name=%s;", ["Reinhardt"])],\n)\nOm reverse_sql är None (standard) är RunSQL-operationen irreversibel.
Med argumentet state_operations kan du ange operationer som är likvärdiga med SQL när det gäller projektstatus. Om du till exempel skapar en kolumn manuellt bör du skicka in en lista som innehåller en AddField operation här så att autodetektorn fortfarande har ett uppdaterat tillstånd för modellen. Om du inte gör det, när du nästa gång kör makemigrations, kommer den inte att se någon operation som lägger till det fältet och kommer därför att försöka köra den igen. Till exempel:
migrations.RunSQL(\n "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",\n state_operations=[\n migrations.AddField(\n "musician",\n "name",\n models.CharField(max_length=255),\n ),\n ],\n)\nDet valfria argumentet hints kommer att skickas som **hints till metoden allow_migrate`() i databasroutrar för att hjälpa dem att fatta beslut om routning. Se Tips för mer information om databastips.
Det valfria argumentet elidable avgör om åtgärden ska tas bort (elided) när squashing migrations.
Skicka attributet RunSQL.noop till sql eller reverse_sql när du vill att operationen inte ska göra någonting i den angivna riktningen. Detta är särskilt användbart för att göra operationen reversibel.
RunPythonLink to this heading#Kör anpassad Python-kod i ett historiskt sammanhang. code (och reverse_code om det tillhandahålls) ska vara anropsbara objekt som accepterar två argument; det första är en instans av django.apps.registry.Apps som innehåller historiska modeller som matchar operationens plats i projekthistoriken, och det andra är en instans av SchemaEditor.
Argumentet reverse_code anropas vid avapplicering av migreringar. Denna anropbara bör ångra vad som gjorts i den anropbara code så att migreringen är reversibel. Om reverse_code är None (standard), är RunPython-operationen irreversibel.
Det valfria argumentet hints kommer att skickas som **hints till metoden allow_migrate`() i databasroutrar för att hjälpa dem att fatta ett routningsbeslut. Se Tips för mer information om databastips.
Det valfria argumentet elidable avgör om åtgärden ska tas bort (elided) när squashing migrations.
Vi rekommenderar att du skriver koden som en separat funktion ovanför klassen Migration i migreringsfilen och skickar den till RunPython. Här är ett exempel på hur du använder RunPython för att skapa några initiala objekt på en Country-modell:
from django.db import migrations\n\n\ndef forwards_func(apps, schema_editor):\n # We get the model from the versioned app registry;\n # if we directly import it, it'll be the wrong version\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).bulk_create(\n [\n Country(name="USA", code="us"),\n Country(name="France", code="fr"),\n ]\n )\n\n\ndef reverse_func(apps, schema_editor):\n # forwards_func() creates two Country instances,\n # so reverse_func() should delete them.\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).filter(name="USA", code="us").delete()\n Country.objects.using(db_alias).filter(name="France", code="fr").delete()\n\n\nclass Migration(migrations.Migration):\n dependencies = []\n\n operations = [\n migrations.RunPython(forwards_func, reverse_func),\n ]\nDetta är i allmänhet den operation du skulle använda för att skapa datamigreringar, köra anpassade datauppdateringar och ändringar och allt annat du behöver tillgång till en ORM och/eller Python-kod för.
\nPrecis som RunSQL, se till att om du ändrar schema här inne gör du det antingen utanför omfattningen av Djangos modellsystem (t.ex. triggers) eller att du använder SeparateDatabaseAndState för att lägga till operationer som återspeglar dina ändringar i modelltillståndet - annars kommer den versionerade ORM och autodetektorn att sluta fungera korrekt.
Som standard kommer RunPython att köra sitt innehåll inuti en transaktion på databaser som inte stöder DDL-transaktioner (till exempel MySQL och Oracle). Detta bör vara säkert, men kan orsaka en krasch om du försöker använda schema_editor som tillhandahålls på dessa backends; i detta fall, skicka atomic=False till RunPython-operationen.
På databaser som stöder DDL-transaktioner (SQLite och PostgreSQL) har RunPython -operationer inga transaktioner som automatiskt läggs till förutom de transaktioner som skapas för varje migrering. Således, till exempel på PostgreSQL, bör du undvika att kombinera schemaändringar och RunPython-operationer i samma migrering, annars kan du träffa fel som OperationalError: cannot ALTER TABLE "mytable" because it has pending trigger events.
Om du har en annan databas och inte är säker på om den stöder DDL-transaktioner, kontrollera attributet django.db.connection.features.can_rollback_ddl.
Om åtgärden RunPython är en del av en non-atomic migration, kommer åtgärden endast att utföras i en transaktion om atomic=True skickas till åtgärden RunPython.
Skicka metoden RunPython.noop till code eller reverse_code när du vill att operationen inte ska göra något i den angivna riktningen. Detta är särskilt användbart för att göra operationen reversibel.
SepareraDatabasOchStatusLink to this heading#En mycket specialiserad operation som gör det möjligt att kombinera databasaspekter (schemaändring) och statliga aspekter (autodetektorkraft) av operationer.
\nDen accepterar två listor med operationer. När du blir ombedd att tillämpa tillstånd kommer den att använda listan `` state_operations`` (detta är en generaliserad version av RunSQL’s `` state_operations`` argument). När den ombeds att tillämpa ändringar i databasen kommer den att använda listan database_operations.
Om databasens faktiska tillstånd och Djangos syn på tillståndet inte är synkroniserade kan detta bryta migreringsramverket och till och med leda till dataförlust. Det är värt att vara försiktig och kontrollera dina databas- och tillståndsoperationer noggrant. Du kan använda sqlmigrate och dbshell för att kontrollera dina databasoperationer. Du kan använda makemigrations, särskilt med --dry-run, för att kontrollera dina tillståndsoperationer.
För ett exempel på användning av SeparateDatabaseAndState, se Ändra en ManyToManyField så att den använder en through-modell.
Kategorier av migreringsoperationer som används av kommandot makemigrations för att visa meningsfulla symboler.
Symbol: +
Symbol: -
Symbol: ~
Symbol: p
Symbol: s
Symbol: ?
Operationer har ett relativt enkelt API, och de är utformade så att du enkelt kan skriva dina egna för att komplettera de inbyggda Django. Den grundläggande strukturen för en Operation ser ut så här:
from django.db.migrations.operations.base import Operation\n\n\nclass MyCustomOperation(Operation):\n # If this is False, it means that this operation will be ignored by\n # sqlmigrate; if true, it will be run and the SQL collected for its output.\n reduces_to_sql = False\n\n # If this is False, Django will refuse to reverse past this operation.\n reversible = False\n\n # This categorizes the operation. The corresponding symbol will be\n # displayed by the makemigrations command.\n category = OperationCategory.ADDITION\n\n def __init__(self, arg1, arg2):\n # Operations are usually instantiated with arguments in migration\n # files. Store the values of them on self for later use.\n pass\n\n def state_forwards(self, app_label, state):\n # The Operation should take the 'state' parameter (an instance of\n # django.db.migrations.state.ProjectState) and mutate it to match\n # any schema changes that have occurred.\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # The Operation should use schema_editor to apply any changes it\n # wants to make to the database.\n pass\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n # If reversible is True, this is called when the operation is reversed.\n pass\n\n def describe(self):\n # This is used to describe what the operation does.\n return "Custom Operation"\n\n @property\n def migration_name_fragment(self):\n # Optional. A filename part suitable for automatically naming a\n # migration containing this operation, or None if not applicable.\n return "custom_operation_%s_%s" % (self.arg1, self.arg2)\nDu kan ta den här mallen och arbeta utifrån den, men vi föreslår att du tittar på de inbyggda Django-operationerna i django.db.migrations.operations - de täcker mycket av exempelanvändningen av semi-interna aspekter av migreringsramen som ProjectState och de mönster som används för att få historiska modeller, liksom ModelState och de mönster som används för att mutera historiska modeller i state_forwards().
Några saker att notera:
\nDu behöver inte lära dig så mycket om ProjectState för att skriva migreringar; du behöver bara veta att den har en apps-egenskap som ger tillgång till ett appregister (som du sedan kan anropa get_model på).
database_forwards och database_backwards får båda två tillstånd skickade till sig; dessa representerar skillnaden som state_forwards-metoden skulle ha tillämpat, men ges till dig av bekvämlighets- och hastighetsskäl.
Om du vill arbeta med modellklasser eller modellinstanser från argumentet from_state i database_forwards() eller database_backwards() måste du rendera modelltillstånd med metoden clear_delayed_apps_cache() för att göra relaterade modeller tillgängliga:
def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # This operation should have access to all models. Ensure that all models are\n # reloaded in case any are delayed.\n from_state.clear_delayed_apps_cache()\n ...\nto_state i metoden database_backwards är det äldre tillståndet, det vill säga det som kommer att vara det aktuella tillståndet när migreringen har avslutats.
Du kan se implementeringar av references_model på de inbyggda operationerna; detta är en del av autodetekteringskoden och spelar ingen roll för anpassade operationer.
Låt oss som ett exempel göra en operation som laddar PostgreSQL-tillägg (som innehåller några av PostgreSQL: s mer spännande funktioner). Eftersom det inte finns några förändringar i modelltillståndet är allt det gör att köra ett kommando:
\nfrom django.db.migrations.operations.base import Operation\n\n\nclass LoadExtension(Operation):\n reversible = True\n\n def __init__(self, name):\n self.name = name\n\n def state_forwards(self, app_label, state):\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("CREATE EXTENSION IF NOT EXISTS %s" % self.name)\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("DROP EXTENSION %s" % self.name)\n\n def describe(self):\n return "Creates extension %s" % self.name\n\n @property\n def migration_name_fragment(self):\n return "create_extension_%s" % self.name\n