[1.5.X] Added an example of "default" database dictionary left blank; refs #19775.

Thanks wsmith323 for the patch.

Backport of cf890c110e from master

1 files changed, 24 insertions, 5 deletions

diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt
index dd7e59b99e..8150e498de 100644
--- a/docs/topics/db/multi-db.txt
+++ b/docs/topics/db/multi-db.txt
@@ -20,11 +20,7 @@ documentation.
 
 Databases can have any alias you choose. However, the alias
 ``default`` has special significance. Django uses the database with
-the alias of ``default`` when no other database has been selected. 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 can be left blank if it will not be used.
+the alias of ``default`` when no other database has been selected.
 
 The following is an example ``settings.py`` snippet defining two
 databases -- a default PostgreSQL database and a MySQL database called
@@ -47,6 +43,29 @@ databases -- a default PostgreSQL database and a MySQL database called
         }
     }
 
+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::
+
+    DATABASES = {
+        'default': {},
+        'users': {
+            'NAME': 'user_data',
+            'ENGINE': 'django.db.backends.mysql',
+            'USER': 'mysql_user',
+            'PASSWORD': 'superS3cret'
+        },
+        'customers': {
+            'NAME': 'customer_data',
+            'ENGINE': 'django.db.backends.mysql',
+            'USER': 'mysql_cust',
+            'PASSWORD': 'veryPriv@ate'
+        }
+    }
+
 If you attempt to access a database that you haven't defined in your
 :setting:`DATABASES` setting, Django will raise a
 ``django.db.utils.ConnectionDoesNotExist`` exception.