Knex.js PostgreSQL SSL configuration and pool timeout behavior

Short answer

Yes — in Knex.js, acquireTimeoutMillis covers the entire acquisition attempt, including DNS resolution, the TCP connect, and the SSL/TLS handshake. It is a pool-level deadline, not a per-phase timeout. When the deadline expires, the pending acquire rejects with a timeout error regardless of which phase the connection was stuck in.

However, an invalid certificate with rejectUnauthorized: true usually fails before the timeout: the pg driver surfaces the TLS validation error as soon as the handshake completes, so you get a certificate error rather than a pool timeout. Timeouts dominate when the server is unreachable or DNS stalls, because nothing fails fast in those cases.

What the pool does under concurrent failures

Each waiting request independently races its own acquireTimeoutMillis clock. With pool.max: 10, up to 10 connection attempts can be in flight; if all stall on DNS or an unreachable host, each acquire rejects after the timeout. Failed connection attempts are discarded — Knex's pool (tarn.js underneath) does not retry or back off on its own. With pool.min: 0, the pool simply drains to empty; with min > 0, it will try to replenish minimum connections, which can generate repeated failing attempts against a dead server.

The layer underneath: connectionTimeoutMillis

The pg driver has its own connectionTimeoutMillis (passed through Knex's connection config) that bounds the initial socket connect. If it fires first, the acquire fails with a connection error rather than a pool timeout. Keep it lower than acquireTimeoutMillis so failures surface with a clear cause instead of a generic pool timeout.

Recommended configuration shape

const knex = require('knex')({
  client: 'pg',
  connection: {
    host: process.env.PGHOST,
    database: process.env.PGDATABASE,
    user: process.env.PGUSER,
    password: process.env.PGPASSWORD,
    ssl: { rejectUnauthorized: true, ca: fs.readFileSync('ca.pem') },
    connectionTimeoutMillis: 5000
  },
  pool: { min: 0, max: 10, acquireTimeoutMillis: 10000 }
});

Assumptions: Knex 1.x/2.x with a recent pg 8.x driver. Exact error bubbling for TLS failures has varied across pg versions, so verify against your installed versions.

Verification steps

• Fast-fail path: point at a reachable server with a self-signed cert and rejectUnauthorized: true. You should get a certificate error in well under acquireTimeoutMillis.
• Timeout path: point at a non-routable IP (e.g., a reserved TEST-NET address) with a low acquireTimeoutMillis and fire several concurrent queries. Each should reject with the pool timeout after roughly the configured duration.
• Layer identification: compare error messages while toggling connectionTimeoutMillis — a driver-level connect error versus Knex's acquire timeout tells you which layer terminated the attempt.

One caveat: OS-level DNS resolution can consume a large share of the acquire budget and is not separately configurable here. If your environment has slow or flaky DNS, size acquireTimeoutMillis accordingly or prefer IP-based hosts with TLS SNI handled explicitly.