Small start to migrations documentation

2 files changed, 114 insertions, 0 deletions

diff --git a/docs/topics/index.txt b/docs/topics/index.txt
index f8f60b2953..b248e10268 100644
--- a/docs/topics/index.txt
+++ b/docs/topics/index.txt
@@ -12,6 +12,7 @@ Introductions to all the key parts of Django you'll need to know:
    forms/index
    templates
    class-based-views/index
+   migrations
    files
    testing/index
    auth/index
diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt
new file mode 100644
index 0000000000..e24a7ce085
--- /dev/null
+++ b/docs/topics/migrations.txt
@@ -0,0 +1,113 @@
+==========
+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.