[soc2009/multidb] First set of documentation for multi-db

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

docs/index.txt

@@ -65,7 +65,8 @@ The model layer
       :ref:`Raw SQL <topics-db-sql>` |
       :ref:`Transactions <topics-db-transactions>` |
       :ref:`Aggregation <topics-db-aggregation>` |
-      :ref:`Custom fields <howto-custom-model-fields>`
+      :ref:`Custom fields <howto-custom-model-fields>` |
+      :ref:`Multiple databases <topics-db-multi-db>`
 
     * **Other:**
       :ref:`Supported databases <ref-databases>` |

docs/ref/models/querysets.txt

@@ -877,7 +877,7 @@ logically::
 ``using(alias)``
 ~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 1.2
+.. versionadded:: TODO
 
 This method is for controlling which database the ``QuerySet`` will be
 evaluated against if you are using more than one database.  The only argument

docs/topics/db/index.txt

@@ -16,3 +16,4 @@ model maps to a single database table.
    managers
    sql
    transactions
+   multi-db

docs/topics/db/multi-db.txt

@@ -0,0 +1,56 @@
+.. _topics-db-multi-db:
+
+==================
+Multiple Databases
+==================
+
+.. versionadded:: TODO
+
+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
+incorrect, to fully interact with multiple databases additional steps must be
+taken.
+
+Defining Your Databases
+=======================
+
+The first step to using more than one database with Django is to tell Django
+about the database servers you'll be using.  This is done using the
+:settings:`DATABASES` setting.  This setting maps database aliases, which are
+a way to refer to a specific database throughout Django, to a dictionary of
+settings for that specific connection.  The settings in the inner dictionaries
+are described fully in the :settings:`DATABASES` documentation.  The important
+thing to note is that your primary database should have the alias
+``'default'``, and any additional databases you have can have whatever alias
+you choose.
+
+Selecting a Database for a ``QuerySet``
+=======================================
+
+It is possible to select the database for a ``QuerySet`` at any point during
+it's construction.  To choose the database that a query will be preformed
+against simply call the ``using()`` method on the ``QuerySet`` with the sole
+argument being the database alias.
+
+Select a Database to Save a Model 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::
+
+    >>> user_obj.save(using='legacy_users')
+
+To save the user.
+
+Select a Database to Delete a Model From
+=======================================
+
+To select which database to delete a model from you also use a ``using``
+keyword argument to the ``Model.delete()`` method, analogous to the ``using``
+keyword argument to ``save()``.  For example if you were migrating a user from
+the ``'legacy_users'`` database to the ``'new_users'`` database you might do::
+
+    >>> user_obj.save(using='new_users')
+    >>> usre_obj.delete(using='legacy_users')