Why pooling is necessary

Opening a database connection is expensive: TCP handshake, authentication, session setup. This takes 20–100ms. A pool maintains open connections and reuses them. Without pooling, every request pays that cost.

Pool sizing

The "right size" formula: pool_size = (cores × 2) + effective_spindle_count (HikariCP recommendation). Start with 10–20 for most web services. Bigger is not better — too many connections overwhelm the database.

Connection lifetime settings

  • connectionTimeout — how long to wait for a pool connection. Set to 30 seconds; surface failures fast if the pool is exhausted.
  • maxLifetime — maximum age of a connection. Set to slightly less than the DB's wait_timeout to avoid using a connection the DB has already closed (2–5 minutes less).
  • idleTimeout — how long an idle connection stays open before being closed. 10 minutes is a safe default.

Diagnosing pool exhaustion

Symptoms: requests time out after exactly connectionTimeout. Solution: instrument pool metrics (active, idle, waiting). If waiting > 0 regularly, either increase pool size or find slow queries holding connections longer than necessary.