From c93ac9cf42bff259ab71b70a89b693b9c38e4666 Mon Sep 17 00:00:00 2001 From: Shai Berger Date: Thu, 1 Sep 2016 23:19:47 +0300 Subject: [PATCH] Refs #25850, #27142, #27110 -- Documented migration history consistency checks. --- docs/releases/1.10.txt | 7 ++++--- docs/topics/db/multi-db.txt | 17 +++++++++++++++-- docs/topics/migrations.txt | 20 ++++++++++++++++++++ 3 files changed, 39 insertions(+), 5 deletions(-) diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt index dde54e936c..1df1f0dcc4 100644 --- a/docs/releases/1.10.txt +++ b/docs/releases/1.10.txt @@ -373,9 +373,10 @@ Migrations * Added support for :ref:`non-atomic migrations ` by setting the ``atomic`` attribute on a ``Migration``. -* The ``migrate`` and ``makemigrations`` commands now check for a consistent - migration history. If they find some unapplied dependencies of an applied - migration, ``InconsistentMigrationHistory`` is raised. +* The ``migrate`` and ``makemigrations`` commands now :ref:`check for a + consistent migration history `. If they find + some unapplied dependencies of an applied migration, + ``InconsistentMigrationHistory`` is raised. * The :func:`~django.db.models.signals.pre_migrate` and :func:`~django.db.models.signals.post_migrate` signals now dispatch their diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index be976246e6..c16f976911 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -98,10 +98,22 @@ the database name would raise an error. For the second example:: Using other management commands ------------------------------- -The other ``django-admin`` commands that interact with the database operate in +Most other ``django-admin`` commands that interact with the database operate in the same way as :djadmin:`migrate` -- they only ever operate on one database at a time, using ``--database`` to control the database used. +An exception to this rule is the :djadmin:`makemigrations` command. It +validates the migration history in the databases to catch problems with the +existing migration files (which could be caused by editing them) before +creating new migrations. By default, it checks only the ``default`` database, +but it consults the the :meth:`allow_migrate` method of :ref:`routers +` if any are installed. + +.. versionchanged:: 1.10 + + Migration consistency checks were added. Checks based on database routers + were added in 1.10.1. + .. _topics-db-multi-db-routing: Automatic database routing @@ -188,7 +200,8 @@ A database Router is a class that provides up to four methods: ``model_name`` will be silently skipped when running :djadmin:`migrate` on the ``db``. Changing the behavior of ``allow_migrate()`` for models that already have migrations may result in broken foreign keys, extra tables, - or missing tables. + or missing tables. When :djadmin:`makemigrations` verifies the migration + history, it skips databases where no app is allowed to migrate. A router doesn't have to provide *all* these methods -- it may omit one or more of them. If one of the methods is omitted, Django will skip diff --git a/docs/topics/migrations.txt b/docs/topics/migrations.txt index 9f3635dd4c..0c04fe7295 100644 --- a/docs/topics/migrations.txt +++ b/docs/topics/migrations.txt @@ -298,6 +298,26 @@ Django checks that all of the respective columns already exist in the database and fake-applies the migration if so. Without ``--fake-initial``, initial migrations are treated no differently from any other migration. +.. _migration-history-consistency: + +History consistency +------------------- + +As previously discussed, you may need to linearize migrations manually when two +development branches are joined. While editing migration dependencies, you can +inadvertently create an inconsistent history state where a migration has been +applied but some of its dependencies haven't. This is a strong indication that +the dependencies are incorrect, so Django will refuse to run migrations or make +new migrations until it's fixed. When using multiple databases, you can use the +:meth:`allow_migrate` method of :ref:`database routers +` to control which databases +:djadmin:`makemigrations` checks for consistent history. + +.. versionchanged:: 1.10 + + Migration consistency checks were added. Checks based on database routers + were added in 1.10.1. + Adding migrations to apps =========================