KnexTimeoutError from the connection pool: distinguishing a real leak from undersized pool settings

Answer to the core question

When a KnexTimeoutError is thrown, the pool’s acquire timeout has been reached. Two distinct scenarios can cause this:

1. Connection leak – a checked‑out connection is never returned (e.g., a transaction whose trx is not threaded through every query, or a commit/rollback that never runs). The number of borrowed connections grows over time while idle stays near zero.
2. Undersized pool – the pool’s max is too low for the current burst of concurrent queries. Borrowed connections quickly hit max, and the pending queue grows only while the burst lasts; once concurrency drops, released connections return to available and the error rate subsides.

The distinguishing factor is the pool’s state over time:

• Leak: borrowed steadily increases, available stays at (or near) 0, and pending does not shrink after queries finish.
• Undersized pool: borrowed reaches max during the spike, but available recovers once the load eases; pending clears as connections are released.

Logging acquire/release events

Knex exposes the pool’s log option. Setting it to console.log (or a custom logger) emits an acquire line before each query and a release line when the connection is returned:

knex.initialize({
  client: 'pg',
  connection: { /* … */ },
  pool: {
    min: 2,
    max: 10,
    log: console.log   // logs: acquire, release, destroy, timeout
  }
});

Pair this with knex.on('query', (query) => { /* log query text */ }) to correlate timestamps with the SQL being run.

Inspecting pool metrics at runtime

In a REPL, test hook, or middleware you can read the generic‑pool internals (compatible with Knex ≥ 0.21.0):

const pool = knex.client.pool;
console.log('borrowed:', pool.borrowed);
console.log('available:', pool.available);
console.log('pending:', pool.pending);

Older Knex releases used pool._borrowed etc.; adjust according to the version you run.

Practical steps for this scenario

1. Enable logging: add pool.log: console.log and knex.on('query', …).
2. Run a load test that mimics the production burst. Watch the console for acquire/release pairs.
3. Periodically log pool.borrowed, pool.available, pool.pending.
4. If borrowed never falls below max and available stays 0, you have a leak.
5. If borrowed saturates only during spikes and drops when load subsides, the pool is likely undersized; consider raising max or acquireTimeoutMillis.
6. Ensure every trx or raw connection is released or destroyed in all code paths, including error branches.
7. Call await knex.destroy() on shutdown to cleanly close sockets (especially in tests or serverless functions).

To fine‑tune the recommendation, I need one piece of information: what is the current max setting of your Knex pool? Sharing that will let me determine whether the next step is to increase the pool size or to hunt for a missing release() call.