| 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. |