llm-wiki/vault/20-evidence/official-docs/persistence-hikaricp-configuration-knobs.md

---
title: "official-doc / HikariCP — Configuration (knobs, baby!) Reference"
source_type: official-doc
url: https://github.com/brettwooldridge/HikariCP
archive_url:
vendor: brettwooldridge / HikariCP
related_branches: [feature-database-connection-pool-contract]
related_projects: []
tags: [official-doc, ca-tmpl, persistence, hikaricp, connection-pool, pool-sizing]
created: 2026-06-09
---

# official-doc / HikariCP — Configuration (knobs, baby!) Reference

> Layer: `raw/official-docs/` — HikariCP 공식 README의 "Configuration (knobs, baby!)" 섹션 원문 발췌 보존.
> Self-grep 검증 완료 (2026-06-09). 임시 파일: `/tmp/source-fetch-hikaricp-1749434400.txt`.

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-database-connection-pool-contract]] | HikariCP 커넥션 풀 설정 값(connectionTimeout, maxLifetime, idleTimeout, keepaliveTime, leakDetectionThreshold, validationTimeout, initializationFailTimeout, minimumIdle)의 기본값·최솟값·권고 사항 근거 |

## 출처 / Source

- 원본 URL: https://github.com/brettwooldridge/HikariCP
- 아카이브 URL: (없음)
- 저자 / 조직: Brett Wooldridge (brettwooldridge) — HikariCP 오픈소스 프로젝트
- 발행일: (상시 유지되는 README; 최신 커밋 기준)
- 마지막 확인일: 2026-06-09

## 왜 저장했는지 / Why archived

HikariCP 커넥션 풀 설정 각 항목의 **공식 기본값·최솟값·동작 의미·권고 사항**을 verbatim으로 보관하여, `feature-database-connection-pool-contract` 브랜치의 모든 풀 설정 결정(connectionTimeout·maxLifetime 등 8개 knob)이 공식 문서를 정확히 인용할 수 있게 한다.

## README 분류 체계 — Frequently used / Infrequently used

HikariCP README는 knob을 다음과 같이 분류한다:

- **Essentials** (필수): `dataSourceClassName`, `jdbcUrl`, `username`, `password`
- **Frequently used** (자주 사용): `autoCommit`, `connectionTimeout`, `idleTimeout`, `keepaliveTime`, `maxLifetime`, `connectionTestQuery`, `minimumIdle`, `maximumPoolSize`, `metricRegistry`, `healthCheckRegistry`, `poolName`
- **Infrequently used** (드물게 사용): `initializationFailTimeout`, `isolateInternalQueries`, `allowPoolSuspension`, `readOnly`, `registerMbeans`, `catalog`, `connectionInitSql`, `driverClassName`, `transactionIsolation`, `validationTimeout`, `leakDetectionThreshold`, `dataSource`, `schema`, `threadFactory`, `scheduledExecutor`, `exceptionOverride`

> 주의: `validationTimeout`과 `leakDetectionThreshold`는 README에서 **Infrequently used** 섹션에 위치하지만, 프로덕션 운영에서 설정이 필요한 경우가 많다.

## 핵심 인용 / Key quotes (verbatim, self-grep 통과)

> [§Frequently used — connectionTimeout, line 191–194]
> "This property controls the maximum number of milliseconds that a client (that's you) will wait
> for a connection from the pool.  If this time is exceeded without a connection becoming
> available, a SQLException will be thrown.  Lowest acceptable connection timeout is 250 ms.
> *Default: 30000 (30 seconds)*"

> [§Frequently used — maxLifetime, line 217–224]
> "This property controls the maximum lifetime of a connection in the pool.  An in-use connection will
> never be retired, only when it is closed will it then be removed.  On a connection-by-connection
> basis, minor negative attenuation is applied to avoid mass-extinction in the pool.  **We strongly recommend
> setting this value, and it should be several seconds shorter than any database or infrastructure imposed
> connection time limit.**  A value of 0 indicates no maximum lifetime (infinite lifetime), subject of
> course to the ``idleTimeout`` setting.  The minimum allowed value is 30000ms (30 seconds).
> *Default: 1800000 (30 minutes)*"

> [§Frequently used — idleTimeout, line 197–204]
> "This property controls the maximum amount of time that a connection is allowed to sit idle in the
> pool.  **This setting only applies when ``minimumIdle`` is defined to be less than ``maximumPoolSize``.**
> Idle connections will *not* be retired once the pool reaches ``minimumIdle`` connections. [...] The minimum allowed value is 10000ms
> (10 seconds).
> *Default: 600000 (10 minutes)*"

> [§Frequently used — keepaliveTime, line 207–215]
> "This property controls how frequently HikariCP will attempt to keep a connection alive, in order to prevent
> it from being timed out by the database or network infrastructure. This value must be less than the
> `maxLifetime` value. A "keepalive" will only occur on an idle connection. [...] The minimum
> allowed value is 30000ms (30 seconds), but a value in the range of minutes is most desirable.
> *Default: 120000 (2 minutes)*"

