Unravel โบ Java concepts โบ Persistence and JPA
Connection pools (HikariCP)
Opening a database connection is slow, so applications keep a small pool of open connections and lend them out.
Learn these first
At a glance
A taxi rank with a fixed number of cabs.
- 1HikariCP is the default pool in Spring BootgetConnection() borrows a connection; close() does not close it but returns it to the pool.
- 2The key settings: maximumPoolSize (how many connections at most), connectionTimeout (how long a thread waits for one, default 30 s), maxLifetime (retire connections before the database or firewall does) and idleTimeout
- 3A transaction holds one connection from its start to its end, so slow code inside @Transactional (remote calls, sleeps) directly shrinks the available pool
- 4Failure shows up as Connection is not available, request timed out after 30000ms: all connections are busy or leaked
- A bigger pool is usually not faster
- Total connections = pool size times instances
- Hikari keeps connections in a lock-free ConcurrentBag with thread-local fast paths, so a borrow is usually a few hundred nanoseconds
HikariConfig config = new HikariConfig();config.setJdbcUrl("jdbc:postgresql://db:5432/shop");config.setUsername("app");config.setPassword(System.getenv("DB_PASSWORD"));config.setMaximumPoolSize(15);config.setConnectionTimeout(5000);config.setLeakDetectionThreshold(20000);DataSource ds = new HikariDataSource(config);- line 1 uses HikariConfig, the core of Connection pools (HikariCP)
- line 5 uses setMaximumPoolSize, the core of Connection pools (HikariCP)
- line 6 uses setConnectionTimeout, the core of Connection pools (HikariCP)
- line 7 uses setLeakDetectionThreshold, the core of Connection pools (HikariCP)
- line 8 uses HikariDataSource, the core of Connection pools (HikariCP)
Read the full explanation (about 2 min)
Opening a database connection is slow, so applications keep a small pool of open connections and lend them out. The pool size is one of the most important performance settings of a backend.
A mental model
A taxi rank with a fixed number of cabs. Passengers (threads) take a cab for a ride (a query or transaction) and return it. If all cabs are out, new passengers queue, and after waiting too long they give up.
How it works
HikariCP is the default pool in Spring Boot. getConnection() borrows a connection; close() does not close it but returns it to the pool.
The key settings: maximumPoolSize (how many connections at most), connectionTimeout (how long a thread waits for one, default 30 s), maxLifetime (retire connections before the database or firewall does) and idleTimeout.
A transaction holds one connection from its start to its end, so slow code inside @Transactional (remote calls, sleeps) directly shrinks the available pool.
Failure shows up as Connection is not available, request timed out after 30000ms: all connections are busy or leaked.
Going deeper
A bigger pool is usually not faster. The database can only run so many queries in parallel (roughly the number of CPU cores and disks); beyond that you add queueing and context switching. Start around 10 to 20 per instance and measure.
Total connections = pool size times instances. Ten pods with 20 connections each is 200 connections, which can exceed the database limit (PostgreSQL defaults to 100).
Enable leakDetectionThreshold in non-production to find code that never returns connections, for example a missing try-with-resources or a long transaction.
Under the hood
Hikari keeps connections in a lock-free ConcurrentBag with thread-local fast paths, so a borrow is usually a few hundred nanoseconds. A housekeeper thread retires old connections and replenishes the minimum. Handed-out connections are proxies whose close() returns them and whose statements are tracked and closed.
Common mistakes
- Pool size set to hundreds.
- Not accounting for instance count against the database limit.
- Remote calls inside a transaction.
- Connections leaked by missing close.
How Unravel recognises it
When you paste code, Unravel looks for these signs of connection pools (hikaricp). Spotting them yourself is a good habit when you read unfamiliar code:
- Types:
HikariDataSourceHikariConfigHikariPoolMXBeanComboPooledDataSourceBasicDataSourcePoolPropertiesDataSourceBuilderSQLTransientConnectionException - Method calls:
setMaximumPoolSize()setConnectionTimeout()setLeakDetectionThreshold()setMinimumIdle() - Configuration keys:
spring.datasource.hikari.maximum-pool-sizespring.datasource.hikari.connection-timeoutmaximumPoolSizespring.datasource.url
Part of a learning path
Related concepts
Frequently asked questions
What is Connection pools (HikariCP)?
Opening a database connection is slow, so applications keep a small pool of open connections and lend them out. The pool size is one of the most important performance settings of a backend.
What are the most common mistakes with Connection pools (HikariCP)?
Pool size set to hundreds. Not accounting for instance count against the database limit. Remote calls inside a transaction. Connections leaked by missing close.
How can I see Connection pools (HikariCP) in real code?
Paste your own Java into Unravel and it will point out where connection pools (hikaricp) appears, explain how it works at the detail level you choose, and draw the flow of the code around it.