Αυτό το άρθρο εξηγεί πως να δομήσετε και να γράψετε migrations για τη βάση δεδομένων (database migrations), βασιζόμενοι σε διαφορετικά σενάρια που μπορεί να συναντήσετε. Για μια εισαγωγή στα migrations, δείτε στο άρθρο migrations.
\nΌταν χρησιμοποιείτε πολλές βάσεις δεδομένων, συχνά θα βρίσκεστε σε δίλλημα να τρέξετε ένα migration σε κάποια συγκεκριμένη βάση δεδομένων. Για παράδειγμα, ίσως να θέλετε να τρέξετε ένα migration μόνο για μια συγκεκριμένη βάση δεδομένων.
\nΓια να το κάνετε αυτό, ελέγξτε το alias της σύνδεσης της βάσης δεδομένων μέσα σε μια RunPython λειτουργία, κοιτώντας το attribute του 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\nΈπειτα, για να το αξιοποιήσετε αυτό στα migrations σας, κάντε τα ακόλουθα:
\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 ]\nΑν η RunPython ή η RunSQL λειτουργία σας, επιδρά μόνο σε ένα μοντέλο, μια καλή πρακτική είναι να περάσετε το model_name ως hint για να το κάνετε όσο γίνεται πιο διαφανές στον router. Αυτό είναι ιδιαίτερα σημαντικό για επαναχρησιμοποιήσιμες και third-party εφαρμογές.
Εφαρμόζοντας ένα «απλό» migration το οποίο προσθέτει ένα μοναδικό μη-κενό πεδίο (unique non-nullable field) σε έναν πίνακα με ήδη υπάρχουσες γραμμές, θα κάνει raise κάποιο σφάλμα επειδή δεν είναι δυνατόν να αναπαραχθεί κάποια μοναδική τιμή για κάθε γραμμή της στήλης αυτής. Επίσης δεν γίνεται να ορίσουμε μια default τιμή καθώς δεν μπορεί κάθε γραμμή να έχει την ίδια τιμή για αυτή τη στήλη.
\nΓια να λύσουμε αυτό το πρόβλημα, θα πρέπει να ακολουθήσουμε τα παρακάτω βήματα. Σε αυτό το παράδειγμα, θα προσθέσουμε ένα μη-κενό πεδίο του τύπου UUIDField με μια προεπιλεγμένη τιμή (default value). Τροποποιήστε το αντίστοιχο δικό σας πεδίο ανάλογα τις ανάγκες σας.
Προσθέστε ένα πεδίο στο μοντέλο σας με τις παραμέτρους default=uuid.uuid4 και unique=True (επιλέξτε μια κατάλληλη προεπιλεγμένη τιμή ανάλογα τον τύπο του πεδίου που πρόκειται να προσθέσετε).
Τρέξτε την διαχειριστική εντολή makemigrations. Η εντολή αυτή θα δημιουργήσει ένα αρχείο migration με την λειτουργία του AddField μέσα του.
Δημιουργήστε δύο κενά migration αρχεία για την ίδια εφαρμογή, τρέχοντας δύο φορές την εντολή makemigrations myapp --empty. Στο παράδειγμα μας, έχουμε μετονομάσει τα αρχεία των migrations για να τους δώσουμε πιο επεξηγηματικά ονόματα.
Αντιγράψτε τη λειτουργία του AddField από το migration αρχείο που δημιουργήθηκε με την εντολή makemigrations (το πρώτο από τα τρία migration αρχεία) στο τελευταίο (το δεύτερο από τα δύο κενά) και αλλάξτε το AddField σε AlterField. Επίσης, προσθέστε τα ανάλογα imports για τα modules uuid και models. Για παράδειγμα:
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 ]\nΕπεξεργαστείτε το πρώτο αρχείο του migration, το οποίο θα μοιάζει κάπως έτσι:
\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Αλλάξτε το unique=True σε null=True – αυτό θα δημιουργήσει ένα μεσάζων κενό πεδίο που δεν περιέχει τον περιορισμό της μοναδικότητας (unique constraint) μέχρις ότου δημιουργήσουμε μοναδικές τιμές για κάθε γραμμή αυτής της στήλης.
Στο πρώτο κενό migration αρχείο (το δεύτερο εκ των τριών), προσθέστε μια λειτουργία RunPython ή RunSQL για να δημιουργήσετε μια μοναδική τιμή (σε αυτό το παράδειγμα δημιουργούμε μια τιμή του τύπου UUID) για κάθε υπάρχουσα γραμμή. Επίσης, προσθέστε και το απαραίτητο import για το module uuid. Για παράδειγμα:
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 ]\nΤώρα μπορείτε να εφαρμόσετε τα migration αρχεία, ως συνήθως, με την διαχειριστική εντολή migrate.
Σημειώστε ότι θα υπάρξει race condition αν επιτρέψετε να δημιουργηθούν objects όσο το migration τρέχει. Η τιμή της uuid των objects που θα δημιουργηθούν μεταξύ της λειτουργίας του AddField και της RunPython θα γίνει overwritten.
Στις βάσεις δεδομένων που υποστηρίζουν DDL transactions (όπως η SQLite και η PostgreSQL), τα migrations θα τρέξουν μέσα σε ένα transaction από προεπιλογή. Για τις περιπτώσεις όπου θα πραγματοποιηθούν data migrations σε μεγάλους πίνακες, ίσως να θέλετε να αποτρέψετε το migration να τρέξει μέσα σε ένα transaction θέτοντας το attribute atomic σε 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.
Παρακάτω φαίνεται ένα παράδειγμα ενός non-atomic data migration, το οποίο ενημερώνει έναν μεγάλο πίνακα ανά μικρότερα κομμάτια:
\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 ]\nThe atomic attribute doesn’t have an effect on databases that don’t support\nDDL transactions (e.g. MySQL, Oracle). (MySQL’s atomic DDL statement support refers to individual\nstatements rather than multiple statements wrapped in a transaction that can be\nrolled back.)
Το Django δεν καθορίζει τη σειρά εκτέλεσης των migration αρχείων από το όνομα τους αλλά δημιουργώντας ένα γράφημα χρησιμοποιώντας δύο properties της κλάσης Migration: το dependencies και το run_before.
Αν έχετε χρησιμοποιήσει την διαχειριστική εντολή makemigrations θα έχετε δει, πιθανόν, το property dependencies που δημιουργείται αυτόματα μέσα σε κάθε migration αρχείο.
Το property dependencies ορίζεται ως εξής:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ]\nΣυνήθως αυτό θα είναι αρκετό, αλλά μερικές φορές ίσως χρειαστεί να βεβαιωθείτε ότι το migration αρχείο σας τρέξει πριν τρέξουν άλλα migrations. Αυτό είναι χρήσιμο, για παράδειγμα, να κάνετε τα migration αρχεία τρίτων εφαρμογών να τρέξουν μετά την αντικατάσταση της δική σας ρύθμισης AUTH_USER_MODEL.
Για να το επιτύχετε αυτό, τοποθετήστε όλα τα migrations τα οποία εξαρτώνται από τα δικά σας, στο attribute run_before της κλάσης Migration:
class Migration(migrations.Migration):\n ...\n\n run_before = [\n ("third_party_app", "0001_do_awesome"),\n ]\nΠροτιμήστε να χρησιμοποιείτε το dependencies αντί του run_before όπου αυτό είναι δυνατόν. Θα πρέπει να χρησιμοποιείτε το run_before μόνο όταν είναι μη επιθυμητό ή μη πρακτικό να προσδιορίσετε το dependencies σε ένα migration αρχείο το οποίο θέλετε να τρέξει μετά από αυτό που γράφετε.
Μπορείτε να χρησιμοποιήσετε το data migration για να μετακινήσετε δεδομένα (data) από μια εφαρμογή τρίτου σε μια άλλη.
\nΑν σκοπεύετε να αφαιρέσετε αργότερα την παλιά εφαρμογή σας, θα χρειαστεί να ορίσετε το property dependencies βασιζόμενοι στο αν η παλιά σας εφαρμογή είναι εγκατεστημένη ή όχι. Σε διαφορετική περίπτωση, θα έχετε απόντα dependencies μόλις απεγκαταστήσετε την παλιά εφαρμογή. Ομοίως, θα χρειαστεί να κάνετε catch το exception LookupError μέσα στην κλήση της μεθόδου ``apps.get_model()``η οποία ανακτά τα μοντέλα από την παλιά εφαρμογή. Αυτή η μέθοδος σας επιτρέπει να ανεβάσετε το project σας σε κάποιον server (deployment) χωρίς να χρειάζεται, πρώτα, να εγκαταστήσετε και μετά να απεγκαταστήσετε την παλιά σας εφαρμογή.
Παρακάτω φαίνεται ένα δείγμα ενός migration αρχείου:
\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"))\nΕπίσης, σκεφτείτε τι θα θέλατε να γίνει όταν το migration δεν εφαρμοστεί. Θα μπορούσατε να μην κάνετε τίποτα (όπως στο παραπάνω παράδειγμα) ή να αφαιρέσετε κάποια ή όλα τα data από την καινούργια εφαρμογή. Προσαρμόστε το δεύτερο argument της λειτουργίας του RunPython καταλλήλως.
ManyToManyField to use a through modelLink 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.
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 ]\nΑν θέλετε να αλλάξετε ένα unmanaged μοντέλο (managed=False) σε managed, θα πρέπει να αφαιρέσετε το managed=False και να δημιουργήσετε ένα migration προτού κάνετε άλλες αλλαγές στο μοντέλο σχετικά με το schema, αφού οι αλλαγές στο schema οι οποίες εμφανίζονται στο migration που περιέχει την αλλαγή του Meta.managed ίσως να μην εφαρμοστούν. Με άλλα λόγια, δημιουργήστε και τρέξτε ένα migration μετά την αφαίρεση του managed=False και κατόπιν μπορείτε ελεύθερα να κάνετε τις schema αλλαγές στο (managed) μοντέλο σας.