> [§Frequently used — minimumIdle, line 235–240]
> "However, for maximum performance and responsiveness to spike demands,
> we recommend *not* setting this value and instead allowing HikariCP to act as a *fixed size* connection pool.
> *Default: same as maximumPoolSize*"

> [§Infrequently used — initializationFailTimeout, line 273–284]
> "This property controls whether the pool will "fail fast" if the pool cannot be seeded with
> an initial connection successfully.  Any positive number is taken to be the number of
> milliseconds to attempt to acquire an initial connection; the application thread will be
> blocked during this period.  If a connection cannot be acquired before this timeout occurs,
> an exception will be thrown. [...] If the value is zero (0), HikariCP will attempt to obtain and validate a connection. [...] A value less than zero will bypass any initial
> connection attempt, and the pool will start immediately while trying to obtain connections
> in the background.
> *Default: 1*"

> [§Infrequently used — validationTimeout, line 336–338]
> "This property controls the maximum amount of time that a connection will be tested for aliveness.
> This value must be less than the ``connectionTimeout``.  Lowest acceptable validation timeout is 250 ms.
> *Default: 5000*"

> [§Infrequently used — leakDetectionThreshold, line 341–344]
> "This property controls the amount of time that a connection can be out of the pool before a
> message is logged indicating a possible connection leak.  A value of 0 means leak detection
> is disabled.  Lowest acceptable value for enabling leak detection is 2000 (2 seconds).
> *Default: 0*"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| HIKARI-CFG-C1 | `connectionTimeout` 기본값은 30000ms(30초)이며, 클라이언트가 풀로부터 커넥션을 기다리는 최대 시간이다. 최솟값은 250ms이며 초과 시 SQLException이 발생한다. | [§Frequently used — connectionTimeout] "Lowest acceptable connection timeout is 250 ms. *Default: 30000 (30 seconds)*" | `official-reference` | HikariCP 모든 버전 (기본값 변경 없는 한) | 애플리케이션의 실제 SLA 요건에 맞는 값이 30000ms라는 것은 증명하지 않음 |
| HIKARI-CFG-C2 | `maxLifetime` 기본값은 1800000ms(30분)이며, DB/인프라의 커넥션 제한 시간보다 **수 초 짧게** 설정해야 한다고 공식이 강하게 권고한다. | [§Frequently used — maxLifetime] "**We strongly recommend setting this value, and it should be several seconds shorter than any database or infrastructure imposed connection time limit.** [...] *Default: 1800000 (30 minutes)*" | `official-reference` | HikariCP 모든 버전 | 정확히 몇 초 짧게 설정해야 하는지 수치를 지정하지 않음; DB별 wait_timeout 값은 별도 확인 필요 |
| HIKARI-CFG-C3 | `idleTimeout`은 `minimumIdle < maximumPoolSize` 일 때만 적용된다. 기본값은 600000ms(10분), 최솟값은 10000ms(10초)이다. | [§Frequently used — idleTimeout] "**This setting only applies when `minimumIdle` is defined to be less than `maximumPoolSize`.**  [...] *Default: 600000 (10 minutes)*" | `official-reference` | HikariCP 모든 버전 | minimumIdle = maximumPoolSize(고정 크기 풀) 설정 시에는 idleTimeout이 아무 효과 없음을 이 자료만으로는 실험 검증 불가 |
| HIKARI-CFG-C4 | `keepaliveTime`은 DB/네트워크 인프라에 의한 유휴 커넥션 타임아웃을 방지하기 위한 ping 주기이다. `maxLifetime`보다 작아야 하며, 기본값은 120000ms(2분), 최솟값은 30000ms(30초)이다. | [§Frequently used — keepaliveTime] "This property controls how frequently HikariCP will attempt to keep a connection alive, in order to prevent it from being timed out by the database or network infrastructure. This value must be less than the `maxLifetime` value. [...] *Default: 120000 (2 minutes)*" | `official-reference` | HikariCP 모든 버전 | DB/방화벽의 실제 idle timeout 값은 별도 확인 필요; keepaliveTime이 해당 timeout보다 짧아야 효과 있음 |
| HIKARI-CFG-C5 | `leakDetectionThreshold`는 커넥션이 풀 밖에 있는 허용 시간(ms)이며, 기본값은 0(비활성화)이다. 활성화 최솟값은 2000ms(2초)이다. | [§Infrequently used — leakDetectionThreshold] "A value of 0 means leak detection is disabled.  Lowest acceptable value for enabling leak detection is 2000 (2 seconds). *Default: 0*" | `official-reference` | HikariCP 모든 버전 | 프로덕션에서 적절한 임계값이 2000ms라는 것은 증명하지 않음; long-running 트랜잭션의 경우 false positive 가능 |
| HIKARI-CFG-C6 | `validationTimeout`은 커넥션 aliveness 검증에 허용된 최대 시간이며, 기본값은 5000ms, 최솟값은 250ms이고 `connectionTimeout`보다 작아야 한다. | [§Infrequently used — validationTimeout] "This value must be less than the `connectionTimeout`.  Lowest acceptable validation timeout is 250 ms. *Default: 5000*" | `official-reference` | HikariCP 모든 버전 | validationTimeout을 5000ms로 두는 것이 항상 적절하다는 것은 증명하지 않음 |
| HIKARI-CFG-C7 | `initializationFailTimeout`은 풀 초기화 시 fail-fast 동작을 제어한다. 양수이면 초기 커넥션 획득을 해당 ms 동안 시도(실패 시 예외 throw), 0이면 획득 시도하되 검증 실패 시 예외 throw, 음수이면 초기 커넥션 시도를 우회하고 즉시 시작한다. 기본값은 1이다. | [§Infrequently used — initializationFailTimeout] "Any positive number is taken to be the number of milliseconds to attempt to acquire an initial connection [...] *Default: 1*" | `official-reference` | HikariCP 모든 버전 | 컨테이너 환경에서 DB 시작 순서 보장 없이 음수값 설정이 safe하다는 것은 증명하지 않음 |
| HIKARI-CFG-C8 | HikariCP는 `minimumIdle`을 설정하지 말고 고정 크기 풀로 운영할 것을 공식 권고한다. 기본값은 `maximumPoolSize`와 같다. | [§Frequently used — minimumIdle] "for maximum performance and responsiveness to spike demands, we recommend *not* setting this value and instead allowing HikariCP to act as a *fixed size* connection pool. *Default: same as maximumPoolSize*" | `official-reference` | HikariCP 모든 버전 | 고정 크기 풀이 모든 워크로드 패턴에서 탄력적 풀보다 낫다는 것은 일반적으로 증명하지 않음; 스파이크 수요에 대한 응답성 최적화 맥락의 권고임 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `HIKARI-CFG-C1`: connectionTimeout 기본값(30000ms)·최솟값(250ms)·초과 시 SQLException 발생
  - `HIKARI-CFG-C2`: maxLifetime 기본값(1800000ms)·최솟값(30000ms)·DB 제한 시간보다 수 초 짧게 설정해야 한다는 공식 강한 권고
  - `HIKARI-CFG-C3`: idleTimeout 기본값(600000ms)·최솟값(10000ms)·minimumIdle < maximumPoolSize 조건
  - `HIKARI-CFG-C4`: keepaliveTime 기본값(120000ms)·최솟값(30000ms)·maxLifetime 미만 조건·유휴 커넥션 타임아웃 방지 목적
  - `HIKARI-CFG-C5`: leakDetectionThreshold 기본값(0=비활성화)·활성화 최솟값(2000ms)
  - `HIKARI-CFG-C6`: validationTimeout 기본값(5000ms)·최솟값(250ms)·connectionTimeout 미만 조건
  - `HIKARI-CFG-C7`: initializationFailTimeout 기본값(1)·양수/0/음수 각각의 fail-fast 의미론
  - `HIKARI-CFG-C8`: minimumIdle 기본값(maximumPoolSize)·고정 크기 풀 권고

