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

docs/internals/contributing.txt

@@ -793,27 +793,53 @@ To run the tests, ``cd`` to the ``tests/`` directory and type:
     ./runtests.py --settings=path.to.django.settings
 
 Yes, the unit tests need a settings module, but only for database connection
-info, with the ``DATABASE_ENGINE`` setting.
+info. Your :setting:`DATABASES` setting needs to define two databases:
 
-If you're using the ``sqlite3`` database backend, no further settings are
-needed. A temporary database will be created in memory when running the tests.
+    * A ``default`` database. This database should use the backend that
+      you want to use for primary testing
 
-If you're using another backend:
+    * A database with the alias ``other``. The ``other`` database is
+      used to establish that queries can be directed to different
+      databases. As a result, this database can use any backend you
+      want. It doesn't need to use the same backend as the ``default``
+      database (although it can use the same backend if you want to).
 
-    * Your :setting:`DATABASE_USER` setting needs to specify an existing user account
-      for the database engine.
+If you're using the SQLite database backend, you need to define
+:setting:`ENGINE` for both databases, plus a
+:setting:`TEST_NAME` for the ``other`` database. The
+following is a minimal settings file that can be used to test SQLite::
 
-    * The :setting:`DATABASE_NAME` setting must be the name of an existing database to
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django.db.backends.sqlite3'
+        },
+        'other': {
+            'ENGINE': 'django.db.backends.sqlite3',
+            'TEST_NAME: 'other_db'
+        }
+    }
+
+
+If you're using another backend, you will need to provide other details for
+each database:
+
+    * The :setting:`USER` option for each of your databases needs to
+      specify an existing user account for the database.
+
+    * The :setting:`PASSWORD` option needs to provide the password for
+      the :setting:`USER` that has been specified.
+
+    * The :setting:`NAME` option must be the name of an existing database to
       which the given user has permission to connect. The unit tests will not
       touch this database; the test runner creates a new database whose name is
-      :setting:`DATABASE_NAME` prefixed with ``test_``, and this test database is
+      :setting:`NAME` prefixed with ``test_``, and this test database is
       deleted when the tests are finished. This means your user account needs
       permission to execute ``CREATE DATABASE``.
 
 You will also need to ensure that your database uses UTF-8 as the default
 character set. If your database server doesn't use UTF-8 as a default charset,
-you will need to include a value for ``TEST_DATABASE_CHARSET`` in your settings
-file.
+you will need to include a value for ``TEST_CHARSET`` in the settings
+dictionary for the applicable database.
 
 If you want to run the full suite of tests, you'll need to install a number of
 dependencies:

docs/internals/deprecation.txt

@@ -30,7 +30,19 @@ their deprecation, as per the :ref:`Django deprecation policy
           class in favor of a generic E-mail backend API.
 
         * The many to many SQL generation functions on the database backends
-          will be removed.  These have been deprecated since the 1.2 release.
+          will be removed.
+
+        * The ability to use the ``DATABASE_*`` family of top-level settings to
+          define database connections will be removed.
+
+        * The ability to use shorthand notation to specify a database backend
+          (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be
+          removed.
+
+        * The ``get_db_prep_save``, ``get_db_prep_value`` and
+          ``get_db_prep_lookup`` methods on Field were modified in 1.2 to support
+          multiple databases. In 1.4, the support functions that allow methods
+          with the old prototype to continue working will be removed.
 
         * The ``Message`` model (in ``django.contrib.auth``), its related
           manager in the ``User`` model (``user.message_set``), and the