Changing the `max_connections` parameter for PostgreSQL on a Single Installation of SimpleOne

General topics
1

Changing the max_connections Parameter for PostgreSQL on a Single Installation of SimpleOne

:stop_sign: Database operations are potentially unsafe. Any configuration changes must be tested on dev, test, or sandbox instances before applying to production environments.

Risks of Setting max_connections Too High

Each connection in PostgreSQL is a separate server process that consumes RAM even when idle. Excessively increasing this parameter may lead to:

  • OOM (Out of Memory) — The Linux kernel will forcibly terminate the PostgreSQL process due to insufficient RAM, causing a complete database outage
  • Performance degradation — Excessive processes increase contention for locks and cause constant CPU context switching, slowing down all queries
  • Unstable instance behavior — Even idle connections reserve resources, reducing memory available for caches and query execution

:open_book: Official documentation: postgresql.org — Connection Settings

1. Check Current Value

Before making changes, verify the current setting.

From the host — via PostgreSQL:

docker exec -it postgres su - postgres -c 'psql -c "SHOW max_connections;"'

From the host — via Patroni:

docker exec -it postgres su - postgres -c 'patronictl show-config | grep max_connections'

2. Modify the Parameter via Patroni

Log in from the host to the container as the postgres user:

docker exec -it postgres su - postgres

All subsequent commands must be executed inside the container.

Launch the Patroni configuration editor:

patronictl edit-config

The cluster configuration will open. Locate the postgresql.parameters section and modify the max_connections value:

postgresql:
  parameters:
    ...
    max_connections: 100          # <-- change this value
    ...

Save the file and exit the editor. Patroni will display the changes and prompt for confirmation:

-    max_connections: 100
+    max_connections: 200

Apply these changes? [y/N]: y
Configuration changed

3. Restart the Cluster

The max_connections parameter requires a PostgreSQL restart.

:warning: Warning: Restarting the cluster causes brief downtime!
Schedule this operation during a pre-approved maintenance window.

Inside the container, run patronictl list to identify the cluster name and confirm that * appears under the Pending restart column:

patronictl list
+ Cluster: postgres-firsulov
+--------------------------+------------+--------+---------+----+-------+-----------------+
| Member                   | Host       | Role   | State   | TL | Lag   | Pending restart |
+--------------------------+------------+--------+---------+----+-------+-----------------+
| postgres-single-inst-prod| 172.25.0.3 | Leader | running |  5 |       | *               |
+--------------------------+------------+--------+---------+----+-------+-----------------+

:pushpin: The cluster name is listed under + Cluster: — in this example, it is postgres-firsulov.

Restart the cluster by specifying the cluster name:

patronictl restart postgres-firsulov

Patroni will ask several questions in sequence — answer them as follows:

When should the restart take place (e.g. 2026-02-20T12:59) [now]:          # press Enter
Are you sure you want to restart members postgres-single-instance-prod?
[y/N]: y                                                                   # type y
Restart if the PostgreSQL version is less than provided (e.g. 9.5.2) []:   # press Enter
Success: restart on member postgres-single-instance-prod

4. Verify After Restart

Confirm inside the container that the new value has been applied:

psql -c "SHOW max_connections;"

patronictl show-config | grep max_connections

Both outputs must match the value you set in Step 2.

Quick Reference Cheat Sheet

Step Location Command
View current value Host docker exec -it postgres su - postgres -c 'psql -c "SHOW max_connections;"'
View Patroni config Host `docker exec -it postgres su - postgres -c 'patronictl show-config
Enter container Host docker exec -it postgres su - postgres
Modify parameter Container patronictl edit-config
Find cluster name Container patronictl list
Restart cluster to apply changes (causes downtime) Container patronictl restart <CLUSTER_NAME>
1 Like