Fixed #1142 -- Added multiple database support.

This monster of a patch is the result of Alex Gaynor's 2009 Google Summer of Code project.
Congratulations to Alex for a job well done.

Big thanks also go to:
 * Justin Bronn for keeping GIS in line with the changes,
 * Karen Tracey and Jani Tiainen for their help testing Oracle support
 * Brett Hoerner, Jon Loyens, and Craig Kimmerer for their feedback.
 * Malcolm Treddinick for his guidance during the GSoC submission process.
 * Simon Willison for driving the original design process
 * Cal Henderson for complaining about ponies he wanted.

... and everyone else too numerous to mention that helped to bring this feature into fruition.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@11952 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 218 insertions, 78 deletions

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 8ff15097ac..1feb34a90b 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -189,30 +189,67 @@ where ``reason`` is a short message (intended for developers or logging, not for
 end users) indicating the reason the request was rejected.  See
 :ref:`ref-contrib-csrf`.
 
-.. setting:: DATABASE_ENGINE
 
-DATABASE_ENGINE
----------------
+.. setting:: DATABASES
+
+DATABASES
+---------
+
+.. versionadded: 1.2
+
+Default: ``{}`` (Empty dictionary)
+
+A dictionary containing the settings for all databases to be used with
+Django. It is a nested dictionary who's contents maps database aliases
+to a dictionary containing the options for an individual database.
+
+The :setting:`DATABASES` setting must configure a ``default`` database;
+any number of additional databases may also be specified.
+
+The simplest possible settings file is for a single-database setup using
+SQLite. This can be configured using the following::
+
+    DATABASES = {
+        'default': {
+            'BACKEND': 'django.db.backends.sqlite3',
+            'NAME': 'mydatabase'
+        }
+    }
+
+For other database backends, or more complex SQLite configurations, other options
+will be required. The following inner options are available.
+
+.. setting:: ENGINE
+
+ENGINE
+~~~~~~
 
 Default: ``''`` (Empty string)
 
-The database backend to use. The built-in database backends are
-``'postgresql_psycopg2'``, ``'postgresql'``, ``'mysql'``, ``'sqlite3'``, and
-``'oracle'``.
+The database backend to use. The built-in database backends are:
+
+    * ``'django.db.backends.postgresql_psycopg2'``
+    * ``'django.db.backends.postgresql'``
+    * ``'django.db.backends.mysql'``
+    * ``'django.db.backends.sqlite3'``
+    * ``'django.db.backends.oracle'``
 
 You can use a database backend that doesn't ship with Django by setting
