Migration Operations

Migration files are composed of one or more Operations, objects thatdeclaratively record what the migration should do to your database.

Django also uses these Operation objects to work out what your modelslooked like historically, and to calculate what changes you’ve made toyour models since the last migration so it can automatically writeyour migrations; that’s why they’re declarative, as it means Django caneasily load them all into memory and run through them without touchingthe database to work out what your project should look like.

There are also more specialized Operation objects which are for things likedata migrations and for advanced manual databasemanipulation. You can also write your own Operation classes if you wantto encapsulate a custom change you commonly make.

If you need an empty migration file to write your own Operation objectsinto, use python manage.py makemigrations —empty yourappname, but be awarethat manually adding schema-altering operations can confuse the migrationautodetector and make resulting runs of makemigrations outputincorrect code.

All of the core Django operations are available from thedjango.db.migrations.operations module.

For introductory material, see the migrations topic guide.

Schema Operations

CreateModel

• class CreateModel(name, fields, options=None, bases=None, managers=None)
• Creates a new model in the project history and a corresponding table in thedatabase to match it.

name 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).The field instance should be an unbound field (so justmodels.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;it can contain both class objects as well as strings in the format"appname.ModelName" if you want to depend on another model (so you inheritfrom the historical version). If it’s not supplied, it defaults to inheritingfrom the standard models.Model.

managers takes a list of 2-tuples of (manager_name, manager_instance).The first manager in the list will be the default manager for this model duringmigrations.

DeleteModel

• class DeleteModel(name)
• Deletes the model from the project history and its table from the database.

RenameModel

• class RenameModel(old_name, new_name)
• Renames the model from an old name to a new one.

You may have to manually addthis if you change the model’s name and quite a few of its fields at once; tothe autodetector, this will look like you deleted a model with the old nameand added a new one with a different name, and the migration it creates willlose any data in the old table.

AlterModelTable

• class AlterModelTable(name, table)
• Changes the model’s table name (the db_tableoption on the Meta subclass).

AlterUniqueTogether

• class AlterUniqueTogether(name, unique_together)
• Changes the model’s set of unique constraints (theunique_together option on the Metasubclass).

AlterIndexTogether

• class AlterIndexTogether(name, index_together)
• Changes the model’s set of custom indexes (theindex_together option on the Metasubclass).

AlterOrderWithRespectTo

• class AlterOrderWithRespectTo(name, order_with_respect_to)
• Makes or deletes the _order column needed for theorder_with_respect_to option on the Metasubclass.

AlterModelOptions

• class AlterModelOptions(name, options)
• Stores changes to miscellaneous model options (settings on a model’s Meta)like permissions and verbose_name. Does not affect the database, butpersists these changes for RunPython instances to use. optionsshould be a dictionary mapping option names to values.

AlterModelManagers

• class AlterModelManagers(name, managers)
• Alters the managers that are available during migrations.

AddField

• class AddField(model_name, name, field, preserve_default=True)
• Adds a field to a model. model_name is the model’s name, name isthe field’s name, and field is an unbound Field instance (the thingyou would put in the field declaration in models.py - for example,models.IntegerField(null=True).

The preserve_default argument indicates whether the field’s defaultvalue is permanent and should be baked into the project state (True),or if it is temporary and just for this migration (False) - usuallybecause the migration is adding a non-nullable field to a table and needsa default value to put into existing rows. It does not affect the behaviorof setting defaults in the database directly - Django never sets databasedefaults and always applies them in the Django ORM code.

RemoveField

• class RemoveField(model_name, name)
• Removes a field from a model.

Bear in mind that when reversed, this is actually adding a field to a model.The operation is reversible (apart from any data loss, which of course isirreversible) if the field is nullable or if it has a default value that can beused to populate the recreated column. If the field is not nullable and doesnot have a default value, the operation is irreversible.

AlterField

• class AlterField(model_name, name, field, preserve_default=True)
• Alters a field’s definition, including changes to its type,null, unique,db_column and other field attributes.

The preserve_default argument indicates whether the field’s defaultvalue is permanent and should be baked into the project state (True),or if it is temporary and just for this migration (False) - usuallybecause the migration is altering a nullable field to a non-nullable one andneeds a default value to put into existing rows. It does not affect thebehavior of setting defaults in the database directly - Django never setsdatabase defaults and always applies them in the Django ORM code.

Note that not all changes are possible on all databases - for example, youcannot change a text-type field like models.TextField() into a number-typefield like models.IntegerField() on most databases.

RenameField

• class RenameField(model_name, old_name, new_name)
• Changes a field’s name (and, unless db_columnis set, its column name).

AddIndex

• class AddIndex(model_name, index)
• Creates an index in the database table for the model with model_name.index is an instance of the Index class.

RemoveIndex

• class RemoveIndex(model_name, name)
• Removes the index named name from the model with model_name.

AddConstraint

• class AddConstraint(model_name, constraint)
• New in Django 2.2:

Creates a constraint in the database table forthe model with model_name.

RemoveConstraint

• class RemoveConstraint(model_name, name)
• New in Django 2.2:

Removes the constraint named name from the model with model_name.

Special Operations

RunSQL

• class RunSQL(sql, reverse_sql=None, state_operations=None, hints=None, elidable=False)
• Allows running of arbitrary SQL on the database - useful for more advancedfeatures of database backends that Django doesn’t support directly, likepartial indexes.

sql, and reverse_sql if provided, should be strings of SQL to run onthe database. On most database backends (all but PostgreSQL), Django willsplit 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 passingqueries and parameters in the same way as cursor.execute(). These three operations are equivalent:

migrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")
migrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])
migrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])])

