Implemented persistent database connections.

Thanks Anssi Kääriäinen and Karen Tracey for their inputs.

4 files changed, 98 insertions, 0 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index f1ae1338df..3a9cbd195d 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -339,6 +339,8 @@ these changes.
 
 * ``Model._meta.module_name`` was renamed to ``model_name``.
 
+* The private API ``django.db.close_connection`` will be removed.
+
 2.0
 ---
 
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index e933ee350d..34f60e99ac 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -11,6 +11,68 @@ This file describes some of the features that might be relevant to Django
 usage. Of course, it is not intended as a replacement for server-specific
 documentation or reference manuals.
 
+General notes
+=============
+
+.. _persistent-database-connections:
+
+Persistent connections
+----------------------
+
+.. versionadded:: 1.6
+
+Persistent connections avoid the overhead of re-establishing a connection to
+the database in each request. By default, connections are kept open for up 10
+minutes — if not specified, :setting:`CONN_MAX_AGE` defaults to 600 seconds.
+
+Django 1.5 and earlier didn't have persistent connections. To restore the
+legacy behavior of closing the connection at the end of every request, set
+:setting:`CONN_MAX_AGE` to ``0``.
+
+For unlimited persistent connections, set :setting:`CONN_MAX_AGE` to ``None``.
+
+Connection management
+~~~~~~~~~~~~~~~~~~~~~
+
+Django opens a connection to the database when it first makes a database
+query. It keeps this connection open and reuses it in subsequent requests.
+Django closes the connection once it exceeds the maximum age defined by
+:setting:`CONN_MAX_AGE` or when it isn't usable any longer.
+
+In detail, Django automatically opens a connection to the database whenever it
+needs one and doesn't have one already — either because this is the first
+connection, or because the previous connection was closed.
+
+At the beginning of each request, Django closes the connection if it has
+reached its maximum age. If your database terminates idle connections after
+some time, you should set :setting:`CONN_MAX_AGE` to a lower value, so that
+Django doesn't attempt to use a connection that has been terminated by the
+database server. (This problem may only affect very low traffic sites.)
+
+At the end of each request, Django closes the connection if it has reached its
+maximum age or if it is in an unrecoverable error state. If any database
+errors have occurred while processing the requests, Django checks whether the
+connection still works, and closes it if it doesn't. Thus, database errors
+affect at most one request; if the connection becomes unusable, the next
+request gets a fresh connection.
+
+Caveats
+~~~~~~~
+
+Since each thread maintains its own connection, your database must support at
+least as many simultaneous connections as you have worker threads.
+
+Sometimes a database won't be accessed by the majority of your views, for
+example because it's the database of an external system, or thanks to caching.
+In such cases, you should set :setting:`CONN_MAX_AGE` to a lower value, or
+even ``0``, because it doesn't make sense to maintain a connection that's
+unlikely to be reused. This will help keep the number of simultaneous
+connections to this database small.
+
+
+The development server creates a new thread for each request it handles,
+negating the effect of persistent connections.
+
 .. _postgresql-notes:
 
 PostgreSQL notes
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index bba936d837..baeb02c32d 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -464,6 +464,19 @@ 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:: CONN_MAX_AGE
+
+CONN_MAX_AGE
+~~~~~~~~~~~~
+
+.. versionadded:: 1.6
+
+Default: ``600``
+
+The lifetime of a database connection, in seconds. Use ``0`` to close database
+connections at the end of each request — Django's historical behavior — and
+``None`` for unlimited persistent connections.
+
 .. setting:: OPTIONS
 
 OPTIONS
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index c6a4fb2d5d..34fa687290 100644
--- a/docs/releases/1.6.txt
+++ b/docs/releases/1.6.txt
@@ -30,6 +30,19 @@ prevention <clickjacking-prevention>` are turned on.
 If the default templates don't suit your tastes, you can use :ref:`custom
 project and app templates <custom-app-and-project-templates>`.
 
+Persistent database connections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django now supports reusing the same database connection for several requests.
+This avoids the overhead of re-establishing a connection at the beginning of
+each request.
+
+By default, database connections will kept open for 10 minutes. This behavior
+is controlled by the :setting:`CONN_MAX_AGE` setting. To restore the previous
+behavior of closing the connection at the end of each request, set
+:setting:`CONN_MAX_AGE` to ``0``. See :ref:`persistent-database-connections`
+for details.
+
 Time zone aware aggregation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -136,6 +149,14 @@ Backwards incompatible changes in 1.6
 * Model fields named ``hour``, ``minute`` or ``second`` may clash with the new
   lookups. Append an explicit :lookup:`exact` lookup if this is an issue.
 
+* When Django establishes a connection to the database, it sets up appropriate
+  parameters, depending on the backend being used. Since `persistent database
+  connections <persistent-database-connections>`_ are enabled by default in
+  Django 1.6, this setup isn't repeated at every request any more. If you
+  modifiy parameters such as the connection's isolation level or time zone,
+  you should either restore Django's defaults at the end of each request, or
+  force an appropriate value at the beginning of each request.
+
 * If your CSS/Javascript code used to access HTML input widgets by type, you
   should review it as ``type='text'`` widgets might be now output as
   ``type='email'``, ``type='url'`` or ``type='number'`` depending on their