What does a HikariCP connection pool actually limit?

A HikariCP pool is a fixed set of open JDBC connections that application threads borrow and return. Because each connection can run only one statement at a time, the maximum pool size is a hard cap on how many queries your service can have in flight against the database. When every connection is checked out, the next thread waits in Hikari's queue until one is returned or its connection timeout expires.

Spring Boot uses HikariCP as the default spring boot datasource when it is on the classpath, which it is when you use the standard JDBC or JPA starters. It was chosen because it is small, fast at handing out connections, and adds little overhead per borrow. That speed matters less than what the pool limits.

A database server has finite CPU cores, disk bandwidth, memory and lock capacity. Up to a point, more concurrent queries keep those resources busy and throughput rises. Past that point, extra queries compete for the same cores, wait on I/O, and contend for row locks, latches and buffer pages. Throughput flattens or drops, and per-query latency climbs.

So a bigger hikaricp pool size rarely removes a queue. It usually moves the queue from the application, where waiting threads are cheap and visible, into the database, where queued work holds locks and slows everyone sharing it. Backend engineers own the first queue. Platform engineers who run shared databases inherit the second.

 SMALL POOL: the queue waits in the application
 +---------------------------+        +------------------------------+
 | Spring Boot service       |        | Database server              |
 |  threads T1..Tn           |        |  finite: CPU cores, disk I/O |
 |        |                  |        |  memory, row locks, latches  |
 |        v                  |        |                              |
 |  [Hikari wait queue]      |        |  N queries running           |
 |  T7 T8 T9 ... waiting     |        |  -> resources busy,          |
 |  (cheap, visible, bounded |        |     not oversubscribed       |
 |   by connectionTimeout)   |        |  -> throughput near peak     |
 |        |                  |        |                              |
 |        v                  |  max N |                              |
 |  [pool: N connections]----+------->|                              |
 +---------------------------+        +------------------------------+

 BIG POOL: the same queue, now inside the database
 +---------------------------+        +------------------------------+
 | Spring Boot service       |        | Database server              |
 |  threads T1..Tn           |        |  M >> N queries in flight    |
 |        |                  |        |  [run] [run] [run] ...       |
 |        v                  |        |  [wait CPU] [wait I/O]       |
 |  (little or no wait)      |        |  [wait lock] [wait latch]    |
 |        |                  |        |  -> per-query latency up     |
 |        v                  |  max M |  -> throughput flat or down  |
 |  [pool: M connections]----+------->|  -> locks held longer        |
 +---------------------------+        +------------------------------+
   app-side queue: backend engineers   db-side queue: platform engineers

The maximum pool size caps queries in flight; with a small pool, excess requests wait cheaply in Hikari's queue, while a much larger pool pushes that same waiting into the database as CPU, I/O and lock contention shared by every client.

How do you calculate the right HikariCP pool size?

Start with Little's Law: the average number of connections in use equals the rate of requests that need a connection multiplied by the average time each one holds it. The pool should cover that number plus headroom.

Illustrative estimate. Assume 200 requests per second reach code that borrows a connection, and each holds it for 15 ms on average. 200 × 0.015 = 3 connections busy at any moment in steady state. Bursts and slow outliers push concurrency above the average, so a pool of about 8–10 leaves room without inviting the database to run dozens of competing queries. These inputs are assumptions, not measurements.

Hold time is not query time. A connection is held for the full transaction scope. An @Transactional method that calls a remote HTTP service, serializes a large payload, or loops over results in memory keeps its connection the whole time, even though the database is idle. Open-session-in-view, which Spring Boot enables by default for JPA web applications, can stretch the hold to the entire request, including view rendering.

This is why shrinking hold time usually beats resizing the pool. Moving a 200 ms remote call outside the transaction removes that 200 ms from every connection hold. A larger pool only lets more requests wait on the same slow work. You fix the cause once instead of retuning the pool after every traffic change.

The formula assumes steady state and uses averages. Real traffic arrives in bursts, and hold times have long tails, so treat the result as a starting point and confirm it with load testing.

// Before: @Transactional on the whole method holds a connection during the
// remote HTTP call, even though the database is idle the entire time.
//
// After: fetch the quote outside any transaction, then open a short
// transaction only for the writes.

@Service
public class CheckoutService {
    private final PricingClient pricingClient; // remote HTTP client
    private final OrderWriter orderWriter;     // separate bean so the proxy applies

    public CheckoutService(PricingClient pricingClient, OrderWriter orderWriter) {
        this.pricingClient = pricingClient;
        this.orderWriter = orderWriter;
    }

    // No @Transactional here: no connection is borrowed during the remote call.
    public Order checkout(Cart cart) {
        PriceQuote quote = pricingClient.quote(cart); // slow, no DB connection held
        return orderWriter.save(cart, quote);         // connection held only for the inserts
    }
}

@Service
class OrderWriter {
    private final OrderRepository orders;

    OrderWriter(OrderRepository orders) { this.orders = orders; }

    // Short transaction scope means short hold time.
    // Called from another bean so Spring's transactional proxy is applied.
    @Transactional
    public Order save(Cart cart, PriceQuote quote) {
        return orders.save(Order.from(cart, quote));
    }
}

The remote pricing call runs outside the transaction, so each request holds a pooled connection only for the database writes instead of for the whole HTTP round trip.

How do you budget database connections across every application instance?

That per-instance number is only half the budget. Every replica opens its own pool, so the database sees maximumPoolSize multiplied by every process that can be running at once, and that total has to fit under the server's connection limit with headroom left over.

The formula to plug your numbers into:

required = (max replicas + deploy surge) × maximumPoolSize + batch jobs + migration tools + reserved (admin, monitoring, replication)

Illustrative estimate (assumed numbers, not a benchmark):

Consumer Assumed count Pool size Connections
Autoscaling maximum 12 pods 20 240
Rolling-deploy surge 3 extra pods 20 60
Nightly batch job 2 workers 10 20
Migration tool 1 2 2
Admin, monitoring, replication — — 15
Total 337

A pool of 20 looks modest when you test one pod. The problem shows up later. The autoscaler adds replicas during a traffic spike, and a rolling deploy runs old and new pods side by side. Together they push the total past a limit of, say, 300. New connections are then refused at exactly the moment load peaks. Size for the autoscaling maximum plus surge, not for today's replica count.

The total also affects cost. Each server-side connection holds memory whether it is busy or idle. Teams often move to a larger database instance only to make room for oversized pools. In that case, shrinking maximumPoolSize per pod is usually the cheaper fix, and if pod counts keep growing, an external pooler becomes the better option.

Which spring.datasource.hikari settings matter, and what should they be set to?

With the instance-level budget fixed, the remaining work is in six properties under spring.datasource.hikari.*, written in kebab-case in application.yml (for example, maximum-pool-size).

Fixed versus variable pool. Setting minimum-idle equal to maximum-pool-size gives a fixed pool. Every connection is open from startup, so behavior is predictable and a traffic spike never has to wait for TCP, TLS and authentication handshakes. The cost is that each pod holds its full allocation of database connections even when idle. A smaller minimum-idle releases those connections during quiet periods. The drawback is that it has to create new ones during spikes, which is exactly when that added latency hurts most. idle-timeout only applies in this variable mode.

max-lifetime should sit a few seconds to a few minutes below the shortest idle or session cutoff on the path: firewalls, NAT gateways, load balancers and the database's own timeout. If it is set higher, those devices can silently drop connections the pool still considers valid. If it is set very short, the pool keeps tearing down and rebuilding connections for no benefit.

leak-detection-threshold only logs a warning with the borrowing stack trace. It does not reclaim the connection. Set it above your longest legitimate transaction, or batch jobs will bury real leaks in false alarms.

The example application.yml follows this section.

Setting Controls Too low Too high
maximum-pool-size Concurrent connections per instance Threads queue, timeouts under load Database overload, exceeds connection budget
minimum-idle Connections kept open when idle Spike latency while connections are created Idle connections held on every pod
connection-timeout Wait time for a free connection Spurious failures on brief bursts Request threads pile up behind a stalled pool
idle-timeout When surplus idle connections close Constant connection churn Resources held long after load drops
max-lifetime Maximum age of a connection Churn and reconnect overhead Connections dropped by network or database first
leak-detection-threshold Borrow duration before a warning False alarms on long transactions Real leaks go unnoticed
spring:
  datasource:
    url: jdbc:postgresql://db.internal.example:5432/orders
    username: orders_app
    password: ${DB_PASSWORD}          # injected from the environment, never committed
    hikari:
      # Per-instance share of the database connection budget
      # (e.g. 100 usable connections / 8 pods, minus headroom).
      maximum-pool-size: 10
      # Equal to maximum-pool-size: fixed pool, no handshake cost during spikes.
      # Lower it only if idle connections across all pods are a real problem.
      minimum-idle: 10
      # Max wait (ms) for a connection before SQLException.
      # Fail fast enough that callers can shed load instead of piling up.
      connection-timeout: 3000
      # Only takes effect when minimum-idle < maximum-pool-size.
      idle-timeout: 600000            # 10 minutes
      # Keep below the shortest idle/session cutoff on the path
      # (firewall, NAT, load balancer, database). Assumes a 30-minute cutoff here.
      max-lifetime: 1680000           # 28 minutes
      # Logs a warning with the borrowing stack trace; does not reclaim.
      # Set above the longest legitimate transaction (assumed ~60 s batch job).
      leak-detection-threshold: 90000 # 90 seconds
      pool-name: orders-pool          # makes logs and metrics easier to attribute

An application.yml that configures a fixed-size HikariCP pool, sets max-lifetime just under an assumed 30-minute network idle cutoff, and sets leak detection above the longest expected transaction.

Is it pool exhaustion or database saturation?

When requests slow down and connectionTimeout errors appear, check both ends of the connection before changing any setting. With Micrometer and Actuator on the classpath, HikariCP publishes hikaricp.connections.active, idle, pending, acquire (time spent waiting for a connection) and usage (time a connection is held). Compare these with what the database reports: active sessions, wait events, lock waits and CPU.

The key question is whether the database is busy. If threads are pending while the database sits mostly idle, connections are being held without doing work. Common causes are slow remote calls inside @Transactional methods or connections that are never returned. If threads are pending while the database is saturated, the pool is doing its job: it is queuing work the database cannot absorb.

Raising the pool size is tempting because it makes the pending count drop right away. On a saturated database, though, more connections mean more concurrent queries competing for CPU, I/O and locks. Each query slows down, hold time rises, and the backlog returns larger than before. A bigger pool also hides the real causes: long transactions, N+1 queries, missing indexes and lock contention.

Pool signal Database signal Likely cause Action
High pending, long usage Low CPU, few active sessions Remote calls inside transactions, leaks Shrink transaction scope, enable leak detection
High pending, long usage High CPU, many reads Missing index, N+1 queries Fix the queries; keep pool size unchanged
High pending, long usage Lock wait events dominate Lock contention Shorten transactions, reorder updates
High pending, short usage Healthy Pool genuinely undersized Increase pool size within the connection budget
#!/usr/bin/env bash
# Incident triage: sample the pool side and the database side at the same moment.
# Assumes the Actuator metrics endpoint is exposed and the DB is PostgreSQL.
APP=
POOL=HikariPool-1   # default pool name unless spring.datasource.hikari.pool-name is set

# Pool side: gauges for active/idle/pending, timers for acquire (wait) and usage (hold).
for m in active idle pending acquire usage; do
  echo "== hikaricp.connections.$m"
  curl -s "$APP/hikaricp.connections.$m?tag=pool:$POOL" | jq -c '.measurements'
done

