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

5 files changed, 446 insertions, 144 deletions

diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index d7ae120f94..8b473da821 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -44,18 +44,20 @@ Autocommit mode
 
 .. versionadded:: 1.1
 
-If your application is particularly read-heavy and doesn't make many database
-writes, the overhead of a constantly open transaction can sometimes be
-noticeable. For those situations, if you're using the ``postgresql_psycopg2``
-backend, you can configure Django to use *"autocommit"* behavior for the
-connection, meaning that each database operation will normally be in its own
-transaction, rather than having the transaction extend over multiple
-operations. In this case, you can still manually start a transaction if you're
-doing something that requires consistency across multiple database operations.
-The autocommit behavior is enabled by setting the ``autocommit`` key in the
-:setting:`DATABASE_OPTIONS` setting::
+If your application is particularly read-heavy and doesn't make many
+database writes, the overhead of a constantly open transaction can
+sometimes be noticeable. For those situations, if you're using the
+``postgresql_psycopg2`` backend, you can configure Django to use
+*"autocommit"* behavior for the connection, meaning that each database
+operation will normally be in its own transaction, rather than having
+the transaction extend over multiple operations. In this case, you can
+still manually start a transaction if you're doing something that
+requires consistency across multiple database operations. The
+autocommit behavior is enabled by setting the ``autocommit`` key in
+the :setting:`OPTIONS` part of your database configuration in
+:setting:`DATABASES`::
 
-    DATABASE_OPTIONS = {
+    OPTIONS = {
         "autocommit": True,
     }
 
@@ -67,11 +69,11 @@ objects are changed or none of them are.
 .. admonition:: This is database-level autocommit
 
     This functionality is not the same as the
-    :ref:`topics-db-transactions-autocommit` decorator. That decorator is a
-    Django-level implementation that commits automatically after data changing
-    operations. The feature enabled using the :setting:`DATABASE_OPTIONS`
-    settings provides autocommit behavior at the database adapter level. It
-    commits after *every* operation.
+    :ref:`topics-db-transactions-autocommit` decorator. That decorator
+    is a Django-level implementation that commits automatically after
+    data changing operations. The feature enabled using the
+    :setting:`OPTIONS` option provides autocommit behavior at the
+    database adapter level. It commits after *every* operation.
 
 If you are using this feature and performing an operation akin to delete or
 updating that requires multiple operations, you are strongly recommended to
@@ -249,29 +251,33 @@ Refer to the :ref:`settings documentation <ref-settings>`.
 
 Connection settings are used in this order:
 
-    1. :setting:`DATABASE_OPTIONS`.
-    2. :setting:`DATABASE_NAME`, :setting:`DATABASE_USER`,
-       :setting:`DATABASE_PASSWORD`, :setting:`DATABASE_HOST`,
-       :setting:`DATABASE_PORT`
+    1. :setting:`OPTIONS`.
+    2. :setting:`NAME`, :setting:`USER`, :setting:`PASSWORD`,
+       :setting:`HOST`, :setting:`PORT`
     3. MySQL option files.
 
-In other words, if you set the name of the database in ``DATABASE_OPTIONS``,
-this will take precedence over ``DATABASE_NAME``, which would override
+In other words, if you set the name of the database in ``OPTIONS``,
+this will take precedence over ``NAME``, which would override
 anything in a `MySQL option file`_.
 
 Here's a sample configuration which uses a MySQL option file::
 
     # settings.py
-    DATABASE_ENGINE = "mysql"
-    DATABASE_OPTIONS = {
-        'read_default_file': '/path/to/my.cnf',
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.mysql',
+            'OPTIONS': {
+                'read_default_file': '/path/to/my.cnf',
+            },
+        }
     }
 
+
     # my.cnf
     [client]
-    database = DATABASE_NAME
-    user = DATABASE_USER
-    password = DATABASE_PASSWORD
+    database = NAME
+    user = USER
+    password = PASSWORD
     default-character-set = utf8
 
 Several other MySQLdb connection options may be useful, such as ``ssl``,
