[soc2009/multidb] Final cleanup of multi-db docs. Patch from Russell Keith-Magee.

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/multidb@11945 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/topics/db/multi-db.txt

@@ -8,44 +8,73 @@ Multiple Databases
 
 This topic guide describes Django's support for interacting with multiple
 databases. Most of the rest of Django's documentation assumes you are
-interacting with a single database.  While none of this documentation is
+interacting with a single database. If you want to interact with multiple
-incorrect, to fully interact with multiple databases additional steps must be
+databases, some additional steps must be taken.
-taken.
 
 Defining your databases
 =======================
 
-The first step to using more than one database with Django is to tell Django
+The first step to using more than one database with Django is to tell
-about the database servers you'll be using.  This is done using the
+Django about the database servers you'll be using. This is done using
-:setting:`DATABASES` setting.  This setting maps database aliases, which are
+the :setting:`DATABASES` setting. This setting maps database aliases,
-a way to refer to a specific database throughout Django, to a dictionary of
+which are a way to refer to a specific database throughout Django, to
-settings for that specific connection.  The settings in the inner dictionaries
+a dictionary of settings for that specific connection. The settings in
-are described fully in the :setting:`DATABASES` documentation.  The important
+the inner dictionaries are described fully in the :setting:`DATABASES`
-thing to note is that your primary database should have the alias
+documentation.
-``'default'``, and any additional databases you have can have whatever alias
+
-you choose.  If at any time you attempt to access a database that isn't defined
+Regardless of how many databases you have, you *must* have a database
-in your :setting:`DATABASES` setting then Django will raise a
+named ``'default'``. Any additional databases you have can have
+whatever alias you choose.
+
+The following is an example ``settings.py`` snippet defining two
+databases - a default Postgres database, and a MySQL database called
+``users``::
+
+    DATABASES = {
+        'default': {
+            'NAME': 'app_data',
+            'BACKEND': 'django.db.backends.postgres_psycopg2',
+            'USER': 'postgres_user',
+            'PASSWORD': 's3krit'
+        },
+        'users': {
+            'NAME': 'user_data'
+            'BACKEND': 'django.db.backends.mysql',
+            'USER': 'mysql_user',
+            'PASSWORD': 'priv4te'
+        }
+    }
+
+If you attempt to access a database that you haven't defined in your
+:setting:`DATABASES` setting then Django will raise a
 ``django.db.utils.ConnectionDoesNotExist`` exception.
 
 Selecting a database for a ``QuerySet``
 =======================================
 
-It is possible to select the database for a ``QuerySet`` at any point during
+It is possible to select the database for a ``QuerySet`` at any point
-it's construction.  To choose the database that a query will be preformed
+during it's construction. To choose the database that a query will be
-against simply call the ``using()`` method on the ``QuerySet`` with the sole
+preformed against simply call the ``using()`` method on the
-argument being the database alias.
+``QuerySet``. ``using()`` takes a single argument: the alias of the
+database on which you want to run the query. For example::
+
+    # This will run on the 'default' database...
+    >>> Author.objects.all()
+    # So will this...
+    >>> Author.objects.using('default').all()
+    # This will run on the 'other' database
+    >>> Author.objects.using('other').all()
 
 Select a database to save to
 ============================
 
 To choose what database to save a model to, provide a ``using`` keyword
 argument to ``Model.save()``. For example if you had a user model that you
-wanted to save to the ``'legacy_users'`` database you would do::
+wanted to save to the ``'legacy_users'`` database you would save the user
+by calling::
 
     >>> user_obj.save(using='legacy_users')
 
-To save the user.
-
 Moving an object from one database to another
 ---------------------------------------------
 
@@ -121,17 +150,22 @@ database you might use the commands::
 Using ``Managers`` with multiple databases
 ==========================================
 
-When you call ``using()`` Django returns a ``QuerySet`` that will be evaluated
+When you call ``using()`` Django returns a ``QuerySet`` that will be
-against that database.  However, sometimes you want to chain ``using()``
+evaluated against that database. However, sometimes you want to direct
-together with a cusotm manager method that doesn't return a ``QuerySet``,
+a manager to use a specific database chain ``using()``. If you call
-such as the ``get_by_natural_key`` method.  To solve this issue you can use the
+``using()``, you won't have access to any of the methods on the
-``db_manager()`` method on a manager.  This method returns a copy of the
+manager.
-*manager* bound to that specific database.  This let's you do things like::
 
-    >>> Book.objects.db("other").get_by_natural_key(...)
+To overcome this limitation, managers provide a ``db_manager()``
+method. This method returns a copy of the *manager* bound to that
+specific database. So, if you want to load an object using it's
+natural key (using the ``get_by_natural_key()`` method on the manager,
+you can call::
+
+    >>> Book.objects.db_mamanger("other").get_by_natural_key(...)
 
 If you are overriding ``get_query_set()`` on your manager you must be sure to
-either, a) call the method on the parent (using ``super()``), or b) do the
+either, call the method on the parent (using ``super()``), or do the
 appropriate handling of the ``_db`` attribute on the manager. For example if
 you wanted to return a custom ``QuerySet`` class from the ``get_query_set``
 method you could do this::
@@ -147,9 +181,9 @@ method you could do this::
 Exposing multiple databases in Django's admin interface
 =======================================================
 
-Django's admin doesn't have any explicit support for multi databases.
+Django's admin doesn't have any explicit support for multiple
-If you want to provide an admin interface for a model on a database
+databases. If you want to provide an admin interface for a model on a
-other than ``default``, you need to write custom
+database other than ``default``, you need to write custom
 :class:`~django.contrib.admin.ModelAdmin` classes that will direct the
 admin to use a specific database for content.