diff --git a/django/db/utils.py b/django/db/utils.py index 936b42039d5..e84060f9b3c 100644 --- a/django/db/utils.py +++ b/django/db/utils.py @@ -169,7 +169,7 @@ class ConnectionHandler(object): conn.setdefault('ENGINE', 'django.db.backends.dummy') if conn['ENGINE'] == 'django.db.backends.' or not conn['ENGINE']: conn['ENGINE'] = 'django.db.backends.dummy' - conn.setdefault('CONN_MAX_AGE', 600) + conn.setdefault('CONN_MAX_AGE', 0) conn.setdefault('OPTIONS', {}) conn.setdefault('TIME_ZONE', 'UTC' if settings.USE_TZ else settings.TIME_ZONE) for setting in ['NAME', 'USER', 'PASSWORD', 'HOST', 'PORT']: diff --git a/docs/howto/deployment/checklist.txt b/docs/howto/deployment/checklist.txt index b0920488708..b72be75497d 100644 --- a/docs/howto/deployment/checklist.txt +++ b/docs/howto/deployment/checklist.txt @@ -157,6 +157,15 @@ Performance optimizations Setting :setting:`DEBUG = False ` disables several features that are only useful in development. In addition, you can tune the following settings. +:setting:`CONN_MAX_AGE` +----------------------- + +Enabling `persistent database connections `_ +can result in a nice speed-up when connecting to the database accounts for a +significant part of the request processing time. + +This helps a lot on virtualized hosts with limited network performance. + :setting:`TEMPLATE_LOADERS` --------------------------- diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 2ef048216f6..7555acaabab 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -22,14 +22,14 @@ 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. +the database in each request. They're controlled by the +:setting:`CONN_MAX_AGE` parameter which defines the maximum lifetime of a +connection. It can be set independently for each database. -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``. +The default value is ``0``, preserving the historical behavior of closing the +database connection at the end of each request. To enable persistent +connections, set :setting:`CONN_MAX_AGE` to a positive number of seconds. For +unlimited persistent connections, set it to ``None``. Connection management ~~~~~~~~~~~~~~~~~~~~~ @@ -64,13 +64,22 @@ 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. +In such cases, you should set :setting:`CONN_MAX_AGE` to a low 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. +negating the effect of persistent connections. Don't enable them during +development. + +When Django establishes a connection to the database, it sets up appropriate +parameters, depending on the backend being used. If you enable persistent +connections, this setup is no longer repeated every request. If you modify +parameters such as the connection's isolation level or time zone, you should +either restore Django's defaults at the end of each request, force an +appropriate value at the beginning of each request, or disable persistent +connections. .. _postgresql-notes: diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index f2d418d4d95..04b42aeeb27 100644 --- a/docs/ref/settings.txt +++ b/docs/ref/settings.txt @@ -509,7 +509,7 @@ CONN_MAX_AGE .. versionadded:: 1.6 -Default: ``600`` +Default: ``0`` 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 diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt index 3e15f5b7671..611b6614158 100644 --- a/docs/releases/1.6.txt +++ b/docs/releases/1.6.txt @@ -66,13 +66,8 @@ 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. +each request. For backwards compatibility, this feature is disabled by +default. See :ref:`persistent-database-connections` for details. Time zone aware aggregation ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -298,21 +293,6 @@ Django 1.6 introduces ``hour``, ``minute``, and ``second`` lookups on ``hour``, ``minute``, or ``second``, the new lookups will clash with you field names. Append an explicit :lookup:`exact` lookup if this is an issue. -Persistent database connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Connection setup not repeated for each request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When Django establishes a connection to the database, it sets up appropriate -parameters, depending on the backend being used. Since `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, force an -appropriate value at the beginning of each request, or disable persistent -connections. - ``BooleanField`` no longer defaults to ``False`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~