stemedb/applications/aphoria/dogfood/dbpool/docs/sources/hikaricp-config.md

HikariCP Configuration Guide

Source: HikariCP GitHub Repository and 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