concept Data & storage
Database connection pooling
A database connection pool reuses connections and caps how many callers can borrow them at once. When all usable connections are borrowed, additional callers must wait or fail according to the pool's policy.
What it means
Borrowing a connection is often called checkout; returning it is release. A pool's limit concerns concurrent use, not the total number of requests it can serve over time.
Here, each borrower needs one connection, all borrowers need it at the same instant, and the configured pool is fully usable. These assumptions let you examine the capacity boundary without pretending to model a real queue or workload.
Try it
Simulation: start with Pool connection limit = 5 and Concurrent borrowers = 8. Change Concurrent borrowers to 4, then select Compare with baseline to display the two outcomes. Inspect how the borrowed and excess counts change. Reset restores the baseline inputs and clears errors and the comparison.
Calculate borrowers waiting for a pool
Change one condition and inspect the computed result, its cause, and the model boundary.
Instantaneous counts only; no wait durations, server-side limits or fairness.
5 connection(s) can be borrowed simultaneously in this model; excess demand waits or times out depending on pool policy.
| Input | Supplied value |
|---|---|
| Pool connection limit | 5 |
| Concurrent borrowers | 8 |
Synthetic local learning example. No account, real network, server, filesystem, credential, command or production change is accessed.
About this model
Instantaneous counts only; no wait durations, server-side limits or fairness.
These are bounded teaching rules. Actual behavior needs the linked subject specifications and independent observations. The examples are not live checks.
The initial example remains readable without JavaScript; the controls require JavaScript. All calculations are local, with no database connection or external action.
3 borrower(s) waiting or failing. 5 connection(s) can be borrowed simultaneously in this model; excess demand waits or times out depending on pool policy.
The count of 3 is demand that cannot obtain a connection at this instant. The simulation does not determine whether those borrowers eventually succeed or time out.
Keep Pool connection limit at 5. The assumptions remain unchanged: one connection per borrower, simultaneous demand, and the entire configured pool available.
Reset restores Pool connection limit to 5 and Concurrent borrowers to 8, removes input errors, and clears the comparison. There is no simulation clock or stored event history. Reset preserves your independent choices to open or close FAQ answers and About this model.
How it works
A borrower temporarily holds a connection, making that connection unavailable to other callers. Releasing it makes capacity available for another checkout. Reuse therefore lets successive callers share a bounded set of connections; it does not let unlimited callers hold those connections simultaneously.
This also explains why the configured limit and usable capacity can differ in a real application. If a manually borrowed connection is never released, later callers lose access to that capacity even though the configured limit has not changed. The simulation assumes the whole configured pool is usable and does not detect such leaks.
The client pool limit is also separate from the database's own connection limit. For PostgreSQL 18, the server's connection settings govern what the server can accept; raising a client pool limit does not raise those settings. A larger client limit changes the number allowed through the client-side boundary, but it does not by itself establish additional database processing capacity.
Worked example
This is a synthetic baseline, not a production observation.
| Quantity | Count |
|---|---|
| Pool connection limit | 5 |
| Concurrent borrowers | 8 |
| Connections that can be borrowed simultaneously | 5 |
| Excess borrowers | 3 |
The smaller of 5 available connections and 8 borrowers is 5, so only 5 can hold a connection simultaneously. Subtracting those 5 from the 8 borrowers leaves 3 without a connection at that instant. The calculation establishes the shortfall; the pool's actual policy and subsequent releases determine what happens to those callers.
What changes when the condition changes
Change Concurrent borrowers to 4 while keeping Pool connection limit at 5.
0 borrower(s) waiting or failing. 4 connection(s) can be borrowed simultaneously in this model; excess demand waits or times out depending on pool policy.
Demand is now below the limit, so all four borrowers fit and one slot is unused. The excess count falls from 3 to 0 without changing the pool. This demonstrates a change in demand, not faster queries or a guarantee against real connection failures.
In practice
For an application you are authorized to inspect, begin with existing read-only diagnostics for the same environment and workload. Distinguish checkout wait, connection hold time, query execution time, and the configured client and database connection limits. Checkout wait ends when a caller obtains a connection; hold time continues until that connection is released.
Waiting while all usable connections remain borrowed is consistent with pool saturation, but it does not establish why they remain borrowed. Review whether successful and failed application paths follow the deployed client's documented release pattern. If timing or availability evidence is missing, the bottleneck remains unknown.
STOP before increasing client or database limits when you do not know where the wait occurs or what the database can support. This page provides no configuration-change procedure. Any later change needs a separately scoped plan for the exact client/database versions and authorized environment, including the prior setting, representative-workload verification, STOP conditions, and rollback.
Limits and unknowns
The model provides instantaneous counts only: no wait durations, server-side limits, or fairness. It does not choose which borrowers receive connections, distinguish waiting from eventual failure, or predict when a connection will be released. The label “waiting or failing” identifies excess demand, not an observed timeout.
A result of 0 excess borrowers means only that the supplied demand fits the assumed usable pool. It does not establish database availability, query speed, or adequate production capacity. This is a local simulation, not a live check of a machine, account, deployment, or service.
Use counts within the displayed ranges: Pool connection limit 1–100 and Concurrent borrowers 0–500. Empty, nonnumeric, or out-of-range input is invalid; no calculated outcome applies until you correct it or use Reset.
What to carry forward
Use the pool count to identify a concurrency boundary, not to choose a performance setting. If callers wait, the useful next distinction is whether connections stay borrowed too long or the workload needs more simultaneous access—and whether the database can support that access. The count alone cannot make that decision.
Frequently asked questions
Editorial questions, answered from the sources listed for this article.
Does a pool prevent every connection timeout?
No. Even a zero-excess result here assumes the configured connections are usable; it does not verify that the database will accept a real connection. The database has its own connection limits, and timeout behavior depends on your client configuration. This simulation calculates neither connection failures nor timeout durations.
Why must a borrowed connection be released after an error?
For a manually checked-out connection, failure of your operation does not remove the need for cleanup. If the connection remains checked out, other callers cannot use that pool capacity. Follow your client's documented cleanup pattern on both successful and failed paths; the node-postgres pooling documentation covers checkout and release for that client.
Is waiting for a connection the same as a slow SQL query?
No. Checkout wait occurs before the caller receives a connection; SQL execution is a separate stage while the connection is held. A query-duration observation alone cannot establish how long that caller waited to borrow a connection. Keep checkout and execution timings separate when interpreting a slow request.
Will doubling pool size double throughput?
Not necessarily. A higher client pool limit does not raise PostgreSQL's separate server-side connection limit, and simultaneous borrowers are not the same as completed work per second. This simulation has no query durations or server processing model, so it cannot predict a throughput gain from doubling the pool.
Sources & model boundaries
Primary references used for this explanation. The interactive example is an educational model, not a live check.
- node-postgres: pooling
Checkout, release and pool sizing. Borrowed connections need release; a pool introduces a limited shared resource
Checked .
- PostgreSQL 18: connections and authentication
19.3.1 max_connections and reserved connections. Database-side connection limits are separate from a client pool size
Checked .
- node-postgres: Pool API
Pool configuration: connectionTimeoutMillis; pool.connect; releasing clients. Pool checkout can queue; failure to release clients can make later connects time out or wait indefinitely with the default zero timeout. These statements are specific to this client API.
Checked .