mirror of https://github.com/django/django.git
114 lines
4.5 KiB
Plaintext
114 lines
4.5 KiB
Plaintext
==========
|
|
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.
|