diff options
| author | ddelange <14880945+ddelange@users.noreply.github.com> | 2026-08-20 15:02:30 +0200 |
|---|---|---|
| committer | Sarah Boyce <42296566+sarahboyce@users.noreply.github.com> | 2026-09-15 17:19:27 +0200 |
| commit | 516d06e48fb5a4e7deb055ef578fa1272e86d326 (patch) | |
| tree | 5ce9d98dacabe1ac4ac1258280974a69659ff5ec /docs/ref | |
| parent | 97c38590a2396c8bb123d0782dbe96ddfd760a9a (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.txt | 25 |
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: |
