Knex 3.x pool configuration: idle connection eviction versus database-side TCP timeouts

Short answer

There is no validation query in Knex 3.x that checks a connection before it is handed out. The intended defense against a database that closes idle TCP connections is pool-side eviction: set pool.idleTimeoutMillis comfortably below the server's wait_timeout (and below any firewall idle timeout), and make sure reapIntervalMillis runs often enough to actually enforce it. afterCreate runs once when a connection is created — it is not a recurring health check and cannot catch a connection that died while idle in the pool.

1. idleTimeoutMillis vs. a validation hook

Knex delegates pooling to tarn.js, and tarn.js has no built-in "test on borrow" query. So the documented mechanism is eviction, not validation. The ordering that matters:

• If wait_timeout < idleTimeoutMillis, the server closes the socket first and the pool hands out a dead connection. Your query then fails with something like Connection lost / socket hang-up.
• If idleTimeoutMillis < wait_timeout, tarn destroys the connection while it is still healthy, and the next acquire creates a fresh one.

Leave headroom for the reaper: tarn only checks idleness every reapIntervalMillis, so effective eviction can lag the configured idle timeout by up to one interval. A practical rule: idleTimeoutMillis + reapIntervalMillis < wait_timeout. Example for MySQL's default 8-hour timeout, or a stricter 60-second proxy/firewall timeout:

pool: {
  min: 0,
  max: 10,
  idleTimeoutMillis: 30000,   // well under a 60s network/db timeout
  reapIntervalMillis: 1000,   // check for idle connections every second
  acquireTimeoutMillis: 10000
}

The trade-off: very low idle timeouts cause connection churn (repeated TCP handshakes and auth). Don't go lower than your typical gap between queries.

2. Does pool.min > 0 increase stale-connection risk?

Yes, indirectly. With min: 0, an idle pool drains to zero and every acquire after a quiet period creates a brand-new connection. With min: 2, those two connections sit idle indefinitely and are exactly the ones a firewall or wait_timeout will silently kill — and idle-timeout eviction is the only thing that removes them. If your environment has short network idle timeouts, prefer min: 0, or keep idleTimeoutMillis below the shortest timeout in the path (load balancer, NAT, firewall, and the DB itself).

3. Verifying eviction happens before reuse

1. Confirm the server value: SHOW VARIABLES LIKE 'wait_timeout'; (MySQL) or SHOW idle_in_transaction_session_timeout; / TCP keepalive settings (Postgres). Compare against your pool settings.
2. Run with DEBUG=knex:* (or at least knex:query, knex:client) to watch acquire/release timing.
3. Reproduce: temporarily set the DB timeout very low (e.g., SET GLOBAL wait_timeout = 10;), let a pooled connection sit idle for 15 seconds, then issue a query. If eviction is configured correctly, the connection is reaped first and the query succeeds on a fresh connection; if not, you'll see a connection-lost error on first use.

Caveats

Option names and defaults above reflect Knex 3.x / recent tarn.js; verify against your installed versions (npm ls tarn). If you cannot tolerate a first-query failure even rarely, add application-level retry on connection errors, since Knex alone offers no pre-borrow validation.