From 5ecead9ab993d3939068740bf195e2fff281c8ab Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 26 Aug 2014 15:43:23 -0400 Subject: [PATCH] Fixed #22620 -- Emphasized role of DATABASE_ROTERS in multi-db docs. Thanks Mike O'Connor for the suggestions. --- docs/topics/db/multi-db.txt | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt index 626709f0c5..7d4f2465c9 100644 --- a/docs/topics/db/multi-db.txt +++ b/docs/topics/db/multi-db.txt @@ -45,8 +45,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 ``settings.py`` 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 ``settings.py`` snippet defining two non-default databases, with +the ``default`` entry intentionally left empty:: DATABASES = { 'default': {}, @@ -85,12 +88,6 @@ particular database, you can define a :ref:`database router` 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:: - - $ ./manage.py sqlall sales | ./manage.py dbshell - Using other management commands ------------------------------- @@ -690,11 +687,10 @@ 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 primary/replica 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` that allows - synchronizing these three models only to one database. +connecting to external databases. Therefore, it's recommended to write a +:ref:`database router` 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::