Ticket #15888: 15888-docs.patch

docs/topics/cache.txt

@@ -159 +159 @@
 Database caching
 ----------------
 
-To use a database table as your cache backend, first create a cache table in
-your database by running this command::
+Django can store its cached data in your database. This works best if you've
+got a fast, well-indexed database server.
 
-    python manage.py createcachetable [cache_table_name]
+To use a database table as your cache backend:
 
-...where ``[cache_table_name]`` is the name of the database table to create.
-(This name can be whatever you want, as long as it's a valid table name that's
-not already being used in your database.) This command creates a single table
-in your database that is in the proper format that Django's database-cache
-system expects.
+    * Set :setting:`BACKEND <CACHES-BACKEND>` to
+      ``django.core.cache.backends.db.DatabaseCache``
+    * Set :setting:`LOCATION <CACHES-LOCATION>` to ``tablename``, the name of
+      the database table. This name can be whatever you want, as long as it's
+      a valid table name that's not already being used in your database.
 
-Once you've created that database table, set your
-:setting:`BACKEND <CACHES-BACKEND>` setting to
-``"django.core.cache.backends.db.DatabaseCache"``, and
-:setting:`LOCATION <CACHES-LOCATION>` to ``tablename`` -- the name of the
-database table. In this example, the cache table's name is ``my_cache_table``::
+In this example, the cache table's name is ``my_cache_table``::
 
     CACHES = {
         'default': {
@@ -183 +179 @@
         }
     }
 
+Creating the cache table
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-The database caching backend uses the same database as specified in your
-settings file. You can't use a different database backend for your cache table.
+Before using the database cache, you must create the cache table with this
+command::
 
-Database caching works best if you've got a fast, well-indexed database server.
+    python manage.py createcachetable
 
-Database caching and multiple databases
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This creates a table in your database that is in the proper format that
+Django's database-cache system expects. The name of the table is taken from
+:setting:`LOCATION <CACHES-LOCATION>`.
 
+If you are using multiple database caches, :djadmin:`createcachetable` creates
+one table for each cache.
+
+If you are using multiple databases, :djadmin:`createcachetable` observes the
+``allow_syncdb()`` method of your database routers (see below).
+
+Like :djadmin:`syncdb`, :djadmin:`createcachetable` won't touch an existing
+table. It will only create missing tables.
+
+.. versionchanged:: 1.4
+
+Before Django 1.4, :djadmin:`createcachetable` created one table at a time.
+You had to pass the name of the table you wanted to create in argument,
+and if you were using multiple databases, you had to use the
+:djadminopt:`--database` option. For backwards compatibility,
+this is still possible.
+
+Multiple databases
+~~~~~~~~~~~~~~~~~~
+
 If you use database caching with multiple databases, you'll also need
 to set up routing instructions for your database cache table. For the
 purposes of routing, the database cache table appears as a model named
@@ -247 +266 @@
         }
     }
 
-
 If you're on Windows, put the drive letter at the beginning of the path,
 like this::
 

docs/ref/django-admin.txt

@@ -111 +111 @@
 
 .. django-admin:: createcachetable
 
-Creates a cache table named ``tablename`` for use with the database cache
-backend. See :doc:`/topics/cache` for more information.
+Creates the cache tables for use with the database cache backend. See
+:doc:`/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.
 
+.. versionchanged:: 1.4
+
+It is no longer necessary to provide the cache table name in argument or the
+:djadminopt:`--database` option. Django takes this information from your
+settings file. If you have configured multiple caches or multiple databases,
+all the cache tables are created.
+
 dbshell
 -------