Debian Codegraph @

docs/topics/migrations.txt

raw
1 ==========
2 Migrations
3 ==========
4
5 .. module:: django.db.migrations
6 :synopsis: Schema migration support for Django models
7
8 Migrations are Django's way of propagating changes you make to your models
9 (adding a field, deleting a model, etc.) into your database schema. They're
10 designed to be mostly automatic, but you'll need to know when to make
11 migrations, when to run them, and the common problems you might run into.
12
13 The Commands
14 ============
15
16 There are several commands which you will use to interact with migrations
17 and Django's handling of database schema:
18
19 * :djadmin:`migrate`, which is responsible for applying and unapplying
20 migrations.
21
22 * :djadmin:`makemigrations`, which is responsible for creating new migrations
23 based on the changes you have made to your models.
24
25 * :djadmin:`sqlmigrate`, which displays the SQL statements for a migration.
26
27 * :djadmin:`showmigrations`, which lists a project's migrations and their
28 status.
29
30 You should think of migrations as a version control system for your database
31 schema. ``makemigrations`` is responsible for packaging up your model changes
32 into individual migration files - analogous to commits - and ``migrate`` is
33 responsible for applying those to your database.
34
35 The migration files for each app live in a "migrations" directory inside
36 of that app, and are designed to be committed to, and distributed as part
37 of, its codebase. You should be making them once on your development machine
38 and then running the same migrations on your colleagues' machines, your
39 staging machines, and eventually your production machines.
40
41 .. note::
42 It is possible to override the name of the package which contains the
43 migrations on a per-app basis by modifying the :setting:`MIGRATION_MODULES`
44 setting.
45
46 Migrations will run the same way on the same dataset and produce consistent
47 results, meaning that what you see in development and staging is, under the
48 same circumstances, exactly what will happen in production.
49
50 Django will make migrations for any change to your models or fields - even
51 options that don't affect the database - as the only way it can reconstruct
52 a field correctly is to have all the changes in the history, and you might
53 need those options in some data migrations later on (for example, if you've
54 set custom validators).
55
56 Backend Support
57 ===============
58
59 Migrations are supported on all backends that Django ships with, as well
60 as any third-party backends if they have programmed in support for schema
61 alteration (done via the :doc:`SchemaEditor </ref/schema-editor>` class).
62
63 However, some databases are more capable than others when it comes to
64 schema migrations; some of the caveats are covered below.
65
66 PostgreSQL
67 ----------
68
69 PostgreSQL is the most capable of all the databases here in terms of schema
70 support.
71
72 MySQL
73 -----
74
75 MySQL lacks support for transactions around schema alteration operations,
76 meaning that if a migration fails to apply you will have to manually unpick
77 the changes in order to try again (it's impossible to roll back to an
78 earlier point).
79
80 MySQL 8.0 introduced significant performance enhancements for
81 `DDL operations`_, making them more efficient and reducing the need for full
82 table rebuilds. However, it cannot guarantee a complete absence of locks or
83 interruptions. In situations where locks are still necessary, the duration of
84 these operations will be proportionate to the number of rows involved.
85
86 Finally, MySQL has a relatively small limit on the combined size of all columns
87 an index covers. This means that indexes that are possible on other backends
88 will fail to be created under MySQL.
89
90 .. _DDL operations: https://dev.mysql.com/doc/refman/en/innodb-online-ddl-operations.html
91
92 SQLite
93 ------
94
95 SQLite has very little built-in schema alteration support, and so Django
96 attempts to emulate it by:
97
98 * Creating a new table with the new schema
99 * Copying the data across
100 * Dropping the old table
101 * Renaming the new table to match the original name
102
103 This process generally works well, but it can be slow and occasionally
104 buggy. It is not recommended that you run and migrate SQLite in a
105 production environment unless you are very aware of the risks and
106 its limitations; the support Django ships with is designed to allow
107 developers to use SQLite on their local machines to develop less complex
108 Django projects without the need for a full database.
109
110 Workflow
111 ========
112
113 Django can create migrations for you. Make changes to your models - say, add a
114 field and remove a model - and then run :djadmin:`makemigrations`:
115
116 .. code-block:: shell
117
118 $ python manage.py makemigrations
119 Migrations for 'books':
120 books/migrations/0003_auto.py:
121 ~ Alter field author on book
122
123 Your models will be scanned and compared to the versions currently
124 contained in your migration files, and then a new set of migrations
125 will be written out. Make sure to read the output to see what
126 ``makemigrations`` thinks you have changed - it's not perfect, and for
127 complex changes it might not be detecting what you expect.
128
129 Once you have your new migration files, you should apply them to your
130 database to make sure they work as expected:
131
132 .. code-block:: shell
133
134 $ python manage.py migrate
135 Operations to perform:
136 Apply all migrations: books
137 Running migrations:
138 Rendering model states... DONE
139 Applying books.0003_auto... OK
140
141 Once the migration is applied, commit the migration and the models change
142 to your version control system as a single commit - that way, when other
143 developers (or your production servers) check out the code, they'll
144 get both the changes to your models and the accompanying migration at the
145 same time.
146
147 If you want to give the migration(s) a meaningful name instead of a generated
148 one, you can use the :option:`makemigrations --name` option:
149
150 .. code-block:: shell
151
152 $ python manage.py makemigrations --name changed_my_model your_app_label
153
154 Version control
155 ---------------
156
157 Because migrations are stored in version control, you'll occasionally
158 come across situations where you and another developer have both committed
159 a migration to the same app at the same time, resulting in two migrations
160 with the same number.
161
162 Don't worry - the numbers are just there for developers' reference, Django
163 just cares that each migration has a different name. Migrations specify which
164 other migrations they depend on - including earlier migrations in the same
165 app - in the file, so it's possible to detect when there's two new migrations
166 for the same app that aren't ordered.
167
168 When this happens, Django will prompt you and give you some options. If it
169 thinks it's safe enough, it will offer to automatically linearize the two
170 migrations for you. If not, you'll have to go in and modify the migrations
171 yourself - don't worry, this isn't difficult, and is explained more in
172 :ref:`migration-files` below.
173
174 Transactions
175 ============
176
177 On databases that support DDL transactions (SQLite and PostgreSQL), all
178 migration operations will run inside a single transaction by default. In
179 contrast, if a database doesn't support DDL transactions (e.g. MySQL, Oracle)
180 then all operations will run without a transaction.
181
182 You can prevent a migration from running in a transaction by setting the
183 ``atomic`` attribute to ``False``. For example::
184
185 from django.db import migrations
186
187
188 class Migration(migrations.Migration):
189 atomic = False
190
191 It's also possible to execute parts of the migration inside a transaction using
192 :func:`~django.db.transaction.atomic()` or by passing ``atomic=True`` to
193 :class:`~django.db.migrations.operations.RunPython`. See
194 :ref:`non-atomic-migrations` for more details.
195
196 Dependencies
197 ============
198
199 While migrations are per-app, the tables and relationships implied by
200 your models are too complex to be created for one app at a time. When you make
201 a migration that requires something else to run - for example, you add a
202 ``ForeignKey`` in your ``books`` app to your ``authors`` app - the resulting
203 migration will contain a dependency on a migration in ``authors``.
204
205 This means that when you run the migrations, the ``authors`` migration runs
206 first and creates the table the ``ForeignKey`` references, and then the migration
207 that makes the ``ForeignKey`` column runs afterward and creates the constraint.
208 If this didn't happen, the migration would try to create the ``ForeignKey``
209 column without the table it's referencing existing and your database would
210 throw an error.
211
212 This dependency behavior affects most migration operations where you
213 restrict to a single app. Restricting to a single app (either in
214 ``makemigrations`` or ``migrate``) is a best-efforts promise, and not
215 a guarantee; any other apps that need to be used to get dependencies correct
216 will be.
217
218 Apps without migrations must not have relations (``ForeignKey``,
219 ``ManyToManyField``, etc.) to apps with migrations. Sometimes it may work, but
220 it's not supported.
221
222 Swappable dependencies
223 ----------------------
224
225 .. function:: django.db.migrations.swappable_dependency(value)
226
227 The ``swappable_dependency()`` function is used in migrations to declare
228 "swappable" dependencies on migrations in the app of the swapped-in model,
229 currently, on the first migration of this app. As a consequence, the swapped-in
230 model should be created in the initial migration. The argument ``value`` is a
231 string ``"<app label>.<model>"`` describing an app label and a model name, e.g.
232 ``"myapp.MyModel"``.
233
234 By using ``swappable_dependency()``, you inform the migration framework that
235 the migration relies on another migration which sets up a swappable model,
236 allowing for the possibility of substituting the model with a different
237 implementation in the future. This is typically used for referencing models
238 that are subject to customization or replacement, such as the custom user
239 model (``settings.AUTH_USER_MODEL``, which defaults to ``"auth.User"``) in
240 Django's authentication system.
241
242 .. _migration-files:
243
244 Migration files
245 ===============
246
247 Migrations are stored as an on-disk format, referred to here as
248 "migration files". These files are actually normal Python files with an
249 agreed-upon object layout, written in a declarative style.
250
251 A basic migration file looks like this::
252
253 from django.db import migrations, models
254
255
256 class Migration(migrations.Migration):
257 dependencies = [("migrations", "0001_initial")]
258
259 operations = [
260 migrations.DeleteModel("Tribble"),
261 migrations.AddField("Author", "rating", models.IntegerField(default=0)),
262 ]
263
264 What Django looks for when it loads a migration file (as a Python module) is
265 a subclass of ``django.db.migrations.Migration`` called ``Migration``. It then
266 inspects this object for four attributes, only two of which are used
267 most of the time:
268
269 * ``dependencies``, a list of migrations this one depends on.
270 * ``operations``, a list of ``Operation`` classes that define what this
271 migration does.
272
273 The operations are the key; they are a set of declarative instructions which
274 tell Django what schema changes need to be made. Django scans them and
275 builds an in-memory representation of all of the schema changes to all apps,
276 and uses this to generate the SQL which makes the schema changes.
277
278 That in-memory structure is also used to work out what the differences are
279 between your models and the current state of your migrations; Django runs
280 through all the changes, in order, on an in-memory set of models to come
281 up with the state of your models last time you ran ``makemigrations``. It
282 then uses these models to compare against the ones in your ``models.py`` files
283 to work out what you have changed.
284
285 You should rarely, if ever, need to edit migration files by hand, but
286 it's entirely possible to write them manually if you need to. Some of the
287 more complex operations are not autodetectable and are only available via
288 a hand-written migration, so don't be scared about editing them if you have to.
289
290 Custom fields
291 -------------
292
293 You can't modify the number of positional arguments in an already migrated
294 custom field without raising a ``TypeError``. The old migration will call the
295 modified ``__init__`` method with the old signature. So if you need a new
296 argument, please create a keyword argument and add something like
297 ``assert 'argument_name' in kwargs`` in the constructor.
298
299 .. _using-managers-in-migrations:
300
301 Model managers
302 --------------
303
304 You can optionally serialize managers into migrations and have them available
305 in :class:`~django.db.migrations.operations.RunPython` operations. This is done
306 by defining a ``use_in_migrations`` attribute on the manager class::
307
308 class MyManager(models.Manager):
309 use_in_migrations = True
310
311
312 class MyModel(models.Model):
313 objects = MyManager()
314
315 If you are using the :meth:`~django.db.models.from_queryset` function to
316 dynamically generate a manager class, you need to inherit from the generated
317 class to make it importable::
318
319 class MyManager(MyBaseManager.from_queryset(CustomQuerySet)):
320 use_in_migrations = True
321
322
323 class MyModel(models.Model):
324 objects = MyManager()
325
326 Please refer to the notes about :ref:`historical-models` in migrations to see
327 the implications that come along.
328
329 Initial migrations
330 ------------------
331
332 .. attribute:: Migration.initial
333
334 The "initial migrations" for an app are the migrations that create the first
335 version of that app's tables. Usually an app will have one initial migration,
336 but in some cases of complex model interdependencies it may have two or more.
337
338 Initial migrations are marked with an ``initial = True`` class attribute on the
339 migration class. If an ``initial`` class attribute isn't found, a migration
340 will be considered "initial" if it is the first migration in the app (i.e. if
341 it has no dependencies on any other migration in the same app).
342
343 When the :option:`migrate --fake-initial` option is used, these initial
344 migrations are treated specially. For an initial migration that creates one or
345 more tables (``CreateModel`` operation), Django checks that all of those tables
346 already exist in the database and fake-applies the migration if so. Similarly,
347 for an initial migration that adds one or more fields (``AddField`` operation),
348 Django checks that all of the respective columns already exist in the database
349 and fake-applies the migration if so. Without ``--fake-initial``, initial
350 migrations are treated no differently from any other migration.
351
352 .. _migration-history-consistency:
353
354 History consistency
355 -------------------
356
357 As previously discussed, you may need to linearize migrations manually when two
358 development branches are joined. While editing migration dependencies, you can
359 inadvertently create an inconsistent history state where a migration has been
360 applied but some of its dependencies haven't. This is a strong indication that
361 the dependencies are incorrect, so Django will refuse to run migrations or make
362 new migrations until it's fixed. When using multiple databases, you can use the
363 :meth:`allow_migrate` method of :ref:`database routers
364 <topics-db-multi-db-routing>` to control which databases
365 :djadmin:`makemigrations` checks for consistent history.
366
367 Adding migrations to apps
368 =========================
369
370 New apps come preconfigured to accept migrations, and so you can add migrations
371 by running :djadmin:`makemigrations` once you've made some changes.
372
373 If your app already has models and database tables, and doesn't have migrations
374 yet (for example, you created it against a previous Django version), you'll
375 need to convert it to use migrations by running:
376
377 .. code-block:: shell
378
379 $ python manage.py makemigrations your_app_label
380
381 This will make a new initial migration for your app. Now, run ``python
382 manage.py migrate --fake-initial``, and Django will detect that you have an
383 initial migration *and* that the tables it wants to create already exist, and
384 will mark the migration as already applied. (Without the :option:`migrate
385 --fake-initial` flag, the command would error out because the tables it wants
386 to create already exist.)
387
388 Note that this only works given two things:
389
390 * You have not changed your models since you made their tables. For migrations
391 to work, you must make the initial migration *first* and then make changes,
392 as Django compares changes against migration files, not the database.
393
394 * You have not manually edited your database - Django won't be able to detect
395 that your database doesn't match your models, you'll just get errors when
396 migrations try to modify those tables.
397
398 .. _reversing-migrations:
399
400 Reversing migrations
401 ====================
402
403 Migrations can be reversed with :djadmin:`migrate` by passing the number of the
404 previous migration. For example, to reverse migration ``books.0003``:
405
406 .. console::
407
408 $ python manage.py migrate books 0002
409 Operations to perform:
410 Target specific migration: 0002_auto, from books
411 Running migrations:
412 Rendering model states... DONE
413 Unapplying books.0003_auto... OK
414
415 If you want to reverse all migrations applied for an app, use the name
416 ``zero``:
417
418 .. console::
419
420 $ python manage.py migrate books zero
421 Operations to perform:
422 Unapply all migrations: books
423 Running migrations:
424 Rendering model states... DONE
425 Unapplying books.0002_auto... OK
426 Unapplying books.0001_initial... OK
427
428 A migration is irreversible if it contains any irreversible operations.
429 Attempting to reverse such migrations will raise ``IrreversibleError``:
430
431 .. console::
432
433 $ python manage.py migrate books 0002
434 Operations to perform:
435 Target specific migration: 0002_auto, from books
436 Running migrations:
437 Rendering model states... DONE
438 Unapplying books.0003_auto...Traceback (most recent call last):
439 django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL sql='DROP TABLE demo_books'> in books.0003_auto is not reversible
440
441 .. _historical-models:
442
443 Historical models
444 =================
445
446 When you run migrations, Django is working from historical versions of your
447 models stored in the migration files. If you write Python code using the
448 :class:`~django.db.migrations.operations.RunPython` operation, or if you have
449 ``allow_migrate`` methods on your database routers, you **need to use** these
450 historical model versions rather than importing them directly.
451
452 .. warning::
453
454 If you import models directly rather than using the historical models,
455 your migrations *may work initially* but will fail in the future when you
456 try to rerun old migrations (commonly, when you set up a new installation
457 and run through all the migrations to set up the database).
458
459 This means that historical model problems may not be immediately obvious.
460 If you run into this kind of failure, it's OK to edit the migration to use
461 the historical models rather than direct imports and commit those changes.
462
463 Because it's impossible to serialize arbitrary Python code, these historical
464 models will not have any custom methods that you have defined. They will,
465 however, have the same fields, relationships, managers (limited to those with
466 ``use_in_migrations = True``) and ``Meta`` options (also versioned, so they may
467 be different from your current ones).
468
469 .. warning::
470
471 This means that you will NOT have custom ``save()`` methods called on objects
472 when you access them in migrations, and you will NOT have any custom
473 constructors or instance methods. Plan appropriately!
474
475 References to functions in field options such as ``upload_to`` and
476 ``limit_choices_to`` and model manager declarations with managers having
477 ``use_in_migrations = True`` are serialized in migrations, so the functions and
478 classes will need to be kept around for as long as there is a migration
479 referencing them. Any :doc:`custom model fields </howto/custom-model-fields>`
480 will also need to be kept, since these are imported directly by migrations.
481
482 In addition, the concrete base classes of the model are stored as pointers, so
483 you must always keep base classes around for as long as there is a migration
484 that contains a reference to them. On the plus side, methods and managers from
485 these base classes inherit normally, so if you absolutely need access to these
486 you can opt to move them into a superclass.
487
488 To remove old references, you can :ref:`squash migrations <migration-squashing>`
489 or, if there aren't many references, copy them into the migration files.
490
491 .. _migrations-removing-model-fields:
492
493 Considerations when removing model fields
494 =========================================
495
496 Similar to the "references to historical functions" considerations described in
497 the previous section, removing custom model fields from your project or
498 third-party app will cause a problem if they are referenced in old migrations.
499
500 To help with this situation, Django provides some model field attributes to
501 assist with model field deprecation using the :doc:`system checks framework
502 </topics/checks>`.
503
504 Add the ``system_check_deprecated_details`` attribute to your model field
505 similar to the following::
506
507 class IPAddressField(Field):
508 system_check_deprecated_details = {
509 "msg": (
510 "IPAddressField has been deprecated. Support for it (except "
511 "in historical migrations) will be removed in Django 1.9."
512 ),
513 "hint": "Use GenericIPAddressField instead.", # optional
514 "id": "fields.W900", # pick a unique ID for your field.
515 }
516
517 After a deprecation period of your choosing (two or three feature releases for
518 fields in Django itself), change the ``system_check_deprecated_details``
519 attribute to ``system_check_removed_details`` and update the dictionary similar
520 to::
521
522 class IPAddressField(Field):
523 system_check_removed_details = {
524 "msg": (
525 "IPAddressField has been removed except for support in "
526 "historical migrations."
527 ),
528 "hint": "Use GenericIPAddressField instead.",
529 "id": "fields.E900", # pick a unique ID for your field.
530 }
531
532 You should keep the field's methods that are required for it to operate in
533 database migrations such as ``__init__()``, ``deconstruct()``, and
534 ``get_internal_type()``. Keep this stub field for as long as any migrations
535 which reference the field exist. For example, after squashing migrations and
536 removing the old ones, you should be able to remove the field completely.
537
538 .. _data-migrations:
539
540 Data Migrations
541 ===============
542
543 As well as changing the database schema, you can also use migrations to change
544 the data in the database itself, in conjunction with the schema if you want.
545
546 Migrations that alter data are usually called "data migrations"; they're best
547 written as separate migrations, sitting alongside your schema migrations.
548
549 Django can't automatically generate data migrations for you, as it does with
550 schema migrations, but it's not very hard to write them. Migration files in
551 Django are made up of :doc:`Operations </ref/migration-operations>`, and
552 the main operation you use for data migrations is
553 :class:`~django.db.migrations.operations.RunPython`.
554
555 To start, make an empty migration file you can work from (Django will put
556 the file in the right place, suggest a name, and add dependencies for you):
557
558 .. code-block:: shell
559
560 python manage.py makemigrations --empty yourappname
561
562 Then, open up the file; it should look something like this::
563
564 # Generated by Django A.B on YYYY-MM-DD HH:MM
565 from django.db import migrations
566
567
568 class Migration(migrations.Migration):
569 dependencies = [
570 ("yourappname", "0001_initial"),
571 ]
572
573 operations = []
574
575 Now, all you need to do is create a new function and have
576 :class:`~django.db.migrations.operations.RunPython` use it.
577 :class:`~django.db.migrations.operations.RunPython` expects a callable as its argument
578 which takes two arguments - the first is an :doc:`app registry
579 </ref/applications/>` that has the historical versions of all your models
580 loaded into it to match where in your history the migration sits, and the
581 second is a :doc:`SchemaEditor </ref/schema-editor>`, which you can use to
582 manually effect database schema changes (but beware, doing this can confuse
583 the migration autodetector!)
584
585 Let's write a migration that populates our new ``name`` field with the combined
586 values of ``first_name`` and ``last_name`` (we've come to our senses and
587 realized that not everyone has first and last names). All we need to do is use
588 the historical model and iterate over the rows::
589
590 from django.db import migrations
591
592
593 def combine_names(apps, schema_editor):
594 # We can't import the Person model directly as it may be a newer
595 # version than this migration expects. We use the historical version.
596 Person = apps.get_model("yourappname", "Person")
597 for person in Person.objects.all():
598 person.name = f"{person.first_name} {person.last_name}"
599 person.save()
600
601
602 class Migration(migrations.Migration):
603 dependencies = [
604 ("yourappname", "0001_initial"),
605 ]
606
607 operations = [
608 migrations.RunPython(combine_names),
609 ]
610
611 Once that's done, we can run ``python manage.py migrate`` as normal and the
612 data migration will run in place alongside other migrations.
613
614 You can pass a second callable to
615 :class:`~django.db.migrations.operations.RunPython` to run whatever logic you
616 want executed when migrating backwards. If this callable is omitted, migrating
617 backwards will raise an exception.
618
619 Accessing models from other apps
620 --------------------------------
621
622 When writing a ``RunPython`` function that uses models from apps other than the
623 one in which the migration is located, the migration's ``dependencies``
624 attribute should include the latest migration of each app that is involved,
625 otherwise you may get an error similar to: ``LookupError: No installed app
626 with label 'myappname'`` when you try to retrieve the model in the ``RunPython``
627 function using ``apps.get_model()``.
628
629 In the following example, we have a migration in ``app1`` which needs to use
630 models in ``app2``. We aren't concerned with the details of ``move_m1`` other
631 than the fact it will need to access models from both apps. Therefore we've
632 added a dependency that specifies the last migration of ``app2``::
633
634 class Migration(migrations.Migration):
635 dependencies = [
636 ("app1", "0001_initial"),
637 # added dependency to enable using models from app2 in move_m1
638 ("app2", "0004_foobar"),
639 ]
640
641 operations = [
642 migrations.RunPython(move_m1),
643 ]
644
645 More advanced migrations
646 ------------------------
647
648 If you're interested in the more advanced migration operations, or want
649 to be able to write your own, see the :doc:`migration operations reference
650 </ref/migration-operations>` and the "how-to" on :doc:`writing migrations
651 </howto/writing-migrations>`.
652
653 .. _migration-squashing:
654
655 Squashing migrations
656 ====================
657
658 You are encouraged to make migrations freely and not worry about how many you
659 have; the migration code is optimized to deal with hundreds at a time without
660 much slowdown. However, eventually you will want to move back from having
661 several hundred migrations to just a few, and that's where squashing comes in.
662
663 Squashing is the act of reducing an existing set of many migrations down to
664 one (or sometimes a few) migrations which still represent the same changes.
665
666 Django does this by taking all of your existing migrations, extracting their
667 ``Operation``\s and putting them all in sequence, and then running an optimizer
668 over them to try and reduce the length of the list - for example, it knows
669 that :class:`~django.db.migrations.operations.CreateModel` and
670 :class:`~django.db.migrations.operations.DeleteModel` cancel each other out,
671 and it knows that :class:`~django.db.migrations.operations.AddField` can be
672 rolled into :class:`~django.db.migrations.operations.CreateModel`.
673
674 Once the operation sequence has been reduced as much as possible - the amount
675 possible depends on how closely intertwined your models are and if you have
676 any :class:`~django.db.migrations.operations.RunSQL`
677 or :class:`~django.db.migrations.operations.RunPython` operations (which can't
678 be optimized through unless they are marked as ``elidable``) - Django will then
679 write it back out into a new set of migration files.
680
681 These files are marked to say they replace the previously-squashed migrations,
682 so they can coexist with the old migration files, and Django will intelligently
683 switch between them depending where you are in the history. If you're still
684 part-way through the set of migrations that you squashed, it will keep using
685 them until it hits the end and then switch to the squashed history, while new
686 installs will use the new squashed migration and skip all the old ones.
687
688 This enables you to squash and not mess up systems currently in production
689 that aren't fully up-to-date yet. The recommended process is to squash, keeping
690 the old files, commit and release, wait until all systems are upgraded with
691 the new release (or if you're a third-party project, ensure your users upgrade
692 releases in order without skipping any), and then remove the old files, commit
693 and do a second release.
694
695 The command that backs all this is :djadmin:`squashmigrations` - pass it the
696 app label and migration name you want to squash up to, and it'll get to work:
697
698 .. code-block:: shell
699
700 $ ./manage.py squashmigrations myapp 0004
701 Will squash the following migrations:
702 - 0001_initial
703 - 0002_some_change
704 - 0003_another_change
705 - 0004_undo_something
706 Do you wish to proceed? [y/N] y
707 Optimizing...
708 Optimized from 12 operations to 7 operations.
709 Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_something.py
710 You should commit this migration but leave the old ones in place;
711 the new migration will be used for new installs. Once you are sure
712 all instances of the codebase have applied the migrations you squashed,
713 you can delete them.
714
715 Use the :option:`squashmigrations --squashed-name` option if you want to set
716 the name of the squashed migration rather than use an autogenerated one.
717
718 Note that model interdependencies in Django can get very complex, and squashing
719 may result in migrations that do not run; either mis-optimized (in which case
720 you can try again with ``--no-optimize``, though you should also report an issue),
721 or with a ``CircularDependencyError``, in which case you can manually resolve it.
722
723 To manually resolve a ``CircularDependencyError``, break out one of
724 the ForeignKeys in the circular dependency loop into a separate
725 migration, and move the dependency on the other app with it. If you're unsure,
726 see how :djadmin:`makemigrations` deals with the problem when asked to create
727 brand new migrations from your models. In a future release of Django,
728 :djadmin:`squashmigrations` will be updated to attempt to resolve these errors
729 itself.
730
731 Once you've squashed your migration, you should then commit it alongside the
732 migrations it replaces and distribute this change to all running instances
733 of your application, making sure that they run ``migrate`` to store the change
734 in their database.
735
736 You must then transition the squashed migration to a normal migration by:
737
738 - Deleting all the migration files it replaces.
739 - Updating all migrations that depend on the deleted migrations to depend on
740 the squashed migration instead.
741 - Removing the ``replaces`` attribute in the ``Migration`` class of the
742 squashed migration (this is how Django tells that it is a squashed migration).
743
744 .. note::
745 Once you've squashed a migration, you should not then re-squash that squashed
746 migration until you have fully transitioned it to a normal migration.
747
748 .. admonition:: Pruning references to deleted migrations
749
750 If it is likely that you may reuse the name of a deleted migration in the
751 future, you should remove references to it from Django’s migrations table
752 with the :option:`migrate --prune` option.
753
754 .. _migration-serializing:
755
756 Serializing values
757 ==================
758
759 Migrations are Python files containing the old definitions of your models
760 - thus, to write them, Django must take the current state of your models and
761 serialize them out into a file.
762
763 While Django can serialize most things, there are some things that we just
764 can't serialize out into a valid Python representation - there's no Python
765 standard for how a value can be turned back into code (``repr()`` only works
766 for basic values, and doesn't specify import paths).
767
768 Django can serialize the following:
769
770 - ``int``, ``float``, ``bool``, ``str``, ``bytes``, ``None``, ``NoneType``
771 - ``list``, ``set``, ``tuple``, ``dict``, ``range``.
772 - ``datetime.date``, ``datetime.time``, and ``datetime.datetime`` instances
773 (include those that are timezone-aware)
774 - ``decimal.Decimal`` instances
775 - ``enum.Enum`` and ``enum.Flag`` instances
776 - ``uuid.UUID`` instances
777 - :func:`functools.partial` and :class:`functools.partialmethod` instances
778 which have serializable ``func``, ``args``, and ``keywords`` values.
779 - Pure and concrete path objects from :mod:`pathlib`. Concrete paths are
780 converted to their pure path equivalent, e.g. :class:`pathlib.PosixPath` to
781 :class:`pathlib.PurePosixPath`.
782 - :class:`os.PathLike` instances, e.g. :class:`os.DirEntry`, which are
783 converted to ``str`` or ``bytes`` using :func:`os.fspath`.
784 - ``LazyObject`` instances which wrap a serializable value.
785 - Enumeration types (e.g. ``TextChoices`` or ``IntegerChoices``) instances.
786 - Any Django field
787 - Any function or method reference (e.g. ``datetime.datetime.today``) (must be
788 in module's top-level scope)
789
790 - Functions may be decorated if wrapped properly, i.e. using
791 :func:`functools.wraps`
792 - The :func:`functools.cache` and :func:`functools.lru_cache` decorators are
793 explicitly supported
794
795 - Unbound methods used from within the class body
796 - Any class reference (must be in module's top-level scope)
797 - Anything with a custom ``deconstruct()`` method (:ref:`see below <custom-deconstruct-method>`)
798
799 Django cannot serialize:
800
801 - Nested classes
802 - Arbitrary class instances (e.g. ``MyClass(4.3, 5.7)``)
803 - Lambdas
804
805 .. _custom-migration-serializers:
806
807 Custom serializers
808 ------------------
809
810 You can serialize other types by writing a custom serializer. For example, if
811 Django didn't serialize :class:`~decimal.Decimal` by default, you could do
812 this::
813
814 from decimal import Decimal
815
816 from django.db.migrations.serializer import BaseSerializer
817 from django.db.migrations.writer import MigrationWriter
818
819
820 class DecimalSerializer(BaseSerializer):
821 def serialize(self):
822 return repr(self.value), {"from decimal import Decimal"}
823
824
825 MigrationWriter.register_serializer(Decimal, DecimalSerializer)
826
827 The first argument of ``MigrationWriter.register_serializer()`` is a type or
828 iterable of types that should use the serializer.
829
830 The ``serialize()`` method of your serializer must return a string of how the
831 value should appear in migrations and a set of any imports that are needed in
832 the migration.
833
834 .. _custom-deconstruct-method:
835
836 Adding a ``deconstruct()`` method
837 ---------------------------------
838
839 You can let Django serialize your own custom class instances by giving the class
840 a ``deconstruct()`` method. It takes no arguments, and should return a tuple
841 of three things ``(path, args, kwargs)``:
842
843 * ``path`` should be the Python path to the class, with the class name included
844 as the last part (for example, ``myapp.custom_things.MyClass``). If your
845 class is not available at the top level of a module it is not serializable.
846
847 * ``args`` should be a list of positional arguments to pass to your class'
848 ``__init__`` method. Everything in this list should itself be serializable.
849
850 * ``kwargs`` should be a dict of keyword arguments to pass to your class'
851 ``__init__`` method. Every value should itself be serializable.
852
853 .. note::
854
855 This return value is different from the ``deconstruct()`` method
856 :ref:`for custom fields <custom-field-deconstruct-method>` which returns a
857 tuple of four items.
858
859 Django will write out the value as an instantiation of your class with the
860 given arguments, similar to the way it writes out references to Django fields.
861
862 To prevent a new migration from being created each time
863 :djadmin:`makemigrations` is run, you should also add a ``__eq__()`` method to
864 the decorated class. This function will be called by Django's migration
865 framework to detect changes between states.
866
867 As long as all of the arguments to your class' constructor are themselves
868 serializable, you can use the ``@deconstructible`` class decorator from
869 ``django.utils.deconstruct`` to add the ``deconstruct()`` method::
870
871 from django.utils.deconstruct import deconstructible
872
873
874 @deconstructible
875 class MyCustomClass:
876 def __init__(self, foo=1):
877 self.foo = foo
878 ...
879
880 def __eq__(self, other):
881 return self.foo == other.foo
882
883
884 The decorator adds logic to capture and preserve the arguments on their
885 way into your constructor, and then returns those arguments exactly when
886 deconstruct() is called.
887
888 Supporting multiple Django versions
889 ===================================
890
891 If you are the maintainer of a third-party app with models, you may need to
892 ship migrations that support multiple Django versions. In this case, you should
893 always run :djadmin:`makemigrations` **with the lowest Django version you wish
894 to support**.
895
896 The migrations system will maintain backwards-compatibility according to the
897 same policy as the rest of Django, so migration files generated on Django X.Y
898 should run unchanged on Django X.Y+1. The migrations system does not promise
899 forwards-compatibility, however. New features may be added, and migration files
900 generated with newer versions of Django may not work on older versions.
901
902 .. seealso::
903
904 :doc:`The Migrations Operations Reference </ref/migration-operations>`
905 Covers the schema operations API, special operations, and writing your
906 own operations.
907
908 :doc:`The Writing Migrations "how-to" </howto/writing-migrations>`
909 Explains how to structure and write database migrations for different
910 scenarios you might encounter.