What Is a Connection Pool? Why Your Database Runs Out
A connection pool reuses a small set of open database connections instead of opening one per request. Here is why it exists, how to size it, and the leak that freezes an app.
A connection pool is a set of database connections that stay open and are lent out to your code one request at a time. Instead of opening a fresh connection for every query, then closing it, your app borrows an existing one, uses it and hands it back. Opening a connection is slow and databases can only hold so many, so reusing a few is faster and safer.
If you have ever seen "too many connections" or "remaining connection slots are reserved", you have already met the problem a pool exists to prevent.
Why not connect fresh every time?
The node-postgres pooling guide gives three reasons:
Connecting is expensive. It describes a handshake that can take 20 to 30 milliseconds, during which passwords are negotiated, SSL may be set up, and configuration is exchanged. Do that before every query and your app feels sluggish.
The database has a limit. PostgreSQL can only serve so many clients, and unbounded connections can exhaust server memory.
One client runs queries one at a time. A single connection works through its queries in first-in, first-out order, so concurrent requests sharing one connection would queue up behind each other.
A pool solves all three. It pays the connection cost once, caps the total, and lets several requests run in parallel on different connections.
The two ways to use one
With node-postgres, you create a pool once, at startup:
import { Pool } from 'pg';
export const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });Then use it in one of two ways:
// 1. Simple: the pool picks a free connection and returns it for you.
const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [id]);
// 2. Manual: you check one out, and you must give it back.
const client = await pool.connect();
try {
await client.query('BEGIN');
// ...several statements that must share one connection...
await client.query('COMMIT');
} finally {
client.release();
}The guide recommends pool.query() whenever you do not need a transaction or a specific client, because it removes the risk of leaking a client. Use the manual form for transactions, where every statement must run on the same connection.
The leak that freezes an app
The guide stresses that you must always return a checked-out client, even when a query on it fails. Here is the bug in six lines:
const client = await pool.connect();
const { rows } = await client.query('SELECT * FROM orders WHERE id = $1', [id]);
if (rows.length === 0) {
return res.status(404).end(); // returned without client.release()
}
client.release();Every request for a missing order leaks one connection. With a pool of 10, the eleventh such request waits for a free client that will never come. Nothing crashes and nothing logs an error. The app simply stops answering any request that touches the database, and a restart "fixes" it until the leak fills the pool again.
The cure is the finally block in the second example above, so release happens on every path. When you review AI-written database code, search for every pool.connect() and check that each one has a matching release() in a finally.
How big should the pool be?
Bigger is not better. The pool size is a share of the database's total connection budget, not a speed dial.
A worked example. Suppose your database allows 60 connections, and you keep 10 back for migrations, admin tools and monitoring. That leaves 50. If you run 5 copies of the app, each pool should be at most 10. If your host starts extra copies under load, the count of copies changes and the math breaks, which brings us to the serverless trap.
The serverless and multi-instance trap
Platforms that run your code as many short-lived functions can start dozens of instances at once. Each one creates its own pool. Ten instances with max: 10 is a hundred connections against a limit of sixty, and the database starts refusing. The usual fixes are a small max per instance (often 1 to 3), or a pooler placed in front of the database. Many hosted databases offer a built-in pooler for exactly this reason, so check your provider's documentation for the connection string meant for it. The details specific to AI-built apps are in database connection limits.
Symptoms checklist
Requests hang until a timeout, with no error: a leaked client, or a pool that is too small for the traffic.
"Too many connections" errors during a traffic spike: too many instances times pool size.
Fast locally, slow in production: no pool at all, so each request reconnects.
Idle connections piling up in the database dashboard: pools created inside a request handler instead of once at startup.
Set a timeout on the checkout too, so a request fails with a clear error rather than waiting forever, and see why your AI-built app is slow for the other usual suspects. If a service in front of the pool is the real problem, a circuit breaker stops the pile-up.
A prompt for your coding agent
Audit every database access path. Confirm one shared pool is created at
startup, not per request. For every pool.connect() call, show me the matching
client.release() inside a finally block. Set max to 5 and add a checkout
timeout of 3 seconds. List any code that opens its own connection outside
the pool.FAQ
What is a connection pool in simple terms?
It is a shared set of ready-to-use database connections. Your code borrows one, runs its queries, and returns it, instead of opening and closing a connection each time.
How many connections should a pool have?
Fewer than you think. Divide your database's connection limit, minus a reserve for tools, by the number of app instances. For small apps, 5 to 10 per instance is a common starting range.
What does "too many connections" mean?
The database has hit its maximum number of simultaneous clients. Usually too many app instances each opened a full pool, or connections are leaking and never released.
What happens if I forget to release a connection?
The pool slowly empties. Once every connection is checked out, new requests wait indefinitely and the app appears frozen.
Do I need a pool for a tiny app?
Usually yes, and most database libraries include one. Connecting per request works at tiny scale and then fails suddenly as traffic grows.
How did this land?
About the author

Staff Engineer, Platform
Carlo works on the platform that turns prompts into running apps. He writes the engineering deep dives and the changelog notes worth reading.


