"Timeout acquiring a connection" under burst load: should pool.min be 0 or positive in Knex?

Direct answer

Set pool.min to a small constant (2–5) per instance, not 0 and not a fraction of max_connections. Enable testOnConnect (or validationQuery) so tarn validates on every checkout. Log acquire, create, and error pool events with timestamps to distinguish cold-start creation timeouts from genuine exhaustion.

Heuristic for pool.min

There is no single documented formula, but the widely used heuristic is:

• pool.min = 2–5 per app instance, sized to your typical concurrent transaction count, not to the database max_connections.
• Keep pool.max at a modest multiple (e.g., 10–20) so burst headroom exists without starving other instances.
• If you run N instances against a hosted Postgres with max_connections = M, ensure N × pool.max < M with headroom for superuser connections and other clients.

With min = 0, a sudden burst forces serial connection creation; each create must finish within createTimeoutMillis (default 30 s). Under load, creation can queue and exceed that timeout. A small min keeps a few connections warm so the first acquisitions succeed instantly.

Validation-on-checkout reliability

In Knex 2.x/3.x (tarn 3.x), testOnConnect (or validationQuery: 'SELECT 1') runs on every checkout when the connection has been idle. It reliably replaces connections the server killed (e.g., Postgres idle_in_transaction_session_timeout or manual termination).

Caveats:

• The validation query adds ~1–2 ms per acquisition; under extreme burst this can become a thundering-herd bottleneck if many idle connections expire simultaneously.
• Older Knex/tarn versions (pre-2.0 / pre-tarn-3) sometimes skipped validation on error paths; verify you are on current releases.

Diagnostics: which events to log

Attach listeners to the underlying tarn pool (available via knex.client.pool after initialization):

const pool = knex.client.pool;
pool.on('acquire', (conn) => {
  conn._acquiredAt = Date.now();
});
pool.on('release', (conn) => {
  const waited = Date.now() - conn._acquiredAt;
  if (waited > 100) console.warn({event: 'slow-release', waited});
});
pool.on('create', () => console.info({event: 'create', ts: Date.now()}));
pool.on('error', (err) => console.error({event: 'pool-error', err: err.message}));
pool.on('acquireTimeout', () => console.error({event: 'acquireTimeout', ts: Date.now()}));

Correlate these logs with createTimeoutMillis:

• Cold-start timeout: create events spike, acquisition duration approaches/exceeds createTimeoutMillis, few or no acquireTimeout before the burst.
• Genuine exhaustion: create rate is stable, acquireTimeout errors rise while pool size sits at max, wait times grow linearly with queue depth.

One missing detail

What is your current createTimeoutMillis and acquireTimeoutMillis? If createTimeoutMillis is left at the default 30 s, raising it to 60–90 s often eliminates cold-start timeouts without changing min.