Quarkus 3.8 Datasource max-lifetime shift and its impact on connection pool exhaustion

Effective Eviction Behavior in Quarkus 3.8

In Quarkus 3.8, when using default settings, the connection pool (Agroal) employs a two-tiered eviction strategy. An idle connection is first eligible for removal if it remains unused for 10 minutes (idle-timeout). Regardless of activity, any connection reaching 30 minutes of total age (max-lifetime) is retired and replaced. This creates a more aggressive retirement cycle than previous versions that relied on HikariCP's internal defaults, potentially increasing connection churn under steady-state loads.

Addressing Pool Exhaustion and Leak Detection

The quarkus.datasource.jdbc.leak-detection-threshold should be enabled if you suspect application-level leaks (e.g., unclosed Connection or ResultSet objects). Connection pool exhaustion often masquerades as a timeout, but a leak is a permanent loss of capacity, whereas max-lifetime churn causes transient spikes in latency. Enabling this threshold allows the pool to log a stack trace when a connection is held longer than the specified duration, distinguishing a coding error from a configuration bottleneck.

Preventing Stale Connections

To prevent SocketException or "broken pipe" errors, quarkus.datasource.jdbc.max-lifetime must be shorter than the database server's own connection timeout (e.g., MySQL's wait_timeout). If the database closes a connection before the pool retires it, the application will encounter a stale connection.

Recommended Configuration Steps

1. Sync Timeouts: Set max-lifetime to 2–5 minutes less than your database's global wait timeout.
2. Enable Leak Detection: Set leak-detection-threshold to a value slightly higher than your longest expected transaction (e.g., 60s).
3. Verify Validation: Ensure the pool validates connections on borrow to prune connections that were killed by the server or network intermediaries.

Verification Commands

Monitor the following MicroProfile Metrics to verify pool health:

# Check for high churn or saturation via metrics endpoint
curl http://localhost:8080/q/metrics | grep agroal_active_connections
curl http://localhost:8080/q/metrics | grep agroal_idle_connections

Note: To provide a more precise timeout recommendation, the specific database engine and its current wait_timeout value are required.