- 이 자료가 증명하지 않는 것:
  - 특정 애플리케이션·DB 조합에서의 최적값 (MySQL wait_timeout, PostgreSQL tcp_keepalives_idle 등은 별도 DB 공식 문서 필요)
  - ca-tmpl 프로젝트에서 실제로 이 값들이 적용되었는지 (needs-confirmation)
  - `keepaliveTime`이 실제로 DB 방화벽 idle timeout을 방지하는지 end-to-end 검증

- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl의 DB(MySQL/PostgreSQL)의 `wait_timeout` / `idle_in_transaction_session_timeout` 값 확인 → maxLifetime 설정의 기준
  - 컨테이너 오케스트레이션 환경(K8s)에서 `initializationFailTimeout` 음수값 vs. `spring.datasource.hikari.initialization-fail-timeout=1` 기본값 유지 여부

## 메모 / Notes

- `validationTimeout`과 `leakDetectionThreshold`가 README에서 **Infrequently used** 섹션에 위치하지만, 프로덕션 안전성상 명시적으로 설정 권장 대상이다.
- `maxLifetime` 설정은 README에서 "single most important setting"이라는 표현은 없으나, "We strongly recommend" 강도로 서술된 유일한 timeout knob이다.
- `keepaliveTime` 기본값이 2026-06 기준 GitHub README에서는 120000ms(2분)으로 표시된다. 일부 이전 버전에서 0(비활성화)이었으므로 사용하는 HikariCP 버전 확인 필요.
- 추가로 봐야 할 동일 출처 페이지: [HikariCP About Pool Sizing](https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing)

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/mysql-innodb-transaction-isolation-official]] (DB 설정이 pool에 영향), [[raw/official-docs/postgres-transaction-isolation-official]]
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/connection-pool-hikaricp]]` (생성 시)