More migration docs, and conversion of all easy syncdb references

docs/howto/legacy-databases.txt

@@ -81,10 +81,10 @@ access to your precious data on a model by model basis.
 Install the core Django tables
 ==============================
 
-Next, run the :djadmin:`syncdb` command to install any extra needed database
+Next, run the :djadmin:`migrate` command to install any extra needed database
 records such as admin permissions and content types::
 
-    python manage.py syncdb
+    python manage.py migrate
 
 Test and tweak
 ==============

docs/internals/contributing/writing-documentation.txt

@@ -165,9 +165,9 @@ __ http://sphinx.pocoo.org/markup/desc.html
 
 * ``django-admin`` commands::
 
-        .. django-admin:: syncdb
+        .. django-admin:: migrate
 
-  To link, use ``:djadmin:`syncdb```.
+  To link, use ``:djadmin:`migrate```.
 
 * ``django-admin`` command-line options::
 

docs/intro/overview.txt

@@ -53,10 +53,11 @@ automatically:
 
 .. code-block:: bash
 
-    manage.py syncdb
+    manage.py migrate
 
-The :djadmin:`syncdb` command looks at all your available models and creates
-tables in your database for whichever tables don't already exist.
+The :djadmin:`migrate` command looks at all your available models and creates
+tables in your database for whichever tables don't already exist, as well as
+optionally providing :doc:`much richer schema control </topics/migrations>`.
 
 Enjoy the free API
 ==================

docs/intro/reusable-apps.txt

@@ -155,7 +155,7 @@ this. For a small app like polls, this process isn't too difficult.
 
           url(r'^polls/', include('polls.urls')),
 
-    3. Run `python manage.py syncdb` to create the polls models.
+    3. Run `python manage.py migrate` to create the polls models.
 
     4. Start the development server and visit http://127.0.0.1:8000/admin/
        to create a poll (you'll need the Admin app enabled).

docs/man/django-admin.1

@@ -45,8 +45,7 @@ Outputs to standard output all data in the database associated with the named
 application(s).
 .TP
 .BI flush
-Returns the database to the state it was in immediately after syncdb was
-executed.
+Removes all data from the database and then re-installs any initial data.
 .TP
 .B inspectdb
 Introspects the database tables in the database specified in settings.py and outputs a Django
@@ -114,9 +113,9 @@ the current directory or the optional destination.
 Creates a Django project directory structure for the given project name
 in the current directory or the optional destination.
 .TP
-.BI syncdb
-Creates the database tables for all apps in INSTALLED_APPS whose tables
-haven't already been created.
+.BI migrate
+Runs migrations for apps containing migrations, and just creates missing tables
+for apps without migrations.
 .TP
 .BI "test [" "\-\-verbosity" "] [" "\-\-failfast" "] [" "appname ..." "]"
 Runs the test suite for the specified applications, or the entire project if

docs/ref/contrib/comments/index.txt

@@ -31,7 +31,7 @@ To get started using the ``comments`` app, follow these steps:
 #. Install the comments framework by adding ``'django.contrib.comments'`` to
    :setting:`INSTALLED_APPS`.
 
-#. Run ``manage.py syncdb`` so that Django will create the comment tables.
+#. Run ``manage.py migrate`` so that Django will create the comment tables.
 
 #. Add the comment app's URLs to your project's ``urls.py``:
 

docs/ref/contrib/contenttypes.txt

@@ -86,7 +86,7 @@ The ``ContentType`` model
 Let's look at an example to see how this works. If you already have
 the :mod:`~django.contrib.contenttypes` application installed, and then add
 :mod:`the sites application <django.contrib.sites>` to your
-:setting:`INSTALLED_APPS` setting and run ``manage.py syncdb`` to install it,
+:setting:`INSTALLED_APPS` setting and run ``manage.py migrate`` to install it,
 the model :class:`django.contrib.sites.models.Site` will be installed into
 your database. Along with it a new instance of
 :class:`~django.contrib.contenttypes.models.ContentType` will be

docs/ref/contrib/flatpages.txt

@@ -55,14 +55,14 @@ or:
 3. Add ``'django.contrib.flatpages.middleware.FlatpageFallbackMiddleware'``
    to your :setting:`MIDDLEWARE_CLASSES` setting.
 
-4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
+4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
 .. currentmodule:: django.contrib.flatpages.middleware
 
 How it works
 ============
 
-``manage.py syncdb`` creates two tables in your database: ``django_flatpage``
+``manage.py migrate`` creates two tables in your database: ``django_flatpage``
 and ``django_flatpage_sites``. ``django_flatpage`` is a simple lookup table
 that simply maps a URL to a title and bunch of text content.
 ``django_flatpage_sites`` associates a flatpage with a site.

docs/ref/contrib/index.txt

@@ -15,7 +15,7 @@ those packages have.
     For most of these add-ons -- specifically, the add-ons that include either
     models or template tags -- you'll need to add the package name (e.g.,
     ``'django.contrib.admin'``) to your :setting:`INSTALLED_APPS` setting and
