Small start to migrations documentation

docs/index.txt

@@ -71,6 +71,9 @@ manipulating the data of your Web application. Learn more about it below:
   :doc:`Instance methods <ref/models/instances>` |
   :doc:`Accessing related objects <ref/models/relations>`
 
+* **Migrations:**
+  :doc:`Introduction to Migrations<topics/migrations>`
+
 * **Advanced:**
   :doc:`Managers <topics/db/managers>` |
   :doc:`Raw SQL <topics/db/sql>` |

docs/ref/django-admin.txt

@@ -572,6 +572,48 @@ Use the ``--keep-pot`` option to prevent django from deleting the temporary
 .pot file it generates before creating the .po file. This is useful for
 debugging errors which may prevent the final language files from being created.
 
+makemigrations [<appname>]
+--------------------------
+
+.. django-admin:: makemigrations
+
+Creates new migrations based on the changes detected to your models.
+Migrations, their relationship with apps and more are covered in depth in
+:doc:`the migrations documentation</topics/migrations>`.
+
+Providing one or more app names as arguments will limit the migrations created
+to the app specified and any dependencies needed (the table at the other end
+of a ForeignKey, for example)
+
+.. django-admin-option:: --empty
+
+The ``--empty`` option will cause ``makemigrations`` to output an empty
+migration for the specified apps, for manual editing. This option is only
+for advanced users and should not be used unless you are familiar with
+the migration format, migration operations and the dependencies between
+your migrations.
+
+migrate [<appname> [<migrationname>]]
+-------------------------------------
+
+.. django-admin:: migrate
+
+Synchronises the database state with the current set of models and migrations.
+Migrations, their relationship with apps and more are covered in depth in
+:doc:`the migrations documentation</topics/migrations>`.
+
+The behaviour of this command changes depending on the arguments provided:
+
+* No arguments: All migrated apps have all of their migrations run,
+  and all unmigrated apps are synchronized with the database,
+* ``<appname>``: The specified app has its migrations run, up to the most
+  recent migration. This may involve running other apps' migrations too, due
+  to dependencies.
+* ``<appname> <migrationname>``: Brings the database schema to a state where it
+  would have just run the given migration, but no further - this may involve
+  unapplying migrations if you have previously migrated past the named
+  migration. Use the name `zero` to unapply all migrations for an app.
+
 runfcgi [options]
 -----------------
 
@@ -1107,47 +1149,13 @@ syncdb
 
 .. django-admin:: syncdb
 
-Creates the database tables for all apps in :setting:`INSTALLED_APPS` whose
-tables have not already been created.
-
-Use this command when you've added new applications to your project and want to
-install them in the database. This includes any apps shipped with Django that
-might be in :setting:`INSTALLED_APPS` by default. When you start a new project,
-run this command to install the default apps.
-
-.. admonition:: Syncdb will not alter existing tables
+.. deprecated:: 1.7
 
-   ``syncdb`` will only create tables for models which have not yet been
-   installed. It will *never* issue ``ALTER TABLE`` statements to match
-   changes made to a model class after installation. Changes to model classes
-   and database schemas often involve some form of ambiguity and, in those
-   cases, Django would have to guess at the correct changes to make. There is
-   a risk that critical data would be lost in the process.
+    This command has been deprecated in favour of the :djadmin:`migrate`
+    command, which performs both the old behaviour as well as executing
+    migrations. It is now just an alias to that command.
 
-   If you have made changes to a model and wish to alter the database tables
-   to match, use the ``sql`` command to display the new SQL structure and
-   compare that to your existing table schema to work out the changes.
-
-If you're installing the ``django.contrib.auth`` application, ``syncdb`` will
-give you the option of creating a superuser immediately.
-
-``syncdb`` will also search for and install any fixture named ``initial_data``
-with an appropriate extension (e.g. ``json`` or ``xml``). See the
-documentation for ``loaddata`` for details on the specification of fixture
-data files.
-
-The :djadminopt:`--noinput` option may be provided to suppress all user
-prompts.
-
-The :djadminopt:`--database` option can be used to specify the database to
-synchronize.
-
---no-initial-data
-~~~~~~~~~~~~~~~~~
-
-.. versionadded:: 1.5
-
-Use ``--no-initial-data`` to avoid loading the initial_data fixture.
+Alias for :djadmin:`migrate`.
 
 test <app or test identifier>
 -----------------------------

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

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.