Fixed #27666 -- Delayed rendering of recursivly related models in migration operations.

2 files changed, 28 insertions, 0 deletions

diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index 739b2bcdf8..bb5d451379 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -421,6 +421,8 @@ It accepts two list of operations, and when asked to apply state will use the
 state list, and when asked to apply changes to the database will use the database
 list. Do not use this operation unless you're very sure you know what you're doing.
 
+.. _writing-your-own-migration-operation:
+
 Writing your own
 ================
 
@@ -480,6 +482,21 @@ Some things to note:
   to them; these just represent the difference the ``state_forwards`` method
   would have applied, but are given to you for convenience and speed reasons.
 
+* If you want to work with model classes or model instances from the
+  ``from_state`` argument in ``database_forwards()`` or
+  ``database_backwards()``, you must render model states using the
+  ``clear_delayed_apps_cache()`` method to make related models available::
+
+    def database_forwards(self, app_label, schema_editor, from_state, to_state):
+        # This operation should have access to all models. Ensure that all models are
+        # reloaded in case any are delayed.
+        from_state.clear_delayed_apps_cache()
+        ...
+
+  .. versionadded:: 1.11
+
+    This requirement and the ``clear_delayed_apps_cache()`` method is new.
+
 * ``to_state`` in the database_backwards method is the *older* state; that is,
   the one that will be the current state once the migration has finished reversing.
 
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index f47e9d3b20..08572560ea 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -593,6 +593,17 @@ must receive a dictionary of context rather than ``Context`` or
 dictionary instead -- doing so is backwards-compatible with older versions of
 Django.
 
+Model state changes in migration operations
+-------------------------------------------
+
+To improve the speed of applying migrations, rendering of related models is
+delayed until an operation that needs them (e.g. ``RunPython``). If you have a
+custom operation that works with model classes or model instances from the
+``from_state`` argument in ``database_forwards()`` or ``database_backwards()``,
+you must render model states using the ``clear_delayed_apps_cache()`` method as
+described in :ref:`writing your own migration operation
+<writing-your-own-migration-operation>`.
+
 Miscellaneous
 -------------