# Database side: what are the backends actually doing right now?
# Many 'idle in transaction' sessions with little CPU load points to held
# connections (remote calls inside @Transactional, leaks).
# Lock waits dominating points to contention; many 'active' sessions with
# no wait event while CPU is high points to saturation (N+1, missing indexes).
psql "host=db-host dbname=appdb user=readonly_user" -c "
  SELECT state,
         coalesce(wait_event_type, 'none') AS wait_type,
         coalesce(wait_event, 'none')      AS wait_event,
         count(*)                          AS sessions,
         max(now() - xact_start)           AS longest_xact
  FROM pg_stat_activity
  WHERE backend_type = 'client backend'
    AND datname = 'appdb'
  GROUP BY 1, 2, 3
  ORDER BY sessions DESC;"

# Pair this with host CPU from your monitoring before touching maximumPoolSize.

A triage script that reads HikariCP's active, idle, pending, acquire and usage metrics from Actuator and, in the same pass, groups PostgreSQL sessions by state and wait event, so you can match the result to a row of the decision table.

How should connectionTimeout and pool size fit your threading model?

A servlet container usually runs many more request threads than the pool has connections. That mismatch is intentional. When threads outnumber connections, the extra threads wait in HikariCP's queue inside the application, where they show up as pending. The alternative is opening more sessions against a database that is already at capacity, which makes every query slower.

That queue needs a deadline. Set connectionTimeout below the upstream request timeout, so a starved request fails while the caller still has time to retry or degrade gracefully. The trade-off runs in both directions:

  • Short timeout: brief spikes become visible 5xx errors.
  • Long timeout: the problem stays hidden until gateway timeouts fire and clients retry into the same full queue, which cascades.

Illustrative estimate (assumed numbers, not a benchmark): gateway timeout 5,000 ms, p99 database work 800 ms, other request handling 200 ms. connectionTimeout ≤ upstream timeout − p99 DB work − other handling = 5,000 − 800 − 200 = 4,000 ms. Pick a value below that ceiling, such as 2,000 ms, to leave the caller room to retry.

Virtual threads remove the thread-count ceiling, so the container no longer limits concurrency. The pool becomes the main limit, and you should size it deliberately rather than inherit a default.

Use separate pools when workloads have different latency profiles. A reporting query that holds a connection for 30 seconds should not occupy a slot that checkout requests need. A typical sketch uses two DataSource beans:

  • OLTP pool: marked @Primary, small, with a short connectionTimeout.
  • Reporting or batch pool: its own small cap, a longer timeout, and optionally pointed at a replica.

Bind each pool to its own @ConfigurationProperties prefix. Count both pools against the per-instance connection budget.

How do you validate pool size under load, and when should you use an external pooler instead?

Validate the number empirically. Replay the production query mix in a staging environment with production-sized data: the same ratio of reads to writes, the same transaction lengths, and the same slow outliers. A synthetic single-query benchmark hides the long transactions that actually hold connections. Hold offered load constant and step maximumPoolSize down and up, for example halving and doubling from the current value. At each step, record throughput, p99 latency, and the pending-threads metric. Plot all three. Throughput rises and then flattens. Past that knee, p99 usually gets worse because the database is spending effort on contention rather than on work. The smallest size at the knee is your answer, and it overrides any formula from earlier sections.

In-app tuning stops being enough when the fleet itself is the problem. Examples include hundreds of replicas, frequent autoscaling, or short-lived and serverless-style instances that open fresh pools on every cold start. An external pooler can multiplex many client connections onto a few server connections. That has costs. It adds a network hop. In transaction-level modes it can break session state, server-side prepared statements, temporary tables, and advisory locks.

Dimension In-app pool (HikariCP) External pooler/proxy
Latency No extra hop One added hop per round trip
Feature compatibility Full session semantics Session features may be restricted, depending on mode
Operational cost None beyond configuration Another component to deploy, monitor, and make highly available
Scaling behavior Server connections grow with instance count Server connections stay bounded as the fleet grows

For low-traffic services, skip all of this. The defaults plus a fleet-wide connection budget are sufficient, and further tuning adds risk without measurable benefit.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to hikaricp pool size, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.