Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

[1.7.x] Fixed #22620 -- Emphasized role of DATABASE_ROTERS in multi-d…

…b docs.

Thanks Mike O'Connor for the suggestions.

Backport of 5ecead9 from master
  • Loading branch information...
commit 403cc55f236d0877592f194ad34d6c1b5f0321ea 1 parent 4f0916c
@timgraham timgraham authored
Showing with 10 additions and 14 deletions.
  1. +10 −14 docs/topics/db/multi-db.txt
24 docs/topics/db/multi-db.txt
@@ -47,8 +47,11 @@ If the concept of a ``default`` database doesn't make sense in the context
of your project, you need to be careful to always specify the database
that you want to use. Django requires that a ``default`` database entry
be defined, but the parameters dictionary can be left blank if it will not be
-used. The following is an example ```` snippet defining two
-non-default databases, with the ``default`` entry intentionally left empty::
+used. You must setup :setting:`DATABASE_ROUTERS` for all of your apps' models,
+including those in any contrib and third-party apps you are using, so that no
+queries are routed to the default database in order to do this. The following
+is an example ```` snippet defining two non-default databases, with
+the ``default`` entry intentionally left empty::
'default': {},
@@ -87,12 +90,6 @@ particular database, you can define a :ref:`database
router<topics-db-multi-db-routing>` that implements a policy
constraining the availability of particular models.
-Alternatively, if you want fine-grained control of synchronization,
-you can pipe all or part of the output of :djadmin:`sqlall` for a
-particular application directly into your database prompt, like this::
- $ ./ sqlall sales | ./ dbshell
Using other management commands
@@ -690,12 +687,11 @@ In addition, some objects are automatically created just after
For common setups with multiple databases, it isn't useful to have these
-objects in more than one database. Common setups include master / slave and
-connecting to external databases. Therefore, it's recommended:
-- either to run :djadmin:`migrate` only for the default database;
-- or to write :ref:`database router<topics-db-multi-db-routing>` that allows
- synchronizing these three models only to one database.
+objects in more than one database. Common setups include primary/replica and
+connecting to external databases. Therefore, it's recommended to write a
+:ref:`database router<topics-db-multi-db-routing>` that allows synchronizing
+these three models to only one database. Use the same approach for contrib
+and third-party apps that don't need their tables in multiple databases.
.. warning::

2 comments on commit 403cc55


Tim thanks for the revisions. Look pretty good. About the migrate command, it's still the case that explicitly lists the --database option but doesn't. So if indeed it does support that option we need to add that to the latter docs for 1.7.


Documented --database` in 6aae07f, thanks.

Please sign in to comment.
Something went wrong with that request. Please try again.