PostgreSQL Connection Budget: Leave Room for the Rollout
Small connection pools can exceed PostgreSQL’s limit when services scale or releases overlap. Build a shared budget, preserve operational headroom, and compare client waiting with server sessions.
DM
Imagine a release that adds two API processes while the old ones finish their requests. Nothing looks extravagant: each API process allows ten database connections, and the background workers have small pools too. Yet the release can still run into PostgreSQL’s connection limit. The database sees the combined demand, including the old and new processes that coexist.
Before increasing max_connections, budget the maximum connections from every application pool at peak deployment overlap. Keep an explicit allowance for operations and reserved access, then compare that plan with both client-side waiting and server-side sessions. Passing the arithmetic means the plan fits a connection allowance. It doesn’t prove the database can run that much work efficiently.
Start with the server’s actual admission settings
This walkthrough assumes PostgreSQL 18 and ordinary application roles connecting directly to it. PostgreSQL’s connection settings define max_connections, privileged reserved_connections and superuser_reserved_connections. The maximum is a server-wide setting, not a separate allowance for each database. Raising it requires a server start and increases resources allocated from that setting, including shared memory.
SELECT name, setting, pending_restart
FROM pg_settings
WHERE name IN (
'max_connections',
'reserved_connections',
'superuser_reserved_connections'
)
ORDER BY name;Use a role permitted to inspect the relevant settings. Read the documentation for your installed major version; reservation settings differ across versions. For this budget, application roles do not have superuser or reserved-connection privileges. Don’t give them those privileges to make a failing budget pass. Preserve that access for its intended purpose.
Next, write down an operational allowance for connections outside the application pools: monitoring, a migration job, maintenance tools and the connections you need to diagnose trouble. This is your planning choice, separate from PostgreSQL’s enforced reserved slots. Count each consumer once. Replication and other special connection types need their own documented limits and accounting; a tally of ordinary client sessions is not a complete inventory of every backend.
Put the rollout in the ledger
Here is invented arithmetic, not a measurement from a Krova customer. Suppose the inspected maximum is 100, privileged reservations total 5, and you deliberately leave 15 ordinary connections for operations and uncertainty. That leaves an application-pool allowance of 100 − 5 − 15 = 80. None of these values is a recommended production default.
| Consumer | Normal processes | Pool maximum per process | Normal ceiling | Extra ceiling during API rollout |
|---|---|---|---|---|
| API | 4 | 10 | 40 | 20 from 2 additional processes |
| Background workers | 3 | 8 | 24 | 0 in this example |
| Application total | 64 | 20 | ||
| Peak during this rollout | 84 |
The steady state fits the allowance, but the rollout does not: 64 + 20 = 84, four above 80. If workers also overlap, add their extra pools as well. Count processes that own pools, not just VMs or container names. One container can launch several processes; one process can create several independent pools.
The node-postgres pool-sizing guide explicitly calls for considering pool maxima across services and instances. Turn that advice into a deployment input: record the largest allowed replica count and the actual overlap policy. A quiet afternoon’s instance count is a poor basis for tomorrow’s deployment limit.
For the hypothetical ledger, reducing each API pool maximum to 9 would make the planned peak 6 × 9 + 3 × 8 = 78. That is an admissible candidate under the assumed allowance, with only two connections left inside it. It may still perform badly or leave too little uncertainty margin. Rehearse it rather than treating 78 as an optimum. Other choices include reducing rollout overlap, limiting worker concurrency or changing how work reaches the database.
Observe connections and waiting as different things
A configured pool maximum is potential demand. It does not mean every slot is open, and an open connection is not necessarily executing a query. Capture both the configured ledger and observations over the same representative interval, including the rollout. Record observation times consistently in Asia/Kolkata and keep the application revision and instance identities with them.
For a server-side view, PostgreSQL documents pg_stat_activity in its statistics reference. A monitoring role with appropriate visibility can group ordinary client backends without collecting query text:
SELECT datname, usename, application_name, state,
count(*) AS observed_sessions
FROM pg_stat_activity
WHERE backend_type = 'client backend'
GROUP BY datname, usename, application_name, state
ORDER BY observed_sessions DESC;This samples ordinary client sessions across databases on that server. It includes the monitoring connection itself. It excludes replication senders and non-client backend types, so don’t present its total as every occupied server resource. Some session details require monitoring privileges; missing detail is not evidence of no activity. Use fresh observations rather than holding the inspection inside a long transaction.
Give services meaningful application_name values and retain their instance mapping in your deployment records. Blank or shared names can make ownership ambiguous. Session state matters too: an idle session still has a connection, while an idle-in-transaction session needs a separate investigation. Krova’s old-transaction and VACUUM guide covers that latter problem.
On the client side, node-postgres exposes totalCount, idleCount and waitingCount in its Pool API. Collect them per pool with service and instance identity. A request waiting to borrow a client has not necessarily opened a new server session, so PostgreSQL alone cannot show the application’s entire queue. Also check that acquired clients are released on every completion and error path; the API documentation warns that unreleased clients can exhaust the pool.
If waiting grows while PostgreSQL has spare admission capacity, inspect client ownership, held clients and query duration before raising the pool. If many services approach their ceilings together, revisit the shared ledger. If active work is already saturating CPU, storage or locks, admitting more concurrent work may deepen the queue. Decide from comparable observations, including request latency, errors and successful job output.
If there’s a pooler, draw a second budget
PgBouncer changes the topology: application connections reach the pooler, and the pooler opens server connections. Its default_pool_size applies per user/database pair and can be overridden. It is not automatically a single cap for the whole fleet. Inventory pooler instances, relevant user/database pools, reserve pools and any direct connections that bypass them. Keep the application-to-pooler allowance separate from the pooler-to-PostgreSQL allowance.
Don’t introduce transaction pooling solely because a total looks large. Review the application’s session-state and transaction requirements, supported features and failure behavior first. The direct-connection calculation above cannot simply be relabeled as a pooler deployment plan.
Make the budget part of the next release
On a separate test deployment, run representative requests and worker jobs, then rehearse the expected overlap. Compare the configured peak, observed sessions, client waiting, database pressure and completed work. Change one constraint at a time and keep the previous configuration available. A reduced pool that fits the ledger but causes unacceptable waiting is useful evidence for a different design, not a successful result to hide.
If you self-host PostgreSQL on a Krova Cube, you control the guest configuration and own this capacity decision. Krova’s PostgreSQL deployment guide covers installation and restricted connectivity. More guest resources do not automatically change your application pool settings.
Before the next replica increase, review one line in the release plan: normal application pool maxima + rollout overlap must fit the application allowance left after reservations and other consumers are accounted for. Keep those deductions separate and the assumptions visible. That gives the next deployment a capacity check before it asks the database for another seat.
Rehearse the database connection budget on a Cube
Use a separate self-managed Linux environment to compare pool settings, deployment overlap and application outcomes with disposable data.
Creation context: This AI-assisted guide uses linked primary documentation and a hypothetical deployment. The counts, pool changes and SQL are illustrative; no database workload or benchmark was run for this article. The cover is a generated illustration.




