Knex connection pool timeout appearing only in production

Quick Answer

1. Inspect numPendingAcquires first – a sustained value near the pool’s max shows saturation. 2. Gather metrics via a lightweight async logger or Prometheus exporter that reads knex.client.pool._metrics without blocking the acquire path. 3. SSL misconfigures surface as TLS alert codes (e.g., 40 for bad certificate, 42 for unsupported) or Node error codes like ERR_TLS_CERT_ALTNAME_INVALID or ECONNRESET during handshake.

Likely Explanation vs Confirmed Facts

• Pool Saturation: numUsed ≈ max and numFree ≈ 0, with numPendingAcquires clamped at max – indicates all connections are busy.
• SSL Failure: numPendingAcquires low, but every acquire attempt triggers handshake errors logged by the driver (e.g., tls: alert 40).
• Both scenarios yield a KnexTimeoutError because the acquire promise never resolves.

Steps to Diagnose in Production

1. Enable lightweight metrics collection:

   const pool = knex.client.pool;
   setInterval(() => {
     const m = pool._metrics;
     console.log(`used:${m.numUsed} free:${m.numFree} pending:${m.numPendingAcquires}`);
   }, 10000); // 10‑second cadence, non‑blocking
   

   This uses the internal _metrics object; it is read‑only and safe for production.
2. Export metrics to a monitoring system (Prometheus, Datadog, etc.) so you can watch trends without adding request‑level overhead.
3. Enable driver‑level TLS debug:

   process.env.NODE_DEBUG = (process.env.NODE_DEBUG || '') + ',tls';
   

   or, for PostgreSQL, set PG_DEBUG to capture server‑side handshake logs.
4. Look for TLS alert codes in the logs:
   • Alert 40 – bad certificate
   • Alert 42 – unsupported certificate
   • Node error ERR_TLS_CERT_ALTNAME_INVALID
   • Connection reset ECONNRESET during handshake
5. Correlate metrics with errors:
   • If numPendingAcquires stays high while errors are TLS‑specific, the root cause is SSL.
   • If metrics show saturation but no TLS errors, increase pool.min or pool.max or add connection retries.

Ask for Missing Diagnostic Detail

Do you have any TLS error logs (e.g., tls: alert 40 or ERR_TLS_CERT_ALTNAME_INVALID) captured around the time of the timeout? That would confirm an SSL misconfiguration.