Ticket #23749: patch

docs/ref/schema-editor.txt

@@ -158 +158 @@
 
 .. attribute:: SchemaEditor.connection
 
-A connection object to the database. A useful attribute of the
-connection is ``alias`` which can be used to determine the name of
-the database being accessed.
+A connection object to the database. A useful attribute of the connection is
+``alias`` which can be used to determine the name of the database being
+accessed.
 
-This in turn is useful when doing data migrations for
-:ref:`migrations with multiple database backends <data-migrations-and-multiple-databases>`.
+This in turn is useful when doing data migrations for :ref:`migrations with
+multiple database backends <data-migrations-and-multiple-databases>`.

docs/topics/migrations.txt

@@ -472 +472 @@
 Data migrations and multiple databases
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-One of the challenges that can be encountered is figuring out whether
-or not to run a migration when using multiple databases.
-
-For example, you may want to **only** run a migration against a
-particular database.
-
-In order to do that you can filter inside of your data migration
-by looking at the ``schema_editor.connection.alias`` attribute.
-However it is better to have your ``dbrouter`` leverage the same
-``allow_migrate`` call by making the following method in your
-router::
-
-        class MyRouter(object):
-
-            def allow_migrate(self, db, model):
-                # your typical migration code here
-
-            def runpython_ok(self, apps, schema_editor, model):
-                db = schema_editor.connection.alias
-                if self.allow_migrate(db, model):
-                    return True
-                return False
-
-Then to leverage this in your migrations, do the following::
-
-        # -*- coding: utf-8 -*-
-        from __future__ import unicode_literals
-
-        from django.db import models, migrations
-        from myappname.dbrouter import MyRouter
-        import sys
-
-        def forwards(apps, schema_editor):
-            # only run this for the correct databases
-            MyModel = apps.get_model("myappname", "MyModel")
-            if not MyRouter().runpython_ok(apps, schema_editor, MyModel):
-                return
-
-            """
-            This is a global configuration model so there should be only
-            row.
-            Get the first one -or- create the initial one.
-            Only set the default ports if it has not been set by user
-            already.
-            """
-            try:
-                my_model = MyModel.objects.order_by("-id").first()
-            except IndexError:
-                my_model = MyModel.objects.create()
-            if my_model.my_model_ports == "":
-                my_model.my_model_ports = "80, 8080, 3128"
-                my_model.save()
-
-        def backwards(apps, schema_editor):
-            pass
-
-        class Migration(migrations.Migration):
-
-            dependencies = [
-                # Dependencies to other migrations
-            ]
-
-            operations = [
-                migrations.RunPython(forwards, backwards),
-            ]
+One of the challenges that can be encountered is figuring out whether or not to
+run a migration when using multiple databases.
+
+For example, you may want to **only** run a migration against a particular
+database.
+
+In order to do that you can check the connection alias inside a ``RunPython``
+forwards and backwards operation by looking at the
+``schema_editor.connection.alias`` attribute.
+
+    # -*- coding: utf-8 -*-
+    from __future__ import unicode_literals
+
+    from django.db import migrations
+
+    def forwards(apps, schema_editor):
+        if not schema_editor.connection.alias == 'master-db':
+            return
+        # Your migration code goes here
+
+    class Migration(migrations.Migration):
+
+        dependencies = [
+            # Dependencies to other migrations
+        ]
+
+        operations = [
+            migrations.RunPython(forwards),
+        ]
+
+You can also use your database router's ``allow_migrate`` method, but keep in
+mind that the imported router needs to stay around as long as it is referenced
+inside a migration:
+
+.. snippet::
+    :filename: myapp/dbrouters.py
+
+    class MyRouter(object):
+
+        def allow_migrate(self, db, model):
+            return db == 'default':
+
+Then, to leverage this in your migrations, do the following::
+
+    # -*- coding: utf-8 -*-
+    from __future__ import unicode_literals
+
+    from django.db import models, migrations
+
+    from myappname.dbrouters import MyRouter
+
+    def forwards(apps, schema_editor):
+        MyModel = apps.get_model("myappname", "MyModel")
+        if not MyRouter().allow_migrate(schema_editor.connection.alias, MyModel):
+            return
+        # Your migration code goes here
+
+    class Migration(migrations.Migration):
+
+        dependencies = [
+            # Dependencies to other migrations
+        ]
+
+        operations = [
+            migrations.RunPython(forwards),
+        ]
 
 More advanced migrations
 ~~~~~~~~~~~~~~~~~~~~~~~~