-``DATABASE_ENGINE`` to a fully-qualified path (i.e.
+``ENGINE`` to a fully-qualified path (i.e.
 ``mypackage.backends.whatever``). Writing a whole new database backend from
 scratch is left as an exercise to the reader; see the other backends for
 examples.
 
-.. versionadded:: 1.0
-    Support for external database backends is new in 1.0.
+.. note::
+    Prior to Django 1.2, you could use a short version of the backend name
+    to reference the built-in database backends (e.g., you could use
+    ``'sqlite3'`` to refer to the SQLite backend). This format has been
+    deprecated, and will be removed in Django 1.4.
 
-.. setting:: DATABASE_HOST
+.. setting:: HOST
 
-DATABASE_HOST
--------------
+HOST
+~~~~
 
 Default: ``''`` (Empty string)
 
@@ -222,7 +259,7 @@ localhost. Not used with SQLite.
 If this value starts with a forward slash (``'/'``) and you're using MySQL,
 MySQL will connect via a Unix socket to the specified socket. For example::
 
-    DATABASE_HOST = '/var/run/mysql'
+    "HOST": '/var/run/mysql'
 
 If you're using MySQL and this value *doesn't* start with a forward slash, then
 this value is assumed to be the host.
@@ -232,10 +269,10 @@ for the connection, rather than a network connection to localhost. If you
 explicitly need to use a TCP/IP connection on the local machine with
 PostgreSQL, specify ``localhost`` here.
 
-.. setting:: DATABASE_NAME
+.. setting:: NAME
 
-DATABASE_NAME
--------------
+NAME
+~~~~
 
 Default: ``''`` (Empty string)
 
@@ -243,44 +280,91 @@ The name of the database to use. For SQLite, it's the full path to the database
 file. When specifying the path, always use forward slashes, even on Windows
 (e.g. ``C:/homes/user/mysite/sqlite3.db``).
 
-.. setting:: DATABASE_OPTIONS
+.. setting:: OPTIONS
 
-DATABASE_OPTIONS
-----------------
+OPTIONS
+~~~~~~~
 
 Default: ``{}`` (Empty dictionary)
 
 Extra parameters to use when connecting to the database. Consult backend
 module's document for available keywords.
 
-.. setting:: DATABASE_PASSWORD
+.. setting:: PASSWORD
 
-DATABASE_PASSWORD
------------------
+PASSWORD
+~~~~~~~~
 
 Default: ``''`` (Empty string)
 
 The password to use when connecting to the database. Not used with SQLite.
 
-.. setting:: DATABASE_PORT
+.. setting:: PORT
 
-DATABASE_PORT
--------------
+PORT
+~~~~
 
 Default: ``''`` (Empty string)
 
 The port to use when connecting to the database. An empty string means the
 default port. Not used with SQLite.
 
-.. setting:: DATABASE_USER
+.. setting:: USER
 
-DATABASE_USER
--------------
+USER
+~~~~
 
 Default: ``''`` (Empty string)
 
 The username to use when connecting to the database. Not used with SQLite.
 
+.. setting:: TEST_CHARSET
+
+TEST_CHARSET
+~~~~~~~~~~~~
+
+Default: ``None``
+
+The character set encoding used to create the test database. The value of this
+string is passed directly through to the database, so its format is
+backend-specific.
+
+Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and
+MySQL_ (``mysql``) backends.
+
+.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
+.. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
+
+.. setting:: TEST_COLLATION
+
+TEST_COLLATION
+~~~~~~~~~~~~~~
+
+Default: ``None``
+
+The collation order to use when creating the test database. This value is
+passed directly to the backend, so its format is backend-specific.
+
+Only supported for the ``mysql`` backend (see `section 10.3.2`_ of the MySQL
+manual for details).
+
+.. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
+
+.. setting:: TEST_NAME
+
+TEST_NAME
+~~~~~~~~~
+
+Default: ``None``
+
+The name of database to use when running the test suite.
+
+If the default value (``None``) is used with the SQLite database engine, the
+tests will use a memory resident database. For all other database engines the
+test database will use the name ``'test_' + DATABASE_NAME``.
+
+See :ref:`topics-testing`.
+
 .. setting:: DATE_FORMAT
 
 DATE_FORMAT
@@ -1045,6 +1129,18 @@ See the :ref:`topics-http-sessions`.
 
 .. setting:: SESSION_EXPIRE_AT_BROWSER_CLOSE
 
+SESSION_DB_ALIAS
+----------------
+
+.. versionadded:: 1.2
+
+Default: ``None``
+
+If you're using database-backed session storage, this selects the database
+alias that will be used to store session data. By default, Django will use
+the ``default`` database, but you can store session data on any database
+you choose.
+
 SESSION_EXPIRE_AT_BROWSER_CLOSE
 -------------------------------
 
@@ -1169,56 +1265,6 @@ Default: ``''`` (Empty string)
 Output, as a string, that the template system should use for invalid (e.g.
 misspelled) variables. See :ref:`invalid-template-variables`..
 
-.. setting:: TEST_DATABASE_CHARSET
-
-TEST_DATABASE_CHARSET
----------------------
-
-.. versionadded:: 1.0
-
-Default: ``None``
-
-The character set encoding used to create the test database. The value of this
-string is passed directly through to the database, so its format is
-backend-specific.
-
-Supported for the PostgreSQL_ (``postgresql``, ``postgresql_psycopg2``) and MySQL_ (``mysql``) backends.
-
-.. _PostgreSQL: http://www.postgresql.org/docs/8.2/static/multibyte.html
-.. _MySQL: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
-
-.. setting:: TEST_DATABASE_COLLATION
-
-TEST_DATABASE_COLLATION
-------------------------
-
-.. versionadded:: 1.0
-
-Default: ``None``
-
-The collation order to use when creating the test database. This value is
-passed directly to the backend, so its format is backend-specific.
-
-Only supported for the ``mysql`` backend (see `section 10.3.2`_ of the MySQL
-manual for details).
-
-.. _section 10.3.2: http://www.mysql.org/doc/refman/5.0/en/charset-database.html
-
-.. setting:: TEST_DATABASE_NAME
-
-TEST_DATABASE_NAME
-------------------
-
-Default: ``None``
-
-The name of database to use when running the test suite.
-
-If the default value (``None``) is used with the SQLite database engine, the
-tests will use a memory resident database. For all other database engines the
-test database will use the name ``'test_' + settings.DATABASE_NAME``.
-
-See :ref:`topics-testing`.
-
 .. setting:: TEST_RUNNER
 
 TEST_RUNNER
@@ -1328,3 +1374,97 @@ Different locales have different formats. For example, U.S. English would say
 
 See :ttag:`allowed date format strings <now>`. See also ``DATE_FORMAT``,
 ``DATETIME_FORMAT``, ``TIME_FORMAT`` and ``MONTH_DAY_FORMAT``.
+
+Deprecated settings
+===================
+
+.. setting:: DATABASE_ENGINE
+
+DATABASE_ENGINE
+---------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`ENGINE` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_HOST
+
+DATABASE_HOST
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`HOST` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_NAME
+
+DATABASE_NAME
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`NAME` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_OPTIONS
+
+DATABASE_OPTIONS
+----------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`OPTIONS` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_PASSWORD
+
+DATABASE_PASSWORD
+-----------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`PASSWORD` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_PORT
+
+DATABASE_PORT
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`PORT` in
+   :setting:`DATABASES`.
+
+.. setting:: DATABASE_USER
+
+DATABASE_USER
+-------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`USER` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_CHARSET
+
+TEST_DATABASE_CHARSET
+---------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_CHARSET` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_COLLATION
+
+TEST_DATABASE_COLLATION
+-----------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_COLLATION` in
+   :setting:`DATABASES`.
+
+.. setting:: TEST_DATABASE_NAME
+
+TEST_DATABASE_NAME
+------------------
+
+.. deprecated:: 1.2
+   This setting has been replaced by :setting:`TEST_NAME` in
+   :setting:`DATABASES`.
+