[soc2009/multidb] Updated testing services to handle multiple databases better. Includes extra tests (some failing) for multiple database support. Patch from Russell Keith-Magee.

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

docs/internals/contributing.txt

@@ -752,20 +752,46 @@ 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 ``DATABASES`` 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 the ``DATABASE_USER`` option for each of your databases needs to
+If you're using the ``sqlite3`` database backend, you need to define
+:setting:`DATABASE_ENGINE` for both databases, plus a
+:setting:`TEST_DATABASE_NAME` for the ``other`` database. The
+following is a minimal settings file that can be used to test SQLite::
+
+    DATABASES = {
+        'default': {
+            'DATABASE_ENGINE': 'sqlite3'
+        },
+        'other': {
+            'DATABASE_ENGINE': 'sqlite3',
+            'TEST_DATABASE_NAME: 'other_db'
+        }
+    }
+
+
+If you're using another backend, you will need to provide other details for
+each database:
+
+    * The :setting:`DATABASE_USER` option for each of your databases needs to
       specify an existing user account for the database.
 
-    * The ``DATABASE_NAME`` option must be the name of an existing database to
+    * The :setting:`DATABASE_PASSWORD` option needs to provide the password for
+      the :setting:`DATABASE_USER` that has been specified.
+
+    * The :setting:`DATABASE_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
-      ``DATABASE_NAME`` prefixed with ``test_``, and this test database is
+      :setting:`DATABASE_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``.
 

docs/ref/settings.txt

@@ -202,11 +202,11 @@ Django.  It is a nested dictionary who's contents maps aliases to a dictionary
 containing the options for an individual database.  The following inner options
 are used:
 
-.. admonition:: Note
+.. deprecated: 1.2
 
-    In versions of Django prior to 1.2 each of the following were individual
-    settings, the usage of those has been deprecated but will be supported
-    until Django 1.4.
+    In versions of Django prior to 1.2 each of the following were
+    individual settings. The usage of the standalone database settings
+    has been deprecated, and will be removed in Django 1.4.
 
 .. setting:: DATABASE_ENGINE
 

docs/topics/testing.txt

@@ -1037,6 +1037,39 @@ URLconf for the duration of the test case.
 
 .. _emptying-test-outbox:
 
+Multi-database support
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. attribute:: TestCase.multi_db
+
+.. versionadded:: 1.2
+
+Django sets up a test database corresponding to every database that is
+defined in the :setting:``DATABASES`` definition in your settings
+file. However, a big part of the time taken to run a Django TestCase
+is consumed by the call to ``flush`` that ensures that you have a
+clean database at the start of each test run. If you have multiple
+databases, multiple flushes are required (one for each database),
+which can be a time consuming activity -- especially if your tests
+don't need to test multi-database activity.
+
+As an optimization, Django only flushes the ``default`` database at
+the start of each test run. If your setup contains multiple databases,
+and you have a test that requires every database to be clean, you can
+use the ``multi_db`` attribute on the test suite to request a full
+flush.
+
+For example::
+
+    class TestMyViews(TestCase):
+        multi_db = True
+
+        def testIndexPageView(self):
+            call_some_test_code()
+
+This test case will flush *all* the test databases before running
+``testIndexPageView``.
+
 Emptying the test outbox
 ~~~~~~~~~~~~~~~~~~~~~~~~