Implement allow_migrate for migration operations

3 files changed, 43 insertions, 2 deletions

diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt
index df2b10d18c..a617c90b34 100644
--- a/docs/releases/1.7.txt
+++ b/docs/releases/1.7.txt
@@ -110,6 +110,18 @@ Backwards incompatible changes in 1.7
     deprecation timeline for a given feature, its removal may appear as a
     backwards incompatible change.
 
+allow_syncdb/allow_migrate
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While Django will still look at ``allow_syncdb`` methods even though they
+should be renamed to ``allow_migrate``, there is a subtle difference in which
+models get passed to these methods.
+
+For apps with migrations, ``allow_migrate`` will now get passed
+:ref:`historical models <historical-models>`, which are special versioned models
+without custom attributes, methods or managers. Make sure your ``allow_migrate``
+methods are only referring to fields or other items in ``model._meta``.
+
 Miscellaneous
 ~~~~~~~~~~~~~
 
diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index 6c74fb944d..6e19844b5c 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -163,8 +163,14 @@ A database Router is a class that provides up to four methods:
     the router has no opinion. This method can be used to determine
     the availability of a model on a given database.
 
-    Note that if this returns ``True`` for an app with migrations but
-    ``False`` for an app those migrations depend on, Django will error.
+    Note that migrations will just silently not perform any operations
+    on a model for which this returns ``False``. This may result in broken
+    ForeignKeys, extra tables or missing tables if you change it once you
+    have applied some migrations.
+
+    The value passed for ``model`` may be a
+    :ref:`historical model <historical-models>`, and thus not have any
+    custom attributes, methods or managers. You should only rely on ``_meta``.
 
 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 f80cbf81fd..5f7def7107 100644
--- a/docs/topics/migrations.txt
+++ b/docs/topics/migrations.txt
@@ -272,3 +272,26 @@ Note that this only works given two things:
 * You have not manually edited your database - Django won't be able to detect
   that your database doesn't match your models, you'll just get errors when
   migrations try and modify those tables.
+
+
+.. historical-models:
+
+Historical models
+-----------------
+
+When you run migrations, Django is working from historical versions of
+your models stored in the migration files. If you write Python code
+using the ``django.db.migrations.RunPython`` operation, or if you have
+``allow_migrate`` methods on your database routers, you will be exposed
+to these versions of your models.
+
+Because it's impossible to serialize arbitrary Python code, these historical
+models will not have any custom methods or managers that you have defined.
+They will, however, have the same fields, relationships and ``Meta`` options
+(also versioned, so they may be different from your current ones).
+
+In addition, the base classes of the model are just stored as pointers,
+so you must always keep base classes around for as long as there is a migration
+that contains a reference to them. On the plus side, methods and managers
+from these base classes inherit normally, so if you absolutely need access
+to these you can opt to move them into a superclass.