Answer:
🔹 What is keepaliveTime
?
The keepaliveTime
setting in HikariCP specifies how often idle connections should be proactively pinged (validated) to keep them alive.
If a connection sits idle longer than keepaliveTime
, HikariCP will run a lightweight validation (using isValid()
or your connectionTestQuery
) on it.
🔹 Why is it important?
Some databases, proxies, or firewalls (e.g., AWS RDS, load balancers) may silently close idle connections after a period of inactivity (e.g., 5 or 10 minutes).
- When this happens, your app could get stale or broken connections from the pool, resulting in errors like
Connection reset
orSocketException
on first use. - By proactively sending keepalive pings, HikariCP prevents idle connections from becoming stale, ensuring your app always receives a valid, ready-to-use connection.
🔹 When should you use it?
- If you know your database, proxy, or network infrastructure has short idle connection timeouts (e.g., AWS ALB closes idle connections after 5 minutes).
- When you observe intermittent
Communications link failure
orConnection reset
errors on the first query after a period of inactivity. - Best practice is to set
keepaliveTime
shorter than the known idle timeout of your DB/network.
🔹 Example configuration:
spring.datasource.hikari.keepalive-time=300000 # 5 minutes in milliseconds
✅ Key point:
Unlike idleTimeout
, which closes idle connections, keepaliveTime
keeps them alive by periodically validating them — helping avoid unexpected connection errors.