Debian Codegraph @

docs/ref/migration-operations.txt

raw
1 ====================
2 Migration Operations
3 ====================
4
5 .. module:: django.db.migrations.operations
6
7 Migration files are composed of one or more ``Operation``\s, objects that
8 declaratively record what the migration should do to your database.
9
10 Django also uses these ``Operation`` objects to work out what your models
11 looked like historically, and to calculate what changes you've made to
12 your models since the last migration so it can automatically write
13 your migrations; that's why they're declarative, as it means Django can
14 easily load them all into memory and run through them without touching
15 the database to work out what your project should look like.
16
17 There are also more specialized ``Operation`` objects which are for things like
18 :ref:`data migrations <data-migrations>` and for advanced manual database
19 manipulation. You can also write your own ``Operation`` classes if you want
20 to encapsulate a custom change you commonly make.
21
22 If you need an empty migration file to write your own ``Operation`` objects
23 into, use ``python manage.py makemigrations --empty yourappname``, but be aware
24 that manually adding schema-altering operations can confuse the migration
25 autodetector and make resulting runs of :djadmin:`makemigrations` output
26 incorrect code.
27
28 All of the core Django operations are available from the
29 ``django.db.migrations.operations`` module.
30
31 For introductory material, see the :doc:`migrations topic guide
32 </topics/migrations>`.
33
34 Schema Operations
35 =================
36
37 ``CreateModel``
38 ---------------
39
40 .. class:: CreateModel(name, fields, options=None, bases=None, managers=None)
41
42 Creates a new model in the project history and a corresponding table in the
43 database to match it.
44
45 ``name`` is the model name, as would be written in the ``models.py`` file.
46
47 ``fields`` is a list of 2-tuples of ``(field_name, field_instance)``.
48 The field instance should be an unbound field (so just
49 ``models.CharField(...)``, rather than a field taken from another model).
50
51 ``options`` is an optional dictionary of values from the model's ``Meta`` class.
52
53 ``bases`` is an optional list of other classes to have this model inherit from;
54 it can contain both class objects as well as strings in the format
55 ``"appname.ModelName"`` if you want to depend on another model (so you inherit
56 from the historical version). If it's not supplied, it defaults to inheriting
57 from the standard ``models.Model``.
58
59 ``managers`` takes a list of 2-tuples of ``(manager_name, manager_instance)``.
60 The first manager in the list will be the default manager for this model during
61 migrations.
62
63 ``DeleteModel``
64 ---------------
65
66 .. class:: DeleteModel(name)
67
68 Deletes the model from the project history and its table from the database.
69
70 ``RenameModel``
71 ---------------
72
73 .. class:: RenameModel(old_name, new_name)
74
75 Renames the model from an old name to a new one.
76
77 You may have to manually add
78 this if you change the model's name and quite a few of its fields at once; to
79 the autodetector, this will look like you deleted a model with the old name
80 and added a new one with a different name, and the migration it creates will
81 lose any data in the old table.
82
83 ``AlterModelTable``
84 -------------------
85
86 .. class:: AlterModelTable(name, table)
87
88 Changes the model's table name (the :attr:`~django.db.models.Options.db_table`
89 option on the ``Meta`` subclass).
90
91 ``AlterModelTableComment``
92 --------------------------
93
94 .. class:: AlterModelTableComment(name, table_comment)
95
96 Changes the model's table comment (the
97 :attr:`~django.db.models.Options.db_table_comment` option on the ``Meta``
98 subclass).
99
100 ``AlterUniqueTogether``
101 -----------------------
102
103 .. class:: AlterUniqueTogether(name, unique_together)
104
105 Changes the model's set of unique constraints (the
106 :attr:`~django.db.models.Options.unique_together` option on the ``Meta``
107 subclass).
108
109 ``AlterIndexTogether``
110 ----------------------
111
112 .. class:: AlterIndexTogether(name, index_together)
113
114 Changes the model's set of custom indexes (the ``index_together`` option on the
115 ``Meta`` subclass).
116
117 .. warning::
118
119 ``AlterIndexTogether`` is officially supported only for pre-Django 4.2
120 migration files. For backward compatibility reasons, it's still part of the
121 public API, and there's no plan to deprecate or remove it, but it should
122 not be used for new migrations. Use
123 :class:`~django.db.migrations.operations.AddIndex` and
124 :class:`~django.db.migrations.operations.RemoveIndex` operations instead.
125
126 ``AlterOrderWithRespectTo``
127 ---------------------------
128
129 .. class:: AlterOrderWithRespectTo(name, order_with_respect_to)
130
131 Makes or deletes the ``_order`` column needed for the
132 :attr:`~django.db.models.Options.order_with_respect_to` option on the ``Meta``
133 subclass.
134
135 ``AlterModelOptions``
136 ---------------------
137
138 .. class:: AlterModelOptions(name, options)
139
140 Stores changes to miscellaneous model options (settings on a model's ``Meta``)
141 like ``permissions`` and ``verbose_name``. Does not affect the database, but
142 persists these changes for :class:`RunPython` instances to use. ``options``
143 should be a dictionary mapping option names to values.
144
145 ``AlterModelManagers``
146 ----------------------
147
148 .. class:: AlterModelManagers(name, managers)
149
150 Alters the managers that are available during migrations.
151
152 ``AddField``
153 ------------
154
155 .. class:: AddField(model_name, name, field, preserve_default=True)
156
157 Adds a field to a model. ``model_name`` is the model's name, ``name`` is
158 the field's name, and ``field`` is an unbound Field instance (the thing
159 you would put in the field declaration in ``models.py`` - for example,
160 ``models.IntegerField(null=True)``.
161
162 The ``preserve_default`` argument indicates whether the field's default
163 value is permanent and should be baked into the project state (``True``),
164 or if it is temporary and just for this migration (``False``) - usually
165 because the migration is adding a non-nullable field to a table and needs
166 a default value to put into existing rows. It does not affect the behavior
167 of setting defaults in the database directly - Django never sets database
168 defaults and always applies them in the Django ORM code.
169
170 .. warning::
171
172 On older databases, adding a field with a default value may cause a full
173 rewrite of the table. This happens even for nullable fields and may have a
174 negative performance impact. To avoid that, the following steps should be
175 taken.
176
177 * Add the nullable field without the default value and run the
178 :djadmin:`makemigrations` command. This should generate a migration with
179 an ``AddField`` operation.
180
181 * Add the default value to your field and run the :djadmin:`makemigrations`
182 command. This should generate a migration with an ``AlterField``
183 operation.
184
185 ``RemoveField``
186 ---------------
187
188 .. class:: RemoveField(model_name, name)
189
190 Removes a field from a model.
191
192 Bear in mind that when reversed, this is actually adding a field to a model.
193 The operation is reversible (apart from any data loss, which is irreversible)
194 if the field is nullable or if it has a default value that can be used to
195 populate the recreated column. If the field is not nullable and does not have a
196 default value, the operation is irreversible.
197
198 .. admonition:: PostgreSQL
199
200 ``RemoveField`` will also delete any additional database objects that are
201 related to the removed field (like views, for example). This is because the
202 resulting ``DROP COLUMN`` statement will include the ``CASCADE`` clause to
203 ensure `dependent objects outside the table are also dropped`_.
204
205 .. _dependent objects outside the table are also dropped: https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-PARMS-CASCADE
206
207
208 ``AlterField``
209 --------------
210
211 .. class:: AlterField(model_name, name, field, preserve_default=True)
212
213 Alters a field's definition, including changes to its type,
214 :attr:`~django.db.models.Field.null`, :attr:`~django.db.models.Field.unique`,
215 :attr:`~django.db.models.Field.db_column` and other field attributes.
216
217 The ``preserve_default`` argument indicates whether the field's default
218 value is permanent and should be baked into the project state (``True``),
219 or if it is temporary and just for this migration (``False``) - usually
220 because the migration is altering a nullable field to a non-nullable one and
221 needs a default value to put into existing rows. It does not affect the
222 behavior of setting defaults in the database directly - Django never sets
223 database defaults and always applies them in the Django ORM code.
224
225 Note that not all changes are possible on all databases - for example, you
226 cannot change a text-type field like ``models.TextField()`` into a number-type
227 field like ``models.IntegerField()`` on most databases.
228
229 ``RenameField``
230 ---------------
231
232 .. class:: RenameField(model_name, old_name, new_name)
233
234 Changes a field's name (and, unless :attr:`~django.db.models.Field.db_column`
235 is set, its column name).
236
237 ``AddIndex``
238 ------------
239
240 .. class:: AddIndex(model_name, index)
241
242 Creates an index in the database table for the model with ``model_name``.
243 ``index`` is an instance of the :class:`~django.db.models.Index` class.
244
245 ``RemoveIndex``
246 ---------------
247
248 .. class:: RemoveIndex(model_name, name)
249
250 Removes the index named ``name`` from the model with ``model_name``.
251
252 ``RenameIndex``
253 ---------------
254
255 .. class:: RenameIndex(model_name, new_name, old_name=None, old_fields=None)
256
257 Renames an index in the database table for the model with ``model_name``.
258 Exactly one of ``old_name`` and ``old_fields`` can be provided. ``old_fields``
259 is an iterable of the strings, often corresponding to fields of
260 ``index_together`` (pre-Django 5.1 option).
261
262 On databases that don't support an index renaming statement (SQLite and MariaDB
263 < 10.5.2), the operation will drop and recreate the index, which can be
264 expensive.
265
266 ``AddConstraint``
267 -----------------
268
269 .. class:: AddConstraint(model_name, constraint)
270
271 Creates a :doc:`constraint </ref/models/constraints>` in the database table for
272 the model with ``model_name``.
273
274 ``RemoveConstraint``
275 --------------------
276
277 .. class:: RemoveConstraint(model_name, name)
278
279 Removes the constraint named ``name`` from the model with ``model_name``.
280
281 ``AlterConstraint``
282 -------------------
283
284 .. versionadded:: 5.2
285
286 .. class:: AlterConstraint(model_name, name, constraint)
287
288 Alters the constraint named ``name`` of the model with ``model_name`` with the
289 new ``constraint`` without affecting the database.
290
291 Special Operations
292 ==================
293
294 ``RunSQL``
295 ----------
296
297 .. class:: RunSQL(sql, reverse_sql=None, state_operations=None, hints=None, elidable=False)
298
299 Allows running of arbitrary SQL on the database - useful for more advanced
300 features of database backends that Django doesn't support directly.
301
302 ``sql``, and ``reverse_sql`` if provided, should be strings of SQL to run on
303 the database. On most database backends (all but PostgreSQL), Django will
304 split the SQL into individual statements prior to executing them.
305
306 .. warning::
307
308 On PostgreSQL and SQLite, only use ``BEGIN`` or ``COMMIT`` in your SQL in
309 :ref:`non-atomic migrations <non-atomic-migrations>`, to avoid breaking
310 Django's transaction state.
311
312 You can also pass a list of strings or 2-tuples. The latter is used for passing
313 queries and parameters in the same way as :ref:`cursor.execute()
314 <executing-custom-sql>`. These three operations are equivalent::
315
316 migrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")
317 migrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])
318 migrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])])
319
320 If you want to include literal percent signs in the query, you have to double
321 them if you are passing parameters.
322
323 The ``reverse_sql`` queries are executed when the migration is unapplied. They
324 should undo what is done by the ``sql`` queries. For example, to undo the above
325 insertion with a deletion::
326
327 migrations.RunSQL(
328 sql=[("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])],
329 reverse_sql=[("DELETE FROM musician where name=%s;", ["Reinhardt"])],
330 )
331
332 If ``reverse_sql`` is ``None`` (the default), the ``RunSQL`` operation is
333 irreversible.
334
335 The ``state_operations`` argument allows you to supply operations that are
336 equivalent to the SQL in terms of project state. For example, if you are
337 manually creating a column, you should pass in a list containing an ``AddField``
338 operation here so that the autodetector still has an up-to-date state of the
339 model. If you don't, when you next run ``makemigrations``, it won't see any
340 operation that adds that field and so will try to run it again. For example::
341
342 migrations.RunSQL(
343 "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",
344 state_operations=[
345 migrations.AddField(
346 "musician",
347 "name",
348 models.CharField(max_length=255),
349 ),
350 ],
351 )
352
353 The optional ``hints`` argument will be passed as ``**hints`` to the
354 :meth:`allow_migrate` method of database routers to assist them in making
355 routing decisions. See :ref:`topics-db-multi-db-hints` for more details on
356 database hints.
357
358 The optional ``elidable`` argument determines whether or not the operation will
359 be removed (elided) when :ref:`squashing migrations <migration-squashing>`.
360
361 .. attribute:: RunSQL.noop
362
363 Pass the ``RunSQL.noop`` attribute to ``sql`` or ``reverse_sql`` when you
364 want the operation not to do anything in the given direction. This is
365 especially useful in making the operation reversible.
366
367 ``RunPython``
368 -------------
369
370 .. class:: RunPython(code, reverse_code=None, atomic=None, hints=None, elidable=False)
371
372 Runs custom Python code in a historical context. ``code`` (and ``reverse_code``
373 if supplied) should be callable objects that accept two arguments; the first is
374 an instance of ``django.apps.registry.Apps`` containing historical models that
375 match the operation's place in the project history, and the second is an
376 instance of :class:`SchemaEditor
377 <django.db.backends.base.schema.BaseDatabaseSchemaEditor>`.
378
379 The ``reverse_code`` argument is called when unapplying migrations. This
380 callable should undo what is done in the ``code`` callable so that the
381 migration is reversible. If ``reverse_code`` is ``None`` (the default), the
382 ``RunPython`` operation is irreversible.
383
384 The optional ``hints`` argument will be passed as ``**hints`` to the
385 :meth:`allow_migrate` method of database routers to assist them in making a
386 routing decision. See :ref:`topics-db-multi-db-hints` for more details on
387 database hints.
388
389 The optional ``elidable`` argument determines whether or not the operation will
390 be removed (elided) when :ref:`squashing migrations <migration-squashing>`.
391
392 You are advised to write the code as a separate function above the ``Migration``
393 class in the migration file, and pass it to ``RunPython``. Here's an example of
394 using ``RunPython`` to create some initial objects on a ``Country`` model::
395
396 from django.db import migrations
397
398
399 def forwards_func(apps, schema_editor):
400 # We get the model from the versioned app registry;
401 # if we directly import it, it'll be the wrong version
402 Country = apps.get_model("myapp", "Country")
403 db_alias = schema_editor.connection.alias
404 Country.objects.using(db_alias).bulk_create(
405 [
406 Country(name="USA", code="us"),
407 Country(name="France", code="fr"),
408 ]
409 )
410
411
412 def reverse_func(apps, schema_editor):
413 # forwards_func() creates two Country instances,
414 # so reverse_func() should delete them.
415 Country = apps.get_model("myapp", "Country")
416 db_alias = schema_editor.connection.alias
417 Country.objects.using(db_alias).filter(name="USA", code="us").delete()
418 Country.objects.using(db_alias).filter(name="France", code="fr").delete()
419
420
421 class Migration(migrations.Migration):
422 dependencies = []
423
424 operations = [
425 migrations.RunPython(forwards_func, reverse_func),
426 ]
427
428 This is generally the operation you would use to create
429 :ref:`data migrations <data-migrations>`, run
430 custom data updates and alterations, and anything else you need access to an
431 ORM and/or Python code for.
432
433 Much like :class:`RunSQL`, ensure that if you change schema inside here you're
434 either doing it outside the scope of the Django model system (e.g. triggers)
435 or that you use :class:`SeparateDatabaseAndState` to add in operations that will
436 reflect your changes to the model state - otherwise, the versioned ORM and
437 the autodetector will stop working correctly.
438
439 By default, ``RunPython`` will run its contents inside a transaction on
440 databases that do not support DDL transactions (for example, MySQL and
441 Oracle). This should be safe, but may cause a crash if you attempt to use
442 the ``schema_editor`` provided on these backends; in this case, pass
443 ``atomic=False`` to the ``RunPython`` operation.
444
445 On databases that do support DDL transactions (SQLite and PostgreSQL),
446 ``RunPython`` operations do not have any transactions automatically added
447 besides the transactions created for each migration. Thus, on PostgreSQL, for
448 example, you should avoid combining schema changes and ``RunPython`` operations
449 in the same migration or you may hit errors like ``OperationalError: cannot
450 ALTER TABLE "mytable" because it has pending trigger events``.
451
452 If you have a different database and aren't sure if it supports DDL
453 transactions, check the ``django.db.connection.features.can_rollback_ddl``
454 attribute.
455
456 If the ``RunPython`` operation is part of a :ref:`non-atomic migration
457 <non-atomic-migrations>`, the operation will only be executed in a transaction
458 if ``atomic=True`` is passed to the ``RunPython`` operation.
459
460 .. warning::
461
462 ``RunPython`` does not magically alter the connection of the models for you;
463 any model methods you call will go to the default database unless you
464 give them the current database alias (available from
465 ``schema_editor.connection.alias``, where ``schema_editor`` is the second
466 argument to your function).
467
468 .. staticmethod:: RunPython.noop
469
470 Pass the ``RunPython.noop`` method to ``code`` or ``reverse_code`` when
471 you want the operation not to do anything in the given direction. This is
472 especially useful in making the operation reversible.
473
474 ``SeparateDatabaseAndState``
475 ----------------------------
476
477 .. class:: SeparateDatabaseAndState(database_operations=None, state_operations=None)
478
479 A highly specialized operation that lets you mix and match the database
480 (schema-changing) and state (autodetector-powering) aspects of operations.
481
482 It accepts two lists of operations. When asked to apply state, it will use the
483 ``state_operations`` list (this is a generalized version of :class:`RunSQL`'s
484 ``state_operations`` argument). When asked to apply changes to the database, it
485 will use the ``database_operations`` list.
486
487 If the actual state of the database and Django's view of the state get out of
488 sync, this can break the migration framework, even leading to data loss. It's
489 worth exercising caution and checking your database and state operations
490 carefully. You can use :djadmin:`sqlmigrate` and :djadmin:`dbshell` to check
491 your database operations. You can use :djadmin:`makemigrations`, especially
492 with :option:`--dry-run<makemigrations --dry-run>`, to check your state
493 operations.
494
495 For an example using ``SeparateDatabaseAndState``, see
496 :ref:`changing-a-manytomanyfield-to-use-a-through-model`.
497
498 Operation category
499 ==================
500
501 .. versionadded:: 5.1
502
503 .. currentmodule:: django.db.migrations.operations.base
504
505 .. class:: OperationCategory
506
507 Categories of migration operation used by the :djadmin:`makemigrations`
508 command to display meaningful symbols.
509
510 .. attribute:: ADDITION
511
512 *Symbol*: ``+``
513
514 .. attribute:: REMOVAL
515
516 *Symbol*: ``-``
517
518 .. attribute:: ALTERATION
519
520 *Symbol*: ``~``
521
522 .. attribute:: PYTHON
523
524 *Symbol*: ``p``
525
526 .. attribute:: SQL
527
528 *Symbol*: ``s``
529
530 .. attribute:: MIXED
531
532 *Symbol*: ``?``
533
534 .. _writing-your-own-migration-operation:
535
536 Writing your own
537 ================
538
539 Operations have a relatively simple API, and they're designed so that you can
540 easily write your own to supplement the built-in Django ones. The basic
541 structure of an ``Operation`` looks like this::
542
543 from django.db.migrations.operations.base import Operation
544
545
546 class MyCustomOperation(Operation):
547 # If this is False, it means that this operation will be ignored by
548 # sqlmigrate; if true, it will be run and the SQL collected for its output.
549 reduces_to_sql = False
550
551 # If this is False, Django will refuse to reverse past this operation.
552 reversible = False
553
554 # This categorizes the operation. The corresponding symbol will be
555 # displayed by the makemigrations command.
556 category = OperationCategory.ADDITION
557
558 def __init__(self, arg1, arg2):
559 # Operations are usually instantiated with arguments in migration
560 # files. Store the values of them on self for later use.
561 pass
562
563 def state_forwards(self, app_label, state):
564 # The Operation should take the 'state' parameter (an instance of
565 # django.db.migrations.state.ProjectState) and mutate it to match
566 # any schema changes that have occurred.
567 pass
568
569 def database_forwards(self, app_label, schema_editor, from_state, to_state):
570 # The Operation should use schema_editor to apply any changes it
571 # wants to make to the database.
572 pass
573
574 def database_backwards(self, app_label, schema_editor, from_state, to_state):
575 # If reversible is True, this is called when the operation is reversed.
576 pass
577
578 def describe(self):
579 # This is used to describe what the operation does.
580 return "Custom Operation"
581
582 @property
583 def migration_name_fragment(self):
584 # Optional. A filename part suitable for automatically naming a
585 # migration containing this operation, or None if not applicable.
586 return "custom_operation_%s_%s" % (self.arg1, self.arg2)
587
588 You can take this template and work from it, though we suggest looking at the
589 built-in Django operations in ``django.db.migrations.operations`` - they cover
590 a lot of the example usage of semi-internal aspects of the migration framework
591 like ``ProjectState`` and the patterns used to get historical models, as well
592 as ``ModelState`` and the patterns used to mutate historical models in
593 ``state_forwards()``.
594
595 Some things to note:
596
597 * You don't need to learn too much about ``ProjectState`` to write migrations;
598 just know that it has an ``apps`` property that gives access to an app
599 registry (which you can then call ``get_model`` on).
600
601 * ``database_forwards`` and ``database_backwards`` both get two states passed
602 to them; these represent the difference the ``state_forwards`` method would
603 have applied, but are given to you for convenience and speed reasons.
604
605 * If you want to work with model classes or model instances from the
606 ``from_state`` argument in ``database_forwards()`` or
607 ``database_backwards()``, you must render model states using the
608 ``clear_delayed_apps_cache()`` method to make related models available::
609
610 def database_forwards(self, app_label, schema_editor, from_state, to_state):
611 # This operation should have access to all models. Ensure that all models are
612 # reloaded in case any are delayed.
613 from_state.clear_delayed_apps_cache()
614 ...
615
616 * ``to_state`` in the database_backwards method is the *older* state; that is,
617 the one that will be the current state once the migration has finished reversing.
618
619 * You might see implementations of ``references_model`` on the built-in
620 operations; this is part of the autodetection code and does not matter for
621 custom operations.
622
623 .. warning::
624
625 For performance reasons, the :class:`~django.db.models.Field` instances in
626 ``ModelState.fields`` are reused across migrations. You must never change
627 the attributes on these instances. If you need to mutate a field in
628 ``state_forwards()``, you must remove the old instance from
629 ``ModelState.fields`` and add a new instance in its place. The same is true
630 for the :class:`~django.db.models.Manager` instances in
631 ``ModelState.managers``.
632
633 As an example, let's make an operation that loads PostgreSQL extensions (which
634 contain some of PostgreSQL's more exciting features). Since there's no model
635 state changes, all it does is run one command::
636
637 from django.db.migrations.operations.base import Operation
638
639
640 class LoadExtension(Operation):
641 reversible = True
642
643 def __init__(self, name):
644 self.name = name
645
646 def state_forwards(self, app_label, state):
647 pass
648
649 def database_forwards(self, app_label, schema_editor, from_state, to_state):
650 schema_editor.execute("CREATE EXTENSION IF NOT EXISTS %s" % self.name)
651
652 def database_backwards(self, app_label, schema_editor, from_state, to_state):
653 schema_editor.execute("DROP EXTENSION %s" % self.name)
654
655 def describe(self):
656 return "Creates extension %s" % self.name
657
658 @property
659 def migration_name_fragment(self):
660 return "create_extension_%s" % self.name