-    re-run ``manage.py syncdb``.
+    re-run ``manage.py migrate``.
 
 .. _"batteries included" philosophy: http://docs.python.org/tutorial/stdlib.html#batteries-included
 

docs/ref/contrib/redirects.txt

@@ -18,12 +18,12 @@ To install the redirects app, follow these steps:
 2. Add ``'django.contrib.redirects'`` to your :setting:`INSTALLED_APPS` setting.
 3. Add ``'django.contrib.redirects.middleware.RedirectFallbackMiddleware'``
    to your :setting:`MIDDLEWARE_CLASSES` setting.
-4. Run the command :djadmin:`manage.py syncdb <syncdb>`.
+4. Run the command :djadmin:`manage.py migrate <migrate>`.
 
 How it works
 ============
 
-``manage.py syncdb`` creates a ``django_redirect`` table in your database. This
+``manage.py migrate`` creates a ``django_redirect`` table in your database. This
 is a simple lookup table with ``site_id``, ``old_path`` and ``new_path`` fields.
 
 The ``RedirectFallbackMiddleware`` does all of the work. Each time any Django

docs/ref/contrib/sites.txt

@@ -264,7 +264,7 @@ To enable the sites framework, follow these steps:
 
     SITE_ID = 1
 
-3. Run :djadmin:`syncdb`.
+3. Run :djadmin:`migrate`.
 
 ``django.contrib.sites`` registers a
 :data:`~django.db.models.signals.post_syncdb` signal handler which creates a

docs/ref/databases.txt

@@ -224,7 +224,7 @@ If you upgrade an existing project to MySQL 5.5.5 and subsequently add some
 tables, ensure that your tables are using the same storage engine (i.e. MyISAM
 vs. InnoDB). Specifically, if tables that have a ``ForeignKey`` between them
 use different storage engines, you may see an error like the following when
-running ``syncdb``::
+running ``migrate``::
 
     _mysql_exceptions.OperationalError: (
         1005, "Can't create table '\\db_name\\.#sql-4a8_ab' (errno: 150)"
@@ -663,7 +663,7 @@ required.
 .. _`Oracle Database Server`: http://www.oracle.com/
 .. _`cx_Oracle`: http://cx-oracle.sourceforge.net/
 
-In order for the ``python manage.py syncdb`` command to work, your Oracle
+In order for the ``python manage.py migrate`` command to work, your Oracle
 database user must have privileges to run the following commands:
 
 * CREATE TABLE
@@ -752,7 +752,7 @@ Oracle imposes a name length limit of 30 characters. To accommodate this, the
 backend truncates database identifiers to fit, replacing the final four
 characters of the truncated name with a repeatable MD5 hash value.
 
-When running syncdb, an ``ORA-06552`` error may be encountered if
+When running ``migrate``, an ``ORA-06552`` error may be encountered if
 certain Oracle keywords are used as the name of a model field or the
 value of a ``db_column`` option.  Django quotes all identifiers used
 in queries to prevent most such problems, but this error can still

docs/ref/django-admin.txt

@@ -242,10 +242,8 @@ flush
 
 .. django-admin:: flush
 
-Returns the database to the state it was in immediately after :djadmin:`syncdb`
-was executed. This means that all data will be removed from the database, any
-post-synchronization handlers will be re-executed, and the ``initial_data``
-fixture will be re-installed.
+Removes all data from the database, re-executes any post-synchronization
+handlers, and reinstalls any initial data fixtures.
 
 The :djadminopt:`--noinput` option may be provided to suppress all user
 prompts.
@@ -1293,7 +1291,7 @@ This command is only available if Django's :doc:`authentication system
 
 Creates a superuser account (a user who has all permissions). This is
 useful if you need to create an initial superuser account but did not
-do so during ``syncdb``, or if you need to programmatically generate
+do so during the first ``migrate``, or if you need to programmatically generate
 superuser accounts for your site(s).
 
 When run interactively, this command will prompt for a password for
@@ -1379,7 +1377,7 @@ allows for the following options:
 
 Example usage::
 
-    django-admin.py syncdb --pythonpath='/home/djangoprojects/myproject'
+    django-admin.py migrate --pythonpath='/home/djangoprojects/myproject'
 
 Adds the given filesystem path to the Python `import search path`_. If this
 isn't provided, ``django-admin.py`` will use the ``PYTHONPATH`` environment
@@ -1394,7 +1392,7 @@ setting the Python path for you.
 
 Example usage::
 
-    django-admin.py syncdb --settings=mysite.settings
+    django-admin.py migrate --settings=mysite.settings
 
 Explicitly specifies the settings module to use. The settings module should be
 in Python package syntax, e.g. ``mysite.settings``. If this isn't provided,
@@ -1408,7 +1406,7 @@ Note that this option is unnecessary in ``manage.py``, because it uses
 
 Example usage::
 
-    django-admin.py syncdb --traceback
+    django-admin.py migrate --traceback
 
 By default, ``django-admin.py`` will show a simple error message whenever an
 :class:`~django.core.management.CommandError` occurs, but a full stack trace
@@ -1424,7 +1422,7 @@ will also output a full stack trace when a ``CommandError`` is raised.
 
 Example usage::
 
-    django-admin.py syncdb --verbosity 2
+    django-admin.py migrate --verbosity 2
 
 Use ``--verbosity`` to specify the amount of notification and debug information
 that ``django-admin.py`` should print to the console.

docs/ref/models/options.txt

@@ -106,9 +106,9 @@ Django quotes column and table names behind the scenes.
 .. attribute:: Options.managed
 
     Defaults to ``True``, meaning Django will create the appropriate database
-    tables in :djadmin:`syncdb` and remove them as part of a :djadmin:`flush`
-    management command. That is, Django *manages* the database tables'
-    lifecycles.
+    tables in :djadmin:`migrate` or as part of migrations and remove them as
+    part of a :djadmin:`flush` management command. That is, Django
+    *manages* the database tables' lifecycles.
 
     If ``False``, no database table creation or deletion operations will be
     performed for this model. This is useful if the model represents an existing
@@ -192,9 +192,9 @@ Django quotes column and table names behind the scenes.
 .. admonition:: Changing order_with_respect_to
 
         ``order_with_respect_to`` adds an additional field/database column
-        named ``_order``, so be sure to handle that as you would any other
-        change to your models if you add or change ``order_with_respect_to``
-        after your initial :djadmin:`syncdb`.
+        named ``_order``, so be sure to make and apply the appropriate 
+        migrations if you add or change ``order_with_respect_to``
+        after your initial :djadmin:`migrate`.
 
 ``ordering``
 ------------

docs/topics/auth/customizing.txt

@@ -275,7 +275,7 @@ can or cannot do with Task instances, specific to your application::
             )
 
 The only thing this does is create those extra permissions when you run
-:djadmin:`manage.py syncdb <syncdb>`. Your code is in charge of checking the
+:djadmin:`manage.py migrate <migrate>`. Your code is in charge of checking the
 value of these permissions when an user is trying to access the functionality
 provided by the application (viewing tasks, changing the status of tasks,
 closing tasks.) Continuing the above example, the following checks if a user may
@@ -380,14 +380,12 @@ use as your User model.
    Changing :setting:`AUTH_USER_MODEL` has a big effect on your database
    structure. It changes the tables that are available, and it will affect the
    construction of foreign keys and many-to-many relationships. If you intend
-   to set :setting:`AUTH_USER_MODEL`, you should set it before running
-   ``manage.py syncdb`` for the first time.
+   to set :setting:`AUTH_USER_MODEL`, you should set it before creating
+   any migrations or running ``manage.py migrate`` for the first time.
 
-   If you have an existing project and you want to migrate to using a custom
-   User model, you may need to look into using a migration tool like South_
-   to ease the transition.
-
-.. _South: http://south.aeracode.org
+   Changing this setting after you have tables created is not supported
+   by :djadmin:`makemigrations` and will result in you having to manually
+   write a set of migrations to fix your schema.
 
 Referencing the User model
 --------------------------

docs/topics/auth/default.txt

@@ -65,7 +65,7 @@ interactively <auth-admin>`.
 Creating superusers
 -------------------
 
-:djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the
+:djadmin:`manage.py migrate <migrate>` prompts you to create a superuser the
 first time you run it with ``'django.contrib.auth'`` in your
 :setting:`INSTALLED_APPS`. If you need to create a superuser at a later date,
 you can use a command line utility::
@@ -190,13 +190,13 @@ setting, it will ensure that three default permissions -- add, change and
 delete -- are created for each Django model defined in one of your installed
 applications.
 
-These permissions will be created when you run :djadmin:`manage.py syncdb
-<syncdb>`; the first time you run ``syncdb`` after adding
+These permissions will be created when you run :djadmin:`manage.py migrate
+<migrate>`; the first time you run ``migrate`` after adding
 ``django.contrib.auth`` to :setting:`INSTALLED_APPS`, the default permissions
 will be created for all previously-installed models, as well as for any new
 models being installed at that time. Afterward, it will create default
-permissions for new models each time you run :djadmin:`manage.py syncdb
-<syncdb>`.
+permissions for new models each time you run :djadmin:`manage.py migrate
+<migrate>`.
 
 Assuming you have an application with an
 :attr:`~django.db.models.Options.app_label` ``foo`` and a model named ``Bar``,

docs/topics/auth/index.txt

@@ -67,7 +67,7 @@ and two items in your :setting:`MIDDLEWARE_CLASSES` setting:
 2. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates
    users with requests using sessions.
 
-With these settings in place, running the command ``manage.py syncdb`` creates
+With these settings in place, running the command ``manage.py migrate`` creates
 the necessary database tables for auth related models, creates permissions for
 any models defined in your installed apps, and prompts you to create
 a superuser account the first time you run it.

docs/topics/db/models.txt

@@ -77,7 +77,8 @@ application by the :djadmin:`manage.py startapp <startapp>` script),
     )
 
 When you add new apps to :setting:`INSTALLED_APPS`, be sure to run
-:djadmin:`manage.py syncdb <syncdb>`.
+:djadmin:`manage.py migrate <migrate>`, optionally making migrations
+for them first with :djadmin:`manage.py makemigrations <makemigrations>`.
 
 Fields
 ======
@@ -956,7 +957,7 @@ The reverse name of the ``common.ChildA.m2m`` field will be
 reverse name of the ``rare.ChildB.m2m`` field will be ``rare_childb_related``.
 It is up to you how you use the ``'%(class)s'`` and ``'%(app_label)s`` portion
 to construct your related name, but if you forget to use it, Django will raise
-errors when you validate your models (or run :djadmin:`syncdb`).
+errors when you validate your models (or run :djadmin:`migrate`).
 
 If you don't specify a :attr:`~django.db.models.ForeignKey.related_name`
 attribute for a field in an abstract base class, the default reverse name will
@@ -1049,7 +1050,7 @@ are putting those types of relations on a subclass of another model,
 you **must** specify the
 :attr:`~django.db.models.ForeignKey.related_name` attribute on each
 such field. If you forget, Django will raise an error when you run
-:djadmin:`validate` or :djadmin:`syncdb`.
+:djadmin:`validate` or :djadmin:`migrate`.
 
 For example, using the above ``Place`` class again, let's create another
 subclass with a :class:`~django.db.models.ManyToManyField`::

docs/topics/http/sessions.txt

@@ -44,7 +44,7 @@ Using database-backed sessions
 If you want to use a database-backed session, you need to add
 ``'django.contrib.sessions'`` to your :setting:`INSTALLED_APPS` setting.
 
-Once you have configured your installation, run ``manage.py syncdb``
+Once you have configured your installation, run ``manage.py migrate``
 to install the single database table that stores session data.
 
 .. _cached-sessions-backend:

docs/topics/install.txt

@@ -122,14 +122,12 @@ database bindings are installed.
 * If you're using an unofficial 3rd party backend, please consult the
   documentation provided for any additional requirements.
 
-If you plan to use Django's ``manage.py syncdb`` command to automatically
+If you plan to use Django's ``manage.py migrate`` command to automatically
 create database tables for your models (after first installing Django and
 creating a project), you'll need to ensure that Django has permission to create
 and alter tables in the database you're using; if you plan to manually create
 the tables, you can simply grant Django ``SELECT``, ``INSERT``, ``UPDATE`` and
-``DELETE`` permissions. On some databases, Django will need ``ALTER TABLE``
-privileges during ``syncdb`` but won't issue ``ALTER TABLE`` statements on a
-table once ``syncdb`` has created it. After creating a database user with these
+``DELETE`` permissions. After creating a database user with these
 permissions, you'll specify the details in your project's settings file,
 see :setting:`DATABASES` for details.
 

docs/topics/migrations.txt

@@ -31,7 +31,7 @@ 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.
 
@@ -111,3 +111,113 @@ 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.
+
+Workflow
+--------
+
+Working with migrations is simple. Make changes to your models - say, add
+a field and remove a model - and then run :djadmin:`makemigrations`::
+
+    $ python manage.py makemigrations
+    Migrations for 'books':
+      0003_auto.py:
+        - Alter field author on book
+
+Your models will be scanned and compared to the versions currently
+contained in your migration files, and then a new set of migrations
+will be written out. Make sure to read the output to see what
+``makemigrations`` thinks you have changed - it's not perfect, and for
+complex changes it might not be detecting what you expect.
+
+Once you have your new migration files, you should apply them to your
+database to make sure they work as expected::
+
+    $ python manage.py migrate
+    Operations to perform:
+      Synchronize unmigrated apps: sessions, admin, messages, auth, staticfiles, contenttypes
+      Apply all migrations: books
+    Synchronizing apps without migrations:
+      Creating tables...
+      Installing custom SQL...
+      Installing indexes...
+    Installed 0 object(s) from 0 fixture(s)
+    Running migrations:
+      Applying books.0003_auto... OK
+
+The command runs in two stages; first, it synchronizes unmigrated apps
+(performing the same functionality that ``syncdb`` used to provide), and
+then it runs any migrations that have not yet been applied.
+
+Once the migration is applied, commit the migration and the models change
+to your version control system as a single commit - that way, when other
+developers (or your production servers) check out the code, they'll
+get both the changes to your models and the accompanying migration at the
+same time.
+
+Dependencies
+------------
+
+While migrations are per-app, the tables and relationships implied by
+your models are too complex to be created for just one app at a time. When
+you make a migration that requires something else to run - for example,
+you add a ForeignKey in your ``books`` app to your ``authors`` app - the
+resulting migration will contain a dependency on a migration in ``authors``.
+
+This means that when you run the migrations, the ``authors`` migration runs
+first and creates the table the ForeignKey references, and then the migration
+that makes the ForeignKey column runs afterwards and creates the constraint.
+If this didn't happen, the migration would try to create the ForeignKey column
+without the table it's referencing existing and your database would
+throw an error.
+
+This dependency behaviour affects most migration operations where you
+restrict to a single app. Restricting to a single app (either in
+``makemigrations`` or ``migrate``) is a best-efforts promise, and not
+a guarantee; any other apps that need to be used to get dependencies correct
+will be.
+
+Migration files
+---------------
+
+Migrations are stored as an on-disk format, referred to here as
+"migration files". These files are actually just normal Python files with
+an agreed-upon object layout, written in a declarative style.
+
+A basic migration file looks like this::
+
+    from django.db import migrations, models
+
+    class Migration(migrations.Migration):
+
+        dependencies = [("migrations", "0001_initial")]
+
+        operations = [
+            migrations.DeleteModel("Tribble"),
+            migrations.AddField("Author", "rating", models.IntegerField(default=0)),
+        ]
+
+What Django looks for when it loads a migration file (as a Python module) is
+a subclass of ``django.db.migrations.Migration`` called ``Migration``. It then
+inspects this object for four attributes, only two of which are used
+most of the time:
+
+* ``dependencies``, a list of migrations this one depends on.
+* ``operations``, a list of Operation classes that define what this migration
+  does.
+
+The operations are the key; they are a set of declarative instructions which
+tell Django what schema changes need to be made. Django scans them and
+builds an in-memory representation of all of the schema changes to all apps,
+and uses this to generate the SQL which makes the schema changes.
+
+That in-memory structure is also used to work out what the differences are
+between your models and the current state of your migrations; Django runs
+through all the changes, in order, on an in-memory set of models to come
+up with the state of your models last time you ran ``makemigrations``. It
+then uses these models to compare against the ones in your ``models.py`` files
+to work out what you have changed.
+
+You should rarely, if ever, need to edit migration files by hand, but
+it's entirely possible to write them manually if you need to. Some of the
+more complex operations are not autodetectable and are only available via
+a hand-written migration, so don't be scared about editing them if you have to.

docs/topics/serialization.txt

@@ -296,7 +296,7 @@ serialize an object that refers to a content type, then you need to have a way
 to refer to that content type to begin with. Since ``ContentType`` objects are
 automatically created by Django during the database synchronization process,
 the primary key of a given content type isn't easy to predict; it will
-depend on how and when :djadmin:`syncdb` was executed. This is true for all
+depend on how and when :djadmin:`migrate` was executed. This is true for all
 models which automatically generate objects, notably including
 :class:`~django.contrib.auth.models.Permission`,
 :class:`~django.contrib.auth.models.Group`, and

docs/topics/testing/advanced.txt

@@ -278,7 +278,7 @@ testing behavior. This behavior involves:
 
 #. Creating the test databases.
 
-#. Running ``syncdb`` to install models and initial data into the test
+#. Running ``migrate`` to install models and initial data into the test
    databases.
 
 #. Running the tests that were found.
@@ -469,7 +469,7 @@ can be useful during testing.
 
 .. function:: create_test_db([verbosity=1, autoclobber=False])
 
-    Creates a new test database and runs ``syncdb`` against it.
+    Creates a new test database and runs ``migrate`` against it.
 
     ``verbosity`` has the same behavior as in ``run_tests()``.
 

docs/topics/testing/overview.txt

@@ -1215,9 +1215,9 @@ documentation<dumpdata>` for more details.
 
 .. note::
 
-    If you've ever run :djadmin:`manage.py syncdb<syncdb>`, you've
+    If you've ever run :djadmin:`manage.py migrate<migrate>`, you've
     already used a fixture without even knowing it! When you call
-    :djadmin:`syncdb` in the database for the first time, Django
+    :djadmin:`migrate` in the database for the first time, Django
     installs a fixture called ``initial_data``. This gives you a way
     of populating a new database with any initial data, such as a
     default set of categories.