Fixed #24351, #24346 -- Changed the signature of allow_migrate().

The new signature enables better support for routing RunPython and
RunSQL operations, especially w.r.t. reusable and third-party apps.

This commit also takes advantage of the deprecation cycle for the old
signature to remove the backward incompatibility introduced in #22583;
RunPython and RunSQL won't call allow_migrate() when when the router
has the old signature.

Thanks Aymeric Augustin and Tim Graham for helping shape up the patch.

Refs 22583.

1 files changed, 5 insertions, 1 deletions

diff --git a/docs/howto/writing-migrations.txt b/docs/howto/writing-migrations.txt
index 59a636626a..37a8b4ed5a 100644
--- a/docs/howto/writing-migrations.txt
+++ b/docs/howto/writing-migrations.txt
@@ -46,7 +46,7 @@ method of database routers as ``**hints``:
 
     class MyRouter(object):
 
-        def allow_migrate(self, db, model, **hints):
+        def allow_migrate(self, db, app_label, model_name=None, **hints):
             if 'target_db' in hints:
                 return db == hints['target_db']
             return True
@@ -68,6 +68,10 @@ Then, to leverage this in your migrations, do the following::
             migrations.RunPython(forwards, hints={'target_db': 'default'}),
         ]
 
+If your ``RunPython`` or ``RunSQL`` operation only affects one model, it's good
+practice to pass ``model_name`` as a hint to make it as transparent as possible
+to the router. This is especially important for reusable and third-party apps.
+
 Migrations that add unique fields
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~