From 65aed2405cfd48cbb0193aa4a2ab19e9da982497 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Antoine=20M=C3=A9rino?= Date: Tue, 30 Dec 2025 22:06:21 +0100 Subject: [PATCH] Documentation: update notes for DB pool size (#11600) --- docs/configuration.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index cd5b8cf0a..adf34e2c6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -170,11 +170,18 @@ Available options are `postgresql` and `mariadb`. !!! note - A small pool is typically sufficient — for example, a size of 4. - Make sure your PostgreSQL server's max_connections setting is large enough to handle: - ```(Paperless workers + Celery workers) × pool size + safety margin``` - For example, with 4 Paperless workers and 2 Celery workers, and a pool size of 4: - (4 + 2) × 4 + 10 = 34 connections required. + A pool of 8-10 connections per worker is typically sufficient. + If you encounter error messages such as `couldn't get a connection` + or database connection timeouts, you probably need to increase the pool size. + + !!! warning + Make sure your PostgreSQL `max_connections` setting is large enough to handle the connection pools: + `(NB_PAPERLESS_WORKERS + NB_CELERY_WORKERS) × POOL_SIZE + SAFETY_MARGIN`. For example, with + 4 Paperless workers and 2 Celery workers, and a pool size of 8:``(4 + 2) × 8 + 10 = 58`, + so `max_connections = 60` (or even more) is appropriate. + + This assumes only Paperless-ngx connects to your PostgreSQL instance. If you have other applications, + you should increase `max_connections` accordingly. #### [`PAPERLESS_DB_READ_CACHE_ENABLED=`](#PAPERLESS_DB_READ_CACHE_ENABLED) {#PAPERLESS_DB_READ_CACHE_ENABLED}