HikariCP

About

HikariCP is a fast, lightweight, reliable JDBC connection pool library. It is the default connection pool implementation used in Spring Boot (from version 2.x onwards). HikariCP is known for its performance, low overhead, and minimal configuration needs, yet it provides powerful tuning options.

What is HikariCP ?

HikariCP is a JDBC connection pool implementation designed to be extremely fast and simple to use. It manages a pool of active database connections that can be reused, avoiding the cost of establishing a new connection for every request.

Hikari means "light" in Japanese, reflecting the library’s goal to be lightweight and fast.

Key Features

• Minimal footprint with low latency and high throughput

• Asynchronous house-keeping

• Fast connection acquisition

• Leak detection support

• Built-in connection health checks

• JDBC4-compliant

• Excellent performance under load

Default in Spring Boot

Starting from Spring Boot 2.0, HikariCP is the default DataSource. Spring Boot will automatically configure it when it detects spring.datasource.* properties.

Minimal setup via application.properties:

spring.datasource.url=jdbc:mysql://localhost:3306/test_db
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Spring Boot will detect HikariCP in the classpath and configure it automatically.

Properties

Commonly Used HikariCP Properties

Property	Description	Best Practice
spring.datasource.hikari.pool-name	Name of the connection pool	Use meaningful names for easier debugging/logging
spring.datasource.hikari.maximum-pool-size	Maximum number of connections in the pool (default: 10)	Set based on DB capacity and concurrent load; typically 10–30
spring.datasource.hikari.minimum-idle	Minimum number of idle connections in the pool	Set equal to maximum-pool-size to avoid pool shrinking
spring.datasource.hikari.idle-timeout	Maximum idle time (ms) for a connection before it's removed	Set lower for low-traffic apps; 30000 (30s) is good
spring.datasource.hikari.connection-timeout	Max time (ms) to wait for a connection from the pool	Keep between 20000–30000; too low may cause exceptions under load
spring.datasource.hikari.max-lifetime	Maximum lifetime (ms) of a connection before it’s recycled	Set slightly less than DB’s timeout (e.g. 1800000 = 30 min)
spring.datasource.hikari.leak-detection-threshold	Logs a warning if a connection is held longer than this (ms)	Use 15000–30000 in dev/test to detect leaks
spring.datasource.hikari.validation-timeout	Timeout (ms) for validating a connection	Default is 5000; reduce if you see slow validation

Other Useful Properties

Property	Description	Best Practice
spring.datasource.hikari.auto-commit	Auto-commit behavior for connections (default: true)	Set to false if you use transactions explicitly
spring.datasource.hikari.read-only	Set connections to read-only if you're not modifying data	Use in read-heavy/reporting apps
spring.datasource.hikari.initialization-fail-timeout	Time (ms) to wait before failing startup if DB is down (default: 1ms)	Set to -1 to disable fail-fast during startup
spring.datasource.hikari.isolate-internal-queries	If true, internal queries run in their own connection state	Keep false unless you suspect conflicts
spring.datasource.hikari.allow-pool-suspension	Allows pool to be suspended and resumed	Rarely used; keep false unless required
spring.datasource.hikari.keepalive-time	Prevents idle connections from being closed if they haven’t timed out	Set if your DB closes idle connections before max-lifetime
spring.datasource.hikari.catalog	Sets the default catalog for connections	Use only if your app needs a specific catalog
spring.datasource.hikari.schema	Sets the default schema	Set when multiple schemas are used in the DB
spring.datasource.hikari.connection-init-sql	SQL executed after a connection is created	Useful for DB-level session parameters (e.g. SET timezone)

Validation Settings

HikariCP doesn't use testOnBorrow, testWhileIdle, etc. like other pools. Instead:

Property	Description	Best Practice
spring.datasource.hikari.connection-test-query	Custom query to test connection validity	HikariCP auto-detects based on driver; override if needed
spring.datasource.hikari.validation-timeout	Timeout (ms) to complete a validation query	Keep 1000–5000ms depending on DB response time

Best Practices for HikariCP in Spring Boot

1. Set the pool size based on database and application capacity

   • maximum-pool-size should reflect the concurrency your database can handle.

   • Start with 10–30 depending on expected load.

   • Never exceed the database’s allowed max connections.

2. Match minimum-idle to maximum-pool-size in high-throughput systems

   • Prevents idle connections from being closed and recreated constantly.

   • Helps maintain performance during sudden traffic spikes.

3. Use max-lifetime below the database’s timeout

   • If your database closes idle connections after 30 minutes, set max-lifetime to 25–28 minutes.

   • Prevents "connection closed" errors due to backend timeout.

4. Set idle-timeout lower than max-lifetime

   • Prevents unnecessary long-held idle connections.

   • Example: idle-timeout = 30000, max-lifetime = 1800000.

5. Enable leak-detection-threshold during development

   • Helps identify when connections are not being closed.

   • Example: leak-detection-threshold = 15000 (15 seconds).

6. Use connection-timeout based on SLA and latency

   • Set it reasonably low to avoid users waiting too long.

   • Default is 30 seconds; values between 10,000–20,000 ms work well in most cases.

7. Avoid using long-living transactions

   • These hold connections longer and reduce pool availability.

   • Always close EntityManagers, JDBC connections, or Sessions properly.

8. Set auto-commit wisely

   • Default is true; disable only if you manage transactions explicitly.

   • Mismatched auto-commit settings can cause silent data issues.

9. Avoid unnecessary validation queries

   • Hikari automatically chooses efficient methods (e.g., JDBC’s isValid()).

   • Only use connection-test-query if absolutely necessary.

10. Monitor pool behavior using Spring Boot Actuator

    • Enable management.endpoints.web.exposure.include=* and inspect metrics like:

      • hikaricp.connections.active

      • hikaricp.connections.idle

      • hikaricp.connections.pending

      • hikaricp.connections.usage

11. Avoid frequent restart of the application or forcing pool shutdown

    • Closing pools too often (especially in microservices) leads to socket issues or DB throttling.

    • Let the pool recycle connections naturally.

12. Consider using a separate pool or datasource for batch/long-running jobs

    • This avoids blocking web requests while a few threads hold connections for long-running tasks.

13. Use the latest HikariCP and JDBC drivers

    • Keeps your app secure, stable, and compatible with database enhancements.

14. Avoid having too many pools in a microservice environment

    • One well-tuned pool per service is ideal.

    • Multiple small pools can starve the DB if misconfigured.

15. Use profiling tools like VisualVM, JConsole, or Spring Boot Micrometer

    • Helps understand real-time pool usage, bottlenecks, and leak points.