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