# HikariCP Configuration Guide

**Source:** [HikariCP GitHub Repository](https://github.com/brettwooldridge/HikariCP) and [About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)

**Authority Tier:** 2 (Vendor - Industry best practices)

## Pool Sizing

### Core Formula

**Primary calculation:** `connections = ((core_count * 2) + effective_spindle_count)`

This PostgreSQL-originated formula serves as the starting point. For a 4-core server with one hard disk: `(4 × 2) + 1 = 9-10 connections` is the recommended pool size.

### Key Principles

**Small Pool Philosophy:** "You want a small pool, saturated with threads waiting for connections." Rather than provisioning large pools for many users, maintain minimal connections sized to database query capacity.

**Performance Principle:** Reducing pool size alone (without other changes) can yield dramatic improvements—the referenced Oracle video demonstrated response time improvements from ~100ms to ~2ms through downsizing.

**Spindle Consideration:** Effective spindle count is zero for fully cached datasets and approaches actual spindle quantity as cache hit rates decline. SSD systems require *fewer* connections than mechanical drives due to eliminated seek times and rotational delays.

### Deadlock Prevention Formula

For applications where threads hold multiple simultaneous connections:

`pool_size = (Tn × (Cm - 1)) + 1`

Where Tn = maximum threads, Cm = maximum simultaneous connections per thread

**Example:** 3 threads requiring 4 connections each: `(3 × 3) + 1 = 10 minimum`

### Mixed Workload Caveats

- Mixed workloads (long and short transactions) benefit from separate pool instances
- Load testing around the formula's baseline is essential for specific deployments
- Over-provisioning creates unnecessary resource contention and context-switching overhead

## Timeout Configuration

### maxLifetime

**Requirement:** Set several seconds shorter than database connection limits.

- **Minimum:** 30 seconds
- **Default:** 30 minutes (1,800,000 ms)
- **Recommendation:** "We strongly recommend setting this value, and it should be several seconds shorter than any database or infrastructure imposed connection time limit."

### idleTimeout

Controls how long connections sit unused before removal.

- **Minimum:** 10 seconds
- **Default:** 10 minutes (600,000 ms)
- **Note:** Only applies when minimumIdle is less than maximumPoolSize

### connectionTimeout

Maximum wait time for acquiring a connection.

- **Minimum:** 250ms
- **Default:** 30 seconds (30,000 ms)
- **Behavior:** Exceeding this triggers SQLException

### validationTimeout

Tests connection aliveness; must be less than connectionTimeout.

- **Minimum:** 250ms
- **Default:** 5 seconds (5,000 ms)

### keepaliveTime

Prevents database timeout by pinging idle connections.

- **Minimum:** 30 seconds
- **Default:** 2 minutes (120,000 ms)
- **Requirement:** Should be less than maxLifetime

## Pool Sizing Parameters

### maximumPoolSize

- **Default:** 10 connections
- **Recommendation:** Read pool sizing analysis; excessive connections negatively impact performance

### minimumIdle

- **Default:** Same as maximumPoolSize (fixed-size pool)
- **Recommendation:** Fixed-size pools recommended for optimal responsiveness

## Leak Detection

### leakDetectionThreshold

Logs possible connection leaks when a connection is out of the pool longer than this duration.

- **Minimum:** 2 seconds (2,000 ms) for enabling
- **Default:** Disabled (0)
- **Use Case:** Development/debugging tool to identify connection leaks

## Validation Strategy

### Connection Testing

**For JDBC4 drivers:** Avoid connectionTestQuery—use built-in `isValid()` method instead for better performance.

**For legacy drivers:** Require custom validation queries (e.g., `SELECT 1` for PostgreSQL).

## Critical System Requirements

**Time Synchronization:** "It is imperative that your server is synchronized with a time-source such as an NTP server. Especially if your server is running within a virtual machine."

Unsynchronized clocks compromise reliability and performance of timeout mechanisms and connection lifecycle management.

## Prescriptive Statements for Claims

1. **MUST set maxLifetime:** Connection pools must configure maxLifetime to be several seconds shorter than database connection time limits
2. **MUST NOT exceed recommended pool size:** Pool size should follow the formula `(core_count × 2) + effective_spindle_count` as a starting point
3. **SHOULD use small pools:** Pools should be sized for saturation rather than provisioning large pools
4. **MUST configure minimumIdle ≤ maximumPoolSize:** minimumIdle cannot exceed maximumPoolSize
5. **MUST set connectionTimeout ≥ 250ms:** Connection timeout must be at least 250ms
6. **MUST set validationTimeout < connectionTimeout:** Validation timeout must be less than connection timeout
7. **SHOULD enable leak detection in development:** leakDetectionThreshold should be set to 2+ seconds during development
8. **MUST synchronize server time:** Servers must be synchronized with NTP for reliable timeout behavior