django/docs/topics/migrations.txt

==========
Migrations
==========

.. module:: django.db.migrations
   :synopsis: Schema migration support for Django models

.. versionadded:: 1.7

Migrations are Django's way of propagating changes you make to your models
(adding a field, deleting a model, etc.) into your database schema. They're
designed to be mostly automatic, but you'll need to know when to make
migrations, when to run them, and the common problems you might run into.

A Brief History
---------------

Prior to version 1.7, Django only supported adding new models to the
database; it was not possible to alter or remove existing models via the
``syncdb`` command (the predecessor to ``migrate``).

Third-party tools, most notably `South <http://south.aeracode.org>`_,
provided support for these additional types of change, but it was considered
important enough that support was brought into core Django.

Two Commands
------------

There are two commands which you will use to interact with migrations
and Django's handling of database schema:

* :djadmin:`migrate`, which is responsible for applying migrations, as well as
  unapplying and listing their status.
  
* :djadmin:`makemigrations`, which is responsible for creating new migrations
  based on the changes you have made to your models.

It's worth noting that migrations are created and run on a per-app basis.
In particular, it's possible to have apps that *do not use migrations* (these
are referred to as "unmigrated" apps) - these apps will instead mimic the
legacy behaviour of just adding new models.

You should think of migrations as a version control system for your database
schema. ``makemigrations`` is responsible for packaging up your model changes
into individual migration files - analagous to commits - and ``migrate`` is
responsible for applying those to your database.

The migration files for each app live in a "migrations" directory inside
of that app, and are designed to be committed to, and distributed as part
of, its codebase. You should be making them once on your development machine
and then running the same migrations on your colleagues' machines, your
staging machines and eventually your production machines.

Migrations will run the same way every time and produce consistent results,
meaning that what you see in development and staging is exactly what will
happen in production - no unexpected surprises.

Backend Support
---------------

Migrations are supported on all backends that Django ships with, as well
as any third-party backends if they have programmed in support for schema
alteration (done via the SchemaEditor class).

However, some databases are more capable than others when it comes to
schema migrations; some of the caveats are covered below.

PostgreSQL
~~~~~~~~~~

PostgreSQL is the most capable of all the databases here in terms of schema
support; the only caveat is that adding columns with default values will
lock a table for a time proportional to the number of rows in it.

For this reason, it's recommended you always create new columns with
``null=True``, as this way they will be added immediately.

MySQL
~~~~~

MySQL lacks support for transactions around schema alteration operations,
meaning that if a migration fails to apply you will have to manually unpick
the changes in order to try again (it's impossible to roll back to an
earlier point).

In addition, MySQL will lock tables for almost every schema operation and
generally takes a time proportional to the number of rows in the table to
add or remove columns. On slower hardware this can be worse than a minute
per million rows - adding a few columns to a table with just a few million
rows could lock your site up for over ten minutes.

Finally, MySQL has reasonably small limits on name lengths for columns, tables
and indexes, as well as a limit on the combined size of all columns an index
covers. This means that indexes that are possible on other backends will
fail to be created under MySQL.

SQLite
~~~~~~

SQLite has very little built-in schema alteration support, and so Django
attempts to emulate it by:

* Creating a new table with the new schema
* Copying the data across
* Dropping the old table
* Renaming the new table to match the original name

This process generally works well, but it can be slow and occasionally
buggy. It is not recommended that you run and migrate SQLite in a
production environment unless you are very aware of the risks and
its limitations; the support Django ships with is designed to allow
developers to use SQLite on their local machines to develop less complex
Django projects without the need for a full database.