🔄 1. HikariCP Waits for an Available Connection
HikariCP does not immediately throw an error. Instead, it waits up to a configured amount of time (connection-timeout, in milliseconds) for a connection to be returned to the pool.
For example:
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.connection-timeout=30000
➡️ If 10 connections are in use and an 11th request comes, it will wait up to 30 seconds for a connection to become available.
❌ 2. Timeout Exception is Thrown if All Connections Are Busy
If no connection is available within the connection-timeout period, HikariCP throws this exception:
com.zaxxer.hikari.pool.HikariPool$PoolAccessException:
Failed to obtain JDBC Connection within 30000ms
Or sometimes:
java.sql.SQLTransientConnectionException:
HikariPool-1 - Connection is not available, request timed out after 30000ms.
🔄 3. Returned Connections Are Reused
When a thread finishes using a connection and returns it (via connection.close() or automatically by Spring), it becomes available to other threads. This is the core idea behind connection pooling—reusing instead of creating new ones.
📌 Summary
| Scenario | Behavior |
|---|---|
Threads ≤ maximum-pool-size | All get connections normally |
Threads > maximum-pool-size | Extra threads wait for a connection |
Wait exceeds connection-timeout | Exception is thrown |
| Connection returned to pool before timeout | Waiting thread can use it |
🧠 Pro Tip:
If you frequently hit the pool size limit:
- Consider increasing
maximum-pool-size(within DB limits). - Profile and fix long-running queries or connection leaks.
- Enable connection pool metrics to monitor usage.