From 04e3fc8de29a5a558e96243605f143c16cff3820 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 1 Jul 2009 04:37:08 +0000 Subject: [PATCH] [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 | 3 +- docs/ref/models/querysets.txt | 2 +- docs/topics/db/index.txt | 1 + docs/topics/db/multi-db.txt | 56 +++++++++++++++++++++++++++++++++++ 4 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 docs/topics/db/multi-db.txt diff --git a/docs/index.txt b/docs/index.txt index 89ee463dfa..b1036b9254 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -65,7 +65,8 @@ The model layer :ref:`Raw SQL ` | :ref:`Transactions ` | :ref:`Aggregation ` | - :ref:`Custom fields ` + :ref:`Custom fields ` | + :ref:`Multiple databases ` * **Other:** :ref:`Supported databases ` | diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 7640d5d4ca..b97e3620e2 100644 --- a/docs/ref/models/querysets.txt +++ b/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 diff --git a/docs/topics/db/index.txt b/docs/topics/db/index.txt index 949f4e87e9..bf918eba6b 100644 --- a/docs/topics/db/index.txt +++ b/docs/topics/db/index.txt @@ -16,3 +16,4 @@ model maps to a single database table. managers sql transactions + multi-db diff --git a/docs/topics/db/multi-db.txt b/docs/topics/db/multi-db.txt new file mode 100644 index 0000000000..0365004091 --- /dev/null +++ b/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')