If you want to include literal percent signs in the query, you have to doublethem if you are passing parameters.

The reverse_sql queries are executed when the migration is unapplied, soyou can reverse the changes done in the forwards queries:

migrations.RunSQL(
    [("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])],
    [("DELETE FROM musician where name=%s;", ['Reinhardt'])],
)

The state_operations argument is so you can supply operations that areequivalent to the SQL in terms of project state; for example, if you aremanually creating a column, you should pass in a list containing an AddFieldoperation here so that the autodetector still has an up-to-date state of themodel (otherwise, when you next run makemigrations, it won’t see anyoperation that adds that field and so will try to run it again). For example:

migrations.RunSQL(
    "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",
    state_operations=[
        migrations.AddField(
            'musician',
            'name',
            models.CharField(max_length=255),
        ),
    ],
)

The optional hints argument will be passed as **hints to theallow_migrate() method of database routers to assist them in makingrouting decisions. See Hints for more details ondatabase hints.

The optional elidable argument determines whether or not the operation willbe removed (elided) when squashing migrations.

• RunSQL.noop
• Pass the RunSQL.noop attribute to sql or reverse_sql when youwant the operation not to do anything in the given direction. This isespecially useful in making the operation reversible.

RunPython

• class RunPython(code, reverse_code=None, atomic=None, hints=None, elidable=False)
• Runs custom Python code in a historical context. code (and reverse_codeif supplied) should be callable objects that accept two arguments; the first isan instance of django.apps.registry.Apps containing historical models thatmatch the operation’s place in the project history, and the second is aninstance of SchemaEditor.

The reverse_code argument is called when unapplying migrations. Thiscallable should undo what is done in the code callable so that themigration is reversible.

The optional hints argument will be passed as **hints to theallow_migrate() method of database routers to assist them in making arouting decision. See Hints for more details ondatabase hints.

The optional elidable argument determines whether or not the operation willbe removed (elided) when squashing migrations.

You are advised to write the code as a separate function above the Migrationclass in the migration file, and pass it to RunPython. Here’s an example ofusing RunPython to create some initial objects on a Country model:

from django.db import migrations
 
def forwards_func(apps, schema_editor):
    # We get the model from the versioned app registry;
    # if we directly import it, it'll be the wrong version
    Country = apps.get_model("myapp", "Country")
    db_alias = schema_editor.connection.alias
    Country.objects.using(db_alias).bulk_create([
        Country(name="USA", code="us"),
        Country(name="France", code="fr"),
    ])
 
def reverse_func(apps, schema_editor):
    # forwards_func() creates two Country instances,
    # so reverse_func() should delete them.
    Country = apps.get_model("myapp", "Country")
    db_alias = schema_editor.connection.alias
    Country.objects.using(db_alias).filter(name="USA", code="us").delete()
    Country.objects.using(db_alias).filter(name="France", code="fr").delete()
 
class Migration(migrations.Migration):
 
    dependencies = []
 
    operations = [
        migrations.RunPython(forwards_func, reverse_func),
    ]

This is generally the operation you would use to createdata migrations, runcustom data updates and alterations, and anything else you need access to anORM and/or Python code for.

If you’re upgrading from South, this is basically the South pattern as anoperation - one or two methods for forwards and backwards, with an ORM andschema operations available. Most of the time, you should be able to translatethe orm.Model or orm["appname", "Model"] references from South directlyinto apps.get_model("appname", "Model") references here and leave most ofthe rest of the code unchanged for data migrations. However, apps will onlyhave references to models in the current app unless migrations in other appsare added to the migration’s dependencies.

Much like RunSQL, ensure that if you change schema inside here you’reeither doing it outside the scope of the Django model system (e.g. triggers)or that you use SeparateDatabaseAndState to add in operations that willreflect your changes to the model state - otherwise, the versioned ORM andthe autodetector will stop working correctly.

By default, RunPython will run its contents inside a transaction ondatabases that do not support DDL transactions (for example, MySQL andOracle). This should be safe, but may cause a crash if you attempt to usethe schema_editor provided on these backends; in this case, passatomic=False to the RunPython operation.

On databases that do support DDL transactions (SQLite and PostgreSQL),RunPython operations do not have any transactions automatically addedbesides the transactions created for each migration. Thus, on PostgreSQL, forexample, you should avoid combining schema changes and RunPython operationsin the same migration or you may hit errors like OperationalError: cannotALTER TABLE "mytable" because it has pending trigger events.

If you have a different database and aren’t sure if it supports DDLtransactions, check the django.db.connection.features.can_rollback_ddlattribute.

If the RunPython operation is part of a non-atomic migration, the operation will only be executed in a transactionif atomic=True is passed to the RunPython operation.

Warning

RunPython does not magically alter the connection of the models for you;any model methods you call will go to the default database unless yougive them the current database alias (available fromschema_editor.connection.alias, where schema_editor is the secondargument to your function).

• static RunPython.noop()
• Pass the RunPython.noop method to code or reverse_code whenyou want the operation not to do anything in the given direction. This isespecially useful in making the operation reversible.

SeparateDatabaseAndState

• class SeparateDatabaseAndState(database_operations=None, state_operations=None)
• A highly specialized operation that let you mix and match the database(schema-changing) and state (autodetector-powering) aspects of operations.

It accepts two lists of operations, and when asked to apply state will use thestate list, and when asked to apply changes to the database will use the databaselist. Do not use this operation unless you’re very sure you know what you’re doing.

Writing your own

Operations have a relatively simple API, and they’re designed so that you caneasily write your own to supplement the built-in Django ones. The basicstructure of an Operation looks like this:

from django.db.migrations.operations.base import Operation
 
class MyCustomOperation(Operation):
 
    # If this is False, it means that this operation will be ignored by
    # sqlmigrate; if true, it will be run and the SQL collected for its output.
    reduces_to_sql = False
 
    # If this is False, Django will refuse to reverse past this operation.
    reversible = False
 
    def __init__(self, arg1, arg2):
        # Operations are usually instantiated with arguments in migration
        # files. Store the values of them on self for later use.
        pass
 
    def state_forwards(self, app_label, state):
        # The Operation should take the 'state' parameter (an instance of
        # django.db.migrations.state.ProjectState) and mutate it to match
        # any schema changes that have occurred.
        pass
 
    def database_forwards(self, app_label, schema_editor, from_state, to_state):
        # The Operation should use schema_editor to apply any changes it
        # wants to make to the database.
        pass
 
    def database_backwards(self, app_label, schema_editor, from_state, to_state):
        # If reversible is True, this is called when the operation is reversed.
        pass
 
    def describe(self):
        # This is used to describe what the operation does in console output.
        return "Custom Operation"

You can take this template and work from it, though we suggest looking at thebuilt-in Django operations in django.db.migrations.operations - they covera lot of the example usage of semi-internal aspects of the migration frameworklike ProjectState and the patterns used to get historical models, as wellas ModelState and the patterns used to mutate historical models instate_forwards().

Some things to note:

• You don’t need to learn too much about ProjectState to write migrations;just know that it has an apps property that gives access to an appregistry (which you can then call get_model on).

• database_forwards and database_backwards both get two states passedto them; these represent the difference the state_forwards method wouldhave applied, but are given to you for convenience and speed reasons.

• If you want to work with model classes or model instances from thefrom_state argument in database_forwards() ordatabase_backwards(), you must render model states using theclear_delayed_apps_cache() method to make related models available:

def database_forwards(self, app_label, schema_editor, from_state, to_state):
    # This operation should have access to all models. Ensure that all models are
    # reloaded in case any are delayed.
    from_state.clear_delayed_apps_cache()
    ...

• tostate in the database_backwards method is the _older state; that is,the one that will be the current state once the migration has finished reversing.

• You might see implementations of references_model on the built-inoperations; this is part of the autodetection code and does not matter forcustom operations.

Warning

For performance reasons, the Field instances inModelState.fields are reused across migrations. You must never changethe attributes on these instances. If you need to mutate a field instate_forwards(), you must remove the old instance fromModelState.fields and add a new instance in its place. The same is truefor the Manager instances inModelState.managers.

As an example, let’s make an operation that loads PostgreSQL extensions (whichcontain some of PostgreSQL’s more exciting features). Since there’s no modelstate changes, all it does is run one command:

from django.db.migrations.operations.base import Operation
 
class LoadExtension(Operation):
 
    reversible = True
 
    def __init__(self, name):
        self.name = name
 
    def state_forwards(self, app_label, state):
        pass
 
    def database_forwards(self, app_label, schema_editor, from_state, to_state):
        schema_editor.execute("CREATE EXTENSION IF NOT EXISTS %s" % self.name)
 
    def database_backwards(self, app_label, schema_editor, from_state, to_state):
        schema_editor.execute("DROP EXTENSION %s" % self.name)
 
    def describe(self):
        return "Creates extension %s" % self.name