From 516d06e48fb5a4e7deb055ef578fa1272e86d326 Mon Sep 17 00:00:00 2001 From: ddelange <14880945+ddelange@users.noreply.github.com> Date: Thu, 20 Aug 2026 15:02:30 +0200 Subject: Fixed #37283 -- Clarified PostgreSQL connection pooling configuration. Documented its interaction with CONN_MAX_AGE and CONN_HEALTH_CHECKS. --- docs/ref/databases.txt | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) (limited to 'docs/ref') 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: -- cgit v1.3