Questo documento spiega come strutturare e scrivere migrazioni di database per diversi scenari che potresti incontrare. Per materiale introduttivo sulle migrazioni, vedere the topic guide.
\nQuando usi più database, potresti aver bisogno di capire se è necessario utilizzare una migrazione per un particolare database. Per esempio, puoi voler lanciare solo una migrazione verso uno specifico database.
\nPer fare ciò è possibile controllare l’alias della connessione del database all’interno di un’operazione RunPython guardando l’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\nQuindi, per sfruttare questo nelle tue migrazioni, procedi come segue:
\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 la tua operazione RunPython o RunSQL interessa solo un modello, è buona norma passare model_name come suggerimento per renderlo il più trasparente possibile al router. Ciò è particolarmente importante per le app riutilizzabili e di terze parti.
L’applicazione di una migrazione «plain» che aggiunge un campo univoco non annullabile a una tabella con righe esistenti genererà un errore poiché il valore utilizzato per popolare le righe esistenti viene generato una sola volta, interrompendo così il vincolo univoco.
\nPertanto, è necessario eseguire i seguenti passaggi. In questo esempio, aggiungeremo un non-nullable UUIDField con un valore predefinito. Modifica il rispettivo campo in base alle tue esigenze.
Aggiungi il campo al tuo modello con gli argomenti default=uuid.uuid4 e unique=True (scegli un valore predefinito appropriato per il tipo di campo che stai aggiungendo).
Esegui il comando makemigrations. Questo dovrebbe generare una migrazione con un’operazione AddField.
Genera due file di migrazione vuoti per la stessa app eseguendo due volte makemigrations myapp --empty. Abbiamo rinominato i file di migrazione per assegnare loro nomi significativi negli esempi seguenti.
Copia l’operazione AddField dalla migrazione generata automaticamente (il primo dei tre nuovi file) all’ultima migrazione, cambia AddField in AlterField e aggiungi le importazioni di uuid e models. Per esempio:
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 ]\nModifica il primo file di migrazione. La classe di migrazione generata sarà simile a questa:
\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 ]\nCambia unique=True in null=True – questo creerà il campo null intermedio e rinvierà la creazione del vincolo univoco fino a quando non avremo popolato valori univoci su tutte le righe.
Nel primo file di migrazione vuoto, aggiungi una operazione RunPython o RunSQL per generare un valore univoco (UUID nell’esempio) per ogni riga esistente. Aggiungi anche un import di uuid. Per esempio:
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 ]\nOra puoi applicare le migrazioni come al solito con il comando migrate .
Nota che si crea una race condition se permetti agli oggetti di essere creati mentre la migrazione gira. Gli oggetti creati dopo AddField e prima di RunPython avranno il loro uuid originale sovrascritto.
In un database che supporta le transazioni DDL (SQLite e PostgreSQL), le migrations sono eseguite di default all’interno di una transazione. Per casi d’uso quali migrations su grandi tabelle, potresti voler evitare l’esecuzione delle migrations all’interno di una transazione, configurando l’attributo atomic a 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.
Qui c’è un esempio di migrazione dei dati non atomica che aggiorna una grande tabella con piccoli passi automatici:
\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 ]\nL’attributo atomic non ha effetto sui database che non supportano le transazioni DDL (per es. MySQL, Oracle). (Il supporto per le istruzioni atomic DDL di MySQL si riferisce a singole istruzioni, piuttosto che a più istruzioni racchiuse in una transazione sulla quale si può fare roll back.)
Django determina l’ordine in cui le migrazioni dovrebbero essere applicate non in base al nome del file di ogni migrazione, ma usando un grafo che usa due proprietà sulla classe Migration: dependencies e run_before.
Se hai usato il comando makemigrations probabilmente hai già visto dependencies in azione perchè le migrazioni auto-generate lo hanno definito come parte del loro processo di creazione.
La proprietà dependencies viene dichiarata in questo modo:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ]\nGeneralmente questo basta, ma di volta in volta potresti aver bisogno di assicurarti che le tue migrazioni girino prima di altre migrazioni. Questo torna utile, ad esempio, per fare in modo che le migrazioni delle app di terze parti girino dopo i rimpiazzi sul tuo AUTH_USER_MODEL.
Per ottenere ciò, inserisci tutte le migrazioni che dovrebbero dipendere dalla tua nell’attributo run_before nella tua classe Migration:
class Migration(migrations.Migration):\n ...\n\n run_before = [\n ("third_party_app", "0001_do_awesome"),\n ]\nÈ preferibile usare dipendenze su run_before quando possibile. Dovresti usare run_before solo se non è desiderabile o non pratico specificare dependencies nella migrazione che vuoi eseguire dopo quella che stai scrivendo.
È possibile utilizzare una migrazione dei dati per spostare i dati da un’applicazione ad un’altra.
\nSe prevedi di rimuovere la vecchia app in un secondo momento, dovrai impostare la proprietà dependencies in base al fatto che la vecchia app sia installata o meno. Altrimenti, avrai le dipendenze mancanti dopo aver disinstallato la vecchia app. Allo stesso modo, dovrai catturare LookupError nella chiamata apps.get_model() che recupera i modelli dalla vecchia app. Questo approccio ti consente di distribuire il tuo progetto ovunque senza prima installare e quindi disinstallare la vecchia app.
Ecco un esempio di migrazione:
\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"))\nPotresti non fare nulla (come nell’esempio sopra) o rimuovere alcuni o tutti i dati dalla nuova applicazione. Regola di conseguenza il secondo argomento dell’operazione RunPython.
ManyToManyField per utilizzare un modello throughLink to this heading#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.
Per esempio, se avessimo un modello Book con un ManyToManyField collegato a Author, potremmo aggiungere un modello completo AuthorBook con un nuovo campo is_primary, come:
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 desideri modificare un modello non gestito (managed=False) in gestito, devi rimuovere managed=False e generare una migrazione prima di creare un altro schema -modifiche correlate al modello, poiché le modifiche allo schema che appaiono nella migrazione che contiene l’operazione di modifica di Meta.managed potrebbero non essere applicate.