@@ -302,7 +308,7 @@ storage engine, you have a couple of options.
     * Another option is to use the ``init_command`` option for MySQLdb prior to
       creating your tables::
 
-          DATABASE_OPTIONS = {
+          OPTIONS = {
              "init_command": "SET storage_engine=INNODB",
           }
 
@@ -467,7 +473,7 @@ If you're getting this error, you can solve it by:
     * Increase the default timeout value by setting the ``timeout`` database
       option option::
 
-          DATABASE_OPTIONS = {
+          OPTIONS = {
               # ...
              "timeout": 20,
               # ...
@@ -520,25 +526,34 @@ Connecting to the database
 
 Your Django settings.py file should look something like this for Oracle::
 
-    DATABASE_ENGINE = 'oracle'
-    DATABASE_NAME = 'xe'
-    DATABASE_USER = 'a_user'
-    DATABASE_PASSWORD = 'a_password'
-    DATABASE_HOST = ''
-    DATABASE_PORT = ''
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.oracle',
+            'NAME': 'xe',
+            'USER': 'a_user',
+            'PASSWORD': 'a_password',
+            'HOST': '',
+            'PORT': ''     ,
+        }
+    }
+
 
 If you don't use a ``tnsnames.ora`` file or a similar naming method that
 recognizes the SID ("xe" in this example), then fill in both
-:setting:`DATABASE_HOST` and :setting:`DATABASE_PORT` like so::
+``HOST`` and ``PORT`` like so::
 
-    DATABASE_ENGINE = 'oracle'
-    DATABASE_NAME = 'xe'
-    DATABASE_USER = 'a_user'
-    DATABASE_PASSWORD = 'a_password'
-    DATABASE_HOST = 'dbprod01ned.mycompany.com'
-    DATABASE_PORT = '1540'
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.oracle',
+            'NAME': 'xe',
+            'USER': 'a_user',
+            'PASSWORD': 'a_password',
+            'HOST': 'dbprod01ned.mycompany.com',
+            'PORT': '1540',
+        }
+    }
 
-You should supply both :setting:`DATABASE_HOST` and :setting:`DATABASE_PORT`, or leave both
+You should supply both ``HOST`` and ``PORT``, or leave both
 as empty strings.
 
 Tablespace options
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 2b7af17f1e..f5cab244bf 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -121,6 +121,11 @@ createcachetable
 Creates a cache table named ``tablename`` for use with the database cache
 backend. See :ref:`topics-cache` for more information.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the cachetable will be installed.
+
 createsuperuser
 ---------------
 
@@ -155,8 +160,8 @@ dbshell
 .. django-admin:: dbshell
 
 Runs the command-line client for the database engine specified in your
-``DATABASE_ENGINE`` setting, with the connection parameters specified in your
-``DATABASE_USER``, ``DATABASE_PASSWORD``, etc., settings.
+``ENGINE`` setting, with the connection parameters specified in your
+``USER``, ``PASSWORD``, etc., settings.
 
     * For PostgreSQL, this runs the ``psql`` command-line client.
     * For MySQL, this runs the ``mysql`` command-line client.
@@ -167,6 +172,12 @@ the program name (``psql``, ``mysql``, ``sqlite3``) will find the program in
 the right place. There's no way to specify the location of the program
 manually.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which to open a shell.
+
+
 diffsettings
 ------------
 
@@ -199,21 +210,6 @@ records to dump. If you're using a :ref:`custom manager <custom-managers>` as
 the default manager and it filters some of the available records, not all of the
 objects will be dumped.
 
-.. django-admin-option:: --exclude
-
-.. versionadded:: 1.0
-
-Exclude a specific application from the applications whose contents is
-output. For example, to specifically exclude the `auth` application from
-the output, you would call::
-
-    django-admin.py dumpdata --exclude=auth
-
-If you want to exclude multiple applications, use multiple ``--exclude``
-directives::
-
-    django-admin.py dumpdata --exclude=auth --exclude=contenttypes
-
 .. django-admin-option:: --format <fmt>
 
 By default, ``dumpdata`` will format its output in JSON, but you can use the
@@ -226,6 +222,11 @@ By default, ``dumpdata`` will output all data on a single line. This isn't
 easy for humans to read, so you can use the ``--indent`` option to
 pretty-print the output with a number of indentation spaces.
 
+.. versionadded:: 1.0
+
+The :djadminopt:`--exclude` option may be provided to prevent specific
+applications from being dumped.
+
 .. versionadded:: 1.1
 
 In addition to specifying application names, you can provide a list of
@@ -234,6 +235,11 @@ name to ``dumpdata``, the dumped output will be restricted to that model,
 rather than the entire application. You can also mix application names and
 model names.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the data will be loaded.
+
 .. django-admin-option:: --natural
 
 .. versionadded:: 1.2
@@ -244,7 +250,6 @@ a natural key definition. If you are dumping ``contrib.auth`` ``Permission``
 objects or ``contrib.contenttypes`` ``ContentType`` objects, you should
 probably be using this flag.
 
-
 flush
 -----
 
@@ -258,13 +263,19 @@ fixture will be re-installed.
 The :djadminopt:`--noinput` option may be provided to suppress all user
 prompts.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option may be used to specify the database
+to flush.
+
+
 inspectdb
 ---------
 
 .. django-admin:: inspectdb
 
 Introspects the database tables in the database pointed-to by the
-``DATABASE_NAME`` setting and outputs a Django model module (a ``models.py``
+``NAME`` setting and outputs a Django model module (a ``models.py``
 file) to standard output.
 
 Use this if you have a legacy database with which you'd like to use Django.
@@ -301,6 +312,12 @@ needed.
 ``inspectdb`` works with PostgreSQL, MySQL and SQLite. Foreign-key detection
 only works in PostgreSQL and with certain types of MySQL tables.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option may be used to specify the
+database to introspect.
+
+
 loaddata <fixture fixture ...>
 ------------------------------
 
@@ -308,6 +325,11 @@ loaddata <fixture fixture ...>
 
 Searches for and loads the contents of the named fixture into the database.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database
+onto which the data will be loaded.
+
 What's a "fixture"?
 ~~~~~~~~~~~~~~~~~~~
 
@@ -389,6 +411,37 @@ installation will be aborted, and any data installed in the call to
     references in your data files - MySQL doesn't provide a mechanism to
     defer checking of row constraints until a transaction is committed.
 
+Database-specific fixtures
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are in a multi-database setup, you may have fixture data that
+you want to load onto one database, but not onto another. In this
+situation, you can add database identifier into . If your
+:setting:`DATABASES` setting has a 'master' database defined, you can
+define the fixture ``mydata.master.json`` or
+``mydata.master.json.gz``. This fixture will only be loaded if you
+have specified that you want to load data onto the ``master``
+database.
+
+Excluding applications from loading
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+The :djadminopt:`--exclude` option may be provided to prevent specific
+applications from being loaded.
+
+For example, if you wanted to exclude models from ``django.contrib.auth``
+from being loaded into your database, you would call::
+
+    django-admin.py loaddata mydata.json --exclude auth
+
+This will look for for a JSON fixture called ``mydata`` in all the
+usual locations - including the ``fixtures`` directory of the
+``django.contrib.auth`` application. However, any fixture object that
+identifies itself as belonging to the ``auth`` application (e.g.,
+instance of ``auth.User``) would be ignored by loaddata.
+
 makemessages
 ------------
 
@@ -450,6 +503,11 @@ Executes the equivalent of ``sqlreset`` for the given app name(s).
 The :djadminopt:`--noinput` option may be provided to suppress all user
 prompts.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the alias
+of the database to reset.
+
 runfcgi [options]
 -----------------
 
@@ -567,6 +625,11 @@ sql <appname appname ...>
 
 Prints the CREATE TABLE SQL statements for the given app name(s).
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlall <appname appname ...>
 ----------------------------
 
@@ -577,6 +640,11 @@ Prints the CREATE TABLE and initial-data SQL statements for the given app name(s
 Refer to the description of ``sqlcustom`` for an explanation of how to
 specify initial data.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlclear <appname appname ...>
 ------------------------------
 
@@ -584,6 +652,11 @@ sqlclear <appname appname ...>
 
 Prints the DROP TABLE SQL statements for the given app name(s).
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlcustom <appname appname ...>
 -------------------------------
 
@@ -605,6 +678,11 @@ table modifications, or insert any SQL functions into the database.
 
 Note that the order in which the SQL files are processed is undefined.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlflush
 --------
 
@@ -613,6 +691,11 @@ sqlflush
 Prints the SQL statements that would be executed for the :djadmin:`flush`
 command.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlindexes <appname appname ...>
 --------------------------------
 
@@ -620,6 +703,11 @@ sqlindexes <appname appname ...>
 
 Prints the CREATE INDEX SQL statements for the given app name(s).
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlreset <appname appname ...>
 ------------------------------
 
@@ -627,6 +715,11 @@ sqlreset <appname appname ...>
 
 Prints the DROP TABLE SQL, then the CREATE TABLE SQL, for the given app name(s).
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 sqlsequencereset <appname appname ...>
 --------------------------------------
 
@@ -640,6 +733,11 @@ number for automatically incremented fields.
 Use this command to generate SQL which will fix cases where a sequence is out
 of sync with its automatically incremented field data.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database for
+which to print the SQL.
+
 startapp <appname>
 ------------------
 
@@ -696,9 +794,16 @@ with an appropriate extension (e.g. ``json`` or ``xml``). See the
 documentation for ``loaddata`` for details on the specification of fixture
 data files.
 
+--noinput
+~~~~~~~~~
 The :djadminopt:`--noinput` option may be provided to suppress all user
 prompts.
 
+.. versionadded:: 1.2
+
+The :djadminopt:`--database` option can be used to specify the database to
+synchronize.
+
 test <app or test identifier>
 -----------------------------
 
@@ -848,6 +953,30 @@ Common options
 The following options are not available on every commands, but they are
 common to a number of commands.
 
+.. django-admin-option:: --database
+
+.. versionadded:: 1.2
+
+Used to specify the database on which a command will operate. If not
+specified, this option will default to an alias of ``default``.
+
+For example, to dump data from the database with the alias ``master``::
+
+    django-admin.py dumpdata --database=master
+
+.. django-admin-option:: --exclude
+
+Exclude a specific application from the applications whose contents is
+output. For example, to specifically exclude the `auth` application from
+the output of dumpdata, you would call::
+
+    django-admin.py dumpdata --exclude=auth
+
+If you want to exclude multiple applications, use multiple ``--exclude``
+directives::
+
+    django-admin.py dumpdata --exclude=auth --exclude=contenttypes
+
 .. django-admin-option:: --locale
 
 Use the ``--locale`` or ``-l`` option to specify the locale to process.
diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt
index d74f8350e8..f3e7363e36 100644
--- a/docs/ref/models/options.txt
+++ b/docs/ref/models/options.txt
@@ -4,8 +4,9 @@
 Model ``Meta`` options
 ======================
 
-This document explains all the possible :ref:`metadata options <meta-options>`  that you can give your model in its internal
-``class Meta``.
+This document explains all the possible :ref:`metadata options
+<meta-options>` that you can give your model in its internal ``class
+Meta``.
 
 Available ``Meta`` options
 ==========================
@@ -242,4 +243,3 @@ The plural name for the object::
     verbose_name_plural = "stories"
 
 If this isn't given, Django will use :attr:`~Options.verbose_name` + ``"s"``.
-
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index e685472cca..45f1c3161b 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -874,6 +874,24 @@ logically::
     # existing set of fields).
     Entry.objects.defer("body").only("headline", "body")
 
+``using(alias)``
+~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 1.2
+
+This method is for controlling which database the ``QuerySet`` will be
+evaluated against if you are using more than one database.  The only argument
+this method takes is the alias of a database, as defined in
+:setting:`DATABASES`.
+
+For example::
+
+    # queries the database with the 'default' alias.
+    >>> Entry.objects.all()
+
+    # queries the database with the 'backup' alias
+    >>> Entry.objects.using('backup')
+
 
 QuerySet methods that do not return QuerySets
 ---------------------------------------------
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`.
+