Migration files are composed of one or more Operations, objects that\ndeclaratively record what the migration should do to your database.
Django also uses these Operation objects to work out what your models\nlooked like historically, and to calculate what changes you’ve made to\nyour models since the last migration so it can automatically write\nyour migrations; that’s why they’re declarative, as it means Django can\neasily load them all into memory and run through them without touching\nthe database to work out what your project should look like.
There are also more specialized Operation objects which are for things like\ndata migrations and for advanced manual database\nmanipulation. You can also write your own Operation classes if you want\nto encapsulate a custom change you commonly make.
If you need an empty migration file to write your own Operation objects\ninto, use python manage.py makemigrations --empty yourappname, but be aware\nthat manually adding schema-altering operations can confuse the migration\nautodetector and make resulting runs of makemigrations output\nincorrect code.
All of the core Django operations are available from the\ndjango.db.migrations.operations module.
For introductory material, see the migrations topic guide.
\nCreateModelLink to this heading#Creates a new model in the project history and a corresponding table in the\ndatabase to match it.
\nname is the model name, as would be written in the models.py file.
fields is a list of 2-tuples of (field_name, field_instance).\nThe field instance should be an unbound field (so just\nmodels.CharField(...), rather than a field taken from another model).
options is an optional dictionary of values from the model’s Meta class.
bases is an optional list of other classes to have this model inherit from;\nit can contain both class objects as well as strings in the format\n"appname.ModelName" if you want to depend on another model (so you inherit\nfrom the historical version). If it’s not supplied, it defaults to inheriting\nfrom the standard models.Model.
managers takes a list of 2-tuples of (manager_name, manager_instance).\nThe first manager in the list will be the default manager for this model during\nmigrations.
DeleteModelLink to this heading#Deletes the model from the project history and its table from the database.
\nRenameModelLink to this heading#Renames the model from an old name to a new one.
\nYou may have to manually add\nthis if you change the model’s name and quite a few of its fields at once; to\nthe autodetector, this will look like you deleted a model with the old name\nand added a new one with a different name, and the migration it creates will\nlose any data in the old table.
\nAlterModelTableLink to this heading#Changes the model’s table name (the db_table\noption on the Meta subclass).
AlterUniqueTogetherLink to this heading#Changes the model’s set of unique constraints (the\nunique_together option on the Meta\nsubclass).
AlterIndexTogetherLink to this heading#Changes the model’s set of custom indexes (the\nindex_together option on the Meta\nsubclass).
AlterOrderWithRespectToLink to this heading#Makes or deletes the _order column needed for the\norder_with_respect_to option on the Meta\nsubclass.
AlterModelOptionsLink to this heading#Stores changes to miscellaneous model options (settings on a model’s Meta)\nlike permissions and verbose_name. Does not affect the database, but\npersists these changes for RunPython instances to use. options\nshould be a dictionary mapping option names to values.
AlterModelManagersLink to this heading#Alters the managers that are available during migrations.
\nAddFieldLink to this heading#Adds a field to a model. model_name is the model’s name, name is\nthe field’s name, and field is an unbound Field instance (the thing\nyou would put in the field declaration in models.py - for example,\nmodels.IntegerField(null=True).
The preserve_default argument indicates whether the field’s default\nvalue is permanent and should be baked into the project state (True),\nor if it is temporary and just for this migration (False) - usually\nbecause the migration is adding a non-nullable field to a table and needs\na default value to put into existing rows. It does not affect the behavior\nof setting defaults in the database directly - Django never sets database\ndefaults and always applies them in the Django ORM code.
RemoveFieldLink to this heading#Removes a field from a model.
\nBear in mind that when reversed, this is actually adding a field to a model.\nThe operation is reversible (apart from any data loss, which of course is\nirreversible) if the field is nullable or if it has a default value that can be\nused to populate the recreated column. If the field is not nullable and does\nnot have a default value, the operation is irreversible.
\nAlterFieldLink to this heading#Alters a field’s definition, including changes to its type,\nnull, unique,\ndb_column and other field attributes.
The preserve_default argument indicates whether the field’s default\nvalue is permanent and should be baked into the project state (True),\nor if it is temporary and just for this migration (False) - usually\nbecause the migration is altering a nullable field to a non-nullable one and\nneeds a default value to put into existing rows. It does not affect the\nbehavior of setting defaults in the database directly - Django never sets\ndatabase defaults and always applies them in the Django ORM code.
Note that not all changes are possible on all databases - for example, you\ncannot change a text-type field like models.TextField() into a number-type\nfield like models.IntegerField() on most databases.
RenameFieldLink to this heading#Changes a field’s name (and, unless db_column\nis set, its column name).
AddIndexLink to this heading#Creates an index in the database table for the model with model_name.\nindex is an instance of the Index class.
RemoveIndexLink to this heading#Removes the index named name from the model with model_name.
AddConstraintLink to this heading#Creates a constraint in the database table for\nthe model with model_name.
RemoveConstraintLink to this heading#Removes the constraint named name from the model with model_name.
RunSQLLink to this heading#Allows running of arbitrary SQL on the database - useful for more advanced\nfeatures of database backends that Django doesn’t support directly.
\nsql, and reverse_sql if provided, should be strings of SQL to run on\nthe database. On most database backends (all but PostgreSQL), Django will\nsplit the SQL into individual statements prior to executing them.
You can also pass a list of strings or 2-tuples. The latter is used for passing\nqueries and parameters in the same way as cursor.execute(). These three operations are equivalent:
\nmigrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])])\nIf you want to include literal percent signs in the query, you have to double\nthem if you are passing parameters.
\nThe reverse_sql queries are executed when the migration is unapplied. They\nshould undo what is done by the sql queries. For example, to undo the above\ninsertion with a deletion:
migrations.RunSQL(\n sql=[("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])],\n reverse_sql=[("DELETE FROM musician where name=%s;", ['Reinhardt'])],\n)\nIf reverse_sql is None (the default), the RunSQL operation is\nirreversible.
The state_operations argument allows you to supply operations that are\nequivalent to the SQL in terms of project state. For example, if you are\nmanually creating a column, you should pass in a list containing an AddField\noperation here so that the autodetector still has an up-to-date state of the\nmodel. If you don’t, when you next run makemigrations, it won’t see any\noperation that adds that field and so will try to run it again. For example:
migrations.RunSQL(\n "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",\n state_operations=[\n migrations.AddField(\n 'musician',\n 'name',\n models.CharField(max_length=255),\n ),\n ],\n)\nThe optional hints argument will be passed as **hints to the\nallow_migrate() method of database routers to assist them in making\nrouting decisions. See Hints for more details on\ndatabase hints.
The optional elidable argument determines whether or not the operation will\nbe removed (elided) when squashing migrations.
Pass the RunSQL.noop attribute to sql or reverse_sql when you\nwant the operation not to do anything in the given direction. This is\nespecially useful in making the operation reversible.
RunPythonLink to this heading#Runs custom Python code in a historical context. code (and reverse_code\nif supplied) should be callable objects that accept two arguments; the first is\nan instance of django.apps.registry.Apps containing historical models that\nmatch the operation’s place in the project history, and the second is an\ninstance of SchemaEditor.
The reverse_code argument is called when unapplying migrations. This\ncallable should undo what is done in the code callable so that the\nmigration is reversible. If reverse_code is None (the default), the\nRunPython operation is irreversible.
The optional hints argument will be passed as **hints to the\nallow_migrate() method of database routers to assist them in making a\nrouting decision. See Hints for more details on\ndatabase hints.
The optional elidable argument determines whether or not the operation will\nbe removed (elided) when squashing migrations.
You are advised to write the code as a separate function above the Migration\nclass in the migration file, and pass it to RunPython. Here’s an example of\nusing RunPython to create some initial objects on a Country model:
from django.db import migrations\n\ndef forwards_func(apps, schema_editor):\n # We get the model from the versioned app registry;\n # if we directly import it, it'll be the wrong version\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).bulk_create([\n Country(name="USA", code="us"),\n Country(name="France", code="fr"),\n ])\n\ndef reverse_func(apps, schema_editor):\n # forwards_func() creates two Country instances,\n # so reverse_func() should delete them.\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).filter(name="USA", code="us").delete()\n Country.objects.using(db_alias).filter(name="France", code="fr").delete()\n\nclass Migration(migrations.Migration):\n\n dependencies = []\n\n operations = [\n migrations.RunPython(forwards_func, reverse_func),\n ]\nThis is generally the operation you would use to create\ndata migrations, run\ncustom data updates and alterations, and anything else you need access to an\nORM and/or Python code for.
\nMuch like RunSQL, ensure that if you change schema inside here you’re\neither doing it outside the scope of the Django model system (e.g. triggers)\nor that you use SeparateDatabaseAndState to add in operations that will\nreflect your changes to the model state - otherwise, the versioned ORM and\nthe autodetector will stop working correctly.
By default, RunPython will run its contents inside a transaction on\ndatabases that do not support DDL transactions (for example, MySQL and\nOracle). This should be safe, but may cause a crash if you attempt to use\nthe schema_editor provided on these backends; in this case, pass\natomic=False to the RunPython operation.
On databases that do support DDL transactions (SQLite and PostgreSQL),\nRunPython operations do not have any transactions automatically added\nbesides the transactions created for each migration. Thus, on PostgreSQL, for\nexample, you should avoid combining schema changes and RunPython operations\nin the same migration or you may hit errors like OperationalError: cannot\nALTER TABLE "mytable" because it has pending trigger events.
If you have a different database and aren’t sure if it supports DDL\ntransactions, check the django.db.connection.features.can_rollback_ddl\nattribute.
If the RunPython operation is part of a non-atomic migration, the operation will only be executed in a transaction\nif atomic=True is passed to the RunPython operation.
Pass the RunPython.noop method to code or reverse_code when\nyou want the operation not to do anything in the given direction. This is\nespecially useful in making the operation reversible.
SeparateDatabaseAndStateLink to this heading#A highly specialized operation that lets you mix and match the database\n(schema-changing) and state (autodetector-powering) aspects of operations.
\nIt accepts two lists of operations. When asked to apply state, it will use the\nstate_operations list (this is a generalized version of RunSQL’s\nstate_operations argument). When asked to apply changes to the database, it\nwill use the database_operations list.
If the actual state of the database and Django’s view of the state get out of\nsync, this can break the migration framework, even leading to data loss. It’s\nworth exercising caution and checking your database and state operations\ncarefully. You can use sqlmigrate and dbshell to check\nyour database operations. You can use makemigrations, especially\nwith --dry-run, to check your state\noperations.
For an example using SeparateDatabaseAndState, see\nChanging a ManyToManyField to use a through model.
Operations have a relatively simple API, and they’re designed so that you can\neasily write your own to supplement the built-in Django ones. The basic\nstructure of an Operation looks like this:
from django.db.migrations.operations.base import Operation\n\nclass MyCustomOperation(Operation):\n\n # If this is False, it means that this operation will be ignored by\n # sqlmigrate; if true, it will be run and the SQL collected for its output.\n reduces_to_sql = False\n\n # If this is False, Django will refuse to reverse past this operation.\n reversible = False\n\n def __init__(self, arg1, arg2):\n # Operations are usually instantiated with arguments in migration\n # files. Store the values of them on self for later use.\n pass\n\n def state_forwards(self, app_label, state):\n # The Operation should take the 'state' parameter (an instance of\n # django.db.migrations.state.ProjectState) and mutate it to match\n # any schema changes that have occurred.\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # The Operation should use schema_editor to apply any changes it\n # wants to make to the database.\n pass\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n # If reversible is True, this is called when the operation is reversed.\n pass\n\n def describe(self):\n # This is used to describe what the operation does in console output.\n return "Custom Operation"\nYou can take this template and work from it, though we suggest looking at the\nbuilt-in Django operations in django.db.migrations.operations - they cover\na lot of the example usage of semi-internal aspects of the migration framework\nlike ProjectState and the patterns used to get historical models, as well\nas ModelState and the patterns used to mutate historical models in\nstate_forwards().
Some things to note:
\nYou don’t need to learn too much about ProjectState to write migrations;\njust know that it has an apps property that gives access to an app\nregistry (which you can then call get_model on).
database_forwards and database_backwards both get two states passed\nto them; these represent the difference the state_forwards method would\nhave applied, but are given to you for convenience and speed reasons.
If you want to work with model classes or model instances from the\nfrom_state argument in database_forwards() or\ndatabase_backwards(), you must render model states using the\nclear_delayed_apps_cache() method to make related models available:
def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # This operation should have access to all models. Ensure that all models are\n # reloaded in case any are delayed.\n from_state.clear_delayed_apps_cache()\n ...\nto_state in the database_backwards method is the older state; that is,\nthe one that will be the current state once the migration has finished reversing.
You might see implementations of references_model on the built-in\noperations; this is part of the autodetection code and does not matter for\ncustom operations.
As an example, let’s make an operation that loads PostgreSQL extensions (which\ncontain some of PostgreSQL’s more exciting features). Since there’s no model\nstate changes, all it does is run one command:
\nfrom django.db.migrations.operations.base import Operation\n\nclass LoadExtension(Operation):\n\n reversible = True\n\n def __init__(self, name):\n self.name = name\n\n def state_forwards(self, app_label, state):\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("CREATE EXTENSION IF NOT EXISTS %s" % self.name)\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("DROP EXTENSION %s" % self.name)\n\n def describe(self):\n return "Creates extension %s" % self.name\n