summaryrefslogtreecommitdiff
path: root/docs/ref
diff options
context:
space:
mode:
authorddelange <14880945+ddelange@users.noreply.github.com>2026-08-20 15:02:30 +0200
committerSarah Boyce <42296566+sarahboyce@users.noreply.github.com>2026-09-15 17:19:27 +0200
commit516d06e48fb5a4e7deb055ef578fa1272e86d326 (patch)
tree5ce9d98dacabe1ac4ac1258280974a69659ff5ec /docs/ref
parent97c38590a2396c8bb123d0782dbe96ddfd760a9a (diff)
Fixed #37283 -- Clarified PostgreSQL connection pooling configuration.
Documented its interaction with CONN_MAX_AGE and CONN_HEALTH_CHECKS.
Diffstat (limited to 'docs/ref')
-rw-r--r--docs/ref/databases.txt25
1 files changed, 19 insertions, 6 deletions
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt
index 3e0fa27600..62c2617ded 100644
--- a/docs/ref/databases.txt
+++ b/docs/ref/databases.txt
@@ -254,10 +254,18 @@ database configuration in :setting:`DATABASES`::
Connection pool
---------------
-To use a connection pool with `psycopg`_, you can either set ``"pool"`` in the
-:setting:`OPTIONS` part of your database configuration in :setting:`DATABASES`
-to be a dict to be passed to :class:`~psycopg:psycopg_pool.ConnectionPool`, or
-to ``True`` to use the ``ConnectionPool`` defaults::
+Connection pooling allows connections to be reused across threads, reducing
+connection setup overhead. When enabled, Django maintains a separate pool for
+each database alias in each process. Closing a Django database connection
+returns it to the pool for reuse.
+
+Connection pooling is supported only with `psycopg`_ and requires
+``psycopg[pool]`` (which installs :pypi:`psycopg-pool`).
+
+To enable connection pooling, set ``"pool"`` in the :setting:`OPTIONS` part of
+your database configuration in :setting:`DATABASES` to a dictionary of options
+to pass to :class:`~psycopg:psycopg_pool.ConnectionPool`, or to ``True`` to use
+the :class:`~psycopg:psycopg_pool.ConnectionPool` defaults::
DATABASES = {
"default": {
@@ -269,8 +277,13 @@ to ``True`` to use the ``ConnectionPool`` defaults::
},
}
-This option requires ``psycopg[pool]`` or :pypi:`psycopg-pool` to be installed
-and is ignored with ``psycopg2``.
+The :setting:`CONN_MAX_AGE` setting must be ``0`` when connection pooling is
+enabled. Configure connection lifetime with the ``max_lifetime`` pool option
+instead.
+
+Unless a ``check`` callback is provided in the pool options,
+:setting:`CONN_HEALTH_CHECKS` determines whether connections are checked when
+retrieved from the pool.
.. _database-server-side-parameters-binding: