From 1dd0519a38b8743b91cb8189575622cfd20c3e39 Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Wed, 21 Jan 2026 22:10:12 +0200 Subject: [PATCH] docs: clarify `max_connections` implications (#21596) Signed-off-by: Danny Kopping --- docs/tutorials/best-practices/scale-coder.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/best-practices/scale-coder.md b/docs/tutorials/best-practices/scale-coder.md index b87d809fc3..87e3c3ced3 100644 --- a/docs/tutorials/best-practices/scale-coder.md +++ b/docs/tutorials/best-practices/scale-coder.md @@ -221,13 +221,19 @@ give specific sizing recommendations for various user scales. ### Connection pool tuning Coder Server maintains a pool of connections to PostgreSQL. You can tune the -pool size with these settings: +pool size with the following settings: + +> [!NOTE] +> When adjusting these settings, please ensure that your PostgreSQL Server has `max_connections` +> set appropriately to accommodate all Coder Server replicas multiplied by the +> maximum number of open connections. We recommend configuring an additional 20% +> of connections to account for churn and other clients. +> +> Also note that increasing `max_connections` will result in potentially higher +> CPU and RAM usage, so you'll need to monitor accordingly. - `--postgres-conn-max-open` (env: `CODER_PG_CONN_MAX_OPEN`): Maximum number of open - connections. Default: 10. Ensure that your PostgreSQL Server has `max_connections` - set appropriately to accommodate all Coder Server replicas multiplied by the - maximum number of open connections. We recommend configuring an additional 20% - of connections to account for churn and other clients. + connections. Default: 10. - `--postgres-conn-max-idle` (env: `CODER_PG_CONN_MAX_IDLE`): Maximum number of idle connections kept in the pool. Default: "auto", which uses max open / 3.