A client called us in a mild panic because their API was throwing intermittent 500 errors, only during their morning traffic spike, only for about twenty minutes, and only some of the time. Classic heisenbug. Their first instinct was that the database itself was overloaded, so they'd already spent money bumping their Postgres instance up a tier before calling us. It didn't help. The actual problem was sitting in their Node.js connection pool config, set to a default that nobody on the team had ever consciously chosen.

What a connection pool is actually doing

Opening a new database connection is expensive — a TCP handshake, TLS negotiation if you're using SSL, authentication, session setup. Do that on every single query and you'll spend more time connecting than querying. A pool keeps a set of already-open connections around and hands them out to your code as needed, then takes them back when the query finishes. The pool size is the maximum number of connections it will open at once. Set it wrong in either direction and you get problems that look completely unrelated to their actual cause.

Too small: the timeout spiral

This was their bug. Pool max was set to 10, a number that had shipped as a copy-pasted default from a tutorial two years earlier and never revisited. Under normal traffic, 10 connections was plenty. During the morning spike, every incoming request needed a connection, all 10 were checked out and busy, and every subsequent request queued up waiting for one to free up. Once the queue wait exceeded their API gateway's 30-second timeout, the request failed — not because the database was slow, but because the request never even got a connection to start its query.

// What they had
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10, // never revisited since the tutorial they copied it from
});

// What we shipped, after load-testing to find the real number
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 30,
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000, // fail fast instead of queueing silently
});

The connectionTimeoutMillis setting mattered as much as raising max. Before that fix, requests were queuing silently for up to 30 seconds before failing, which meant the app looked "slow" rather than clearly broken, and their monitoring didn't flag it as a distinct problem. Failing fast at 5 seconds turned a mysterious intermittent slowdown into an obvious, loud, immediately diagnosable error, which sounds worse but is a strictly better failure mode for actually fixing the thing.

Too large: the database's problem now

The instinct after finding a too-small pool is to way overcorrect, and we've seen teams set max to 200 assuming bigger is safer. It isn't. Postgres has its own connection limit, usually around 100 by default, shared across every app instance connecting to it. If you're running 4 instances of your API each with a pool max of 200, you can theoretically try to open 800 connections to a database that will reject anything past 100. We ran the math backward from their actual instance count: 4 API replicas, Postgres max_connections at 100, leaving headroom for migrations and admin tools, landed us at a pool max of 20 per replica, not 30. Bumping to 30 without checking that math would have traded one outage for a different one.

How we actually found the real number

Guessing pool sizes from a blog post — including this one — is how you end up with a copy-pasted default in the first place. What worked was load-testing with a tool that could simulate their real traffic shape, watching Postgres's own pg_stat_activity view during the test to see actual concurrent connection usage, and setting the pool max slightly above the peak observed, not arbitrarily high. Twenty minutes of load testing told us more than an hour of reading tuning guides.

The part everyone forgets: releasing connections

None of this matters if your code leaks connections by not releasing them back to the pool on error paths. We found one query in their codebase inside a try block with no corresponding release in the catch block — meaning every time that specific query threw an error, a connection was checked out and never returned. Under normal conditions this leaked slowly enough to go unnoticed for months. Under load, it drained the pool fast. Audit your error handling around every raw pool.connect() call; if you're not using a query builder or ORM that handles this automatically, it's worth wrapping it in a helper that guarantees release in a finally block, because someone will eventually forget, and it will be you.