---
title: HikariCP — About Pool Sizing & MBean Monitoring (GitHub Wiki)
source_type: official-doc
status: raw
confidence: high
url: https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing
archive_url:
tags: [ca-persistence-failure, hikari, connection-pool, db, tuning, official-doc]
related_branches: [feature-persistence-failure-baseline, feature-metrics-alerting-contract]
related_projects: [ca-skeleton-operational-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# HikariCP — About Pool Sizing & MBean Monitoring

> Layer: `raw/official-docs/` — HikariCP GitHub Wiki ("About Pool Sizing" + "MBean (JMX) Monitoring and Management") verbatim 발췌. ca-tmpl persistence baseline 의 Hikari pool 크기 결정과 alert threshold 의 1차 근거.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-persistence-failure-baseline]] | "pool 은 크게 둘수록 좋다" 직관을 거부하는 공식 근거 → connection pool 크기를 작게 유지하는 default 결정의 baseline |
| [[raw/branch-notes/feature-metrics-alerting-contract]] | Hikari alert threshold (`pool wait p99 > 100ms 5분`, `pool exhaustion > 1m`) 를 MBean / Micrometer metric 으로 측정 가능하다는 사실 근거 |

특정 branch 없이 foundational 조사로 수집한 경우:

- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl operational contract 의 persistence failure / metrics 계약 초기 조사

## 컨텍스트 / 왜 저장했는지

ca-tmpl persistence baseline 의 **Hikari pool wait p99 / pool exhaustion alert threshold** 정의 근거. pool 크기 결정과 metric 노출 기준을 공식 wiki 에서 인용. 또한 "pool 은 크다고 좋은 것이 아니다" 라는 직관 반박을 공식 출처로 확보.

## 출처 / Source

- 원본 URL: https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing
- 보조 URL: https://github.com/brettwooldridge/HikariCP/wiki/MBean-(JMX)-Monitoring-and-Management
- 아카이브 URL: (미수집)
- 저자 / 조직: Brett Wooldridge (HikariCP maintainer)
- 발행일: rolling wiki
- 마지막 확인일: 2026-05-27 (WebFetch 검증 완료 — `About Pool Sizing` + MBean 페이지)
- 보조 자료: PgBouncer documentation, Oracle "Real-World Performance" pool sizing talk (별도 raw 미수집)

## 핵심 인용 / Key quotes (verbatim)

> [§Axiom: You want a small pool, saturated with threads waiting for connections.] "You want a small pool, saturated with threads waiting for connections."

> [§The Formula] "The formula below is provided by the PostgreSQL project as a starting point, but we believe it will be largely applicable across databases. You should test your application, i.e. simulate expected load, and try different pool settings _around_ this starting point: connections = ((core_count * 2) + effective_spindle_count)"

> [§10,000 Simultaneous Front-End Users] "If you have 10,000 front-end users, having a connection pool of 10,000 would be shear insanity. 1000 still horrible. Even 100 connections, overkill."

> [§10,000 Simultaneous Front-End Users] "You want a small pool of a few dozen connections at most, and you want the rest of the application threads blocked on the pool awaiting connections."

> [§Pool-locking] "pool size = Tn x (Cm - 1) + 1" (where Tn = maximum number of threads, Cm = maximum simultaneous connections held by a single thread — "minimum required to avoid deadlock")

> [§MBean — Accessible Attributes] "IdleConnections, ActiveConnections, TotalConnections, ThreadsAwaitingConnection"

> [§MBean — Invocable Actions] `softEvictConnections()`, `suspendPool()`, `resumePool()`

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| HIKARI-POOL-C1 | HikariCP 의 axiom: pool 은 작게 유지하고, 나머지 application thread 는 connection 대기에서 block 시킨다 | [§Axiom] "You want a small pool, saturated with threads waiting for connections." | `official-vendor-doc` | HikariCP 사용 환경 일반 | "작은 pool" 의 정확한 크기 (특정 절대값) 를 정의하지는 않음 — formula 와 별도 |
| HIKARI-POOL-C2 | PostgreSQL project 가 제공하는 starting-point formula: `connections = ((core_count * 2) + effective_spindle_count)`. 단, 어디까지나 starting point 이며 실제 부하 테스트로 조정 권고 | [§The Formula] "...starting point: connections = ((core_count * 2) + effective_spindle_count)" + "You should test your application, i.e. simulate expected load, and try different pool settings _around_ this starting point" | `official-vendor-doc` | 디스크 IO-bound DB 워크로드 starting point | 모든 워크로드(특히 SSD/NVMe, in-memory)에 그대로 적용된다는 뜻은 아님 — "starting point" 명시. spinning disk 가정 |
| HIKARI-POOL-C3 | 10,000 front-end user 에게 10,000 connection pool 은 "shear insanity"; 1,000 도 horrible; 100 조차 overkill. "a few dozen connections at most" 권고 | [§10,000 Simultaneous Front-End Users] "If you have 10,000 front-end users, having a connection pool of 10,000 would be shear insanity. 1000 still horrible. Even 100 connections, overkill." + "You want a small pool of a few dozen connections at most" | `official-vendor-doc` | high-concurrency web application sizing 직관 반박 | 모든 application 에 "수십 개" 가 충분하다는 절대값 보증은 아님 — formula + 부하테스트 필요. ("just trust me" 같은 paraphrase 는 페이지에 verbatim 없음) |
| HIKARI-POOL-C4 | Pool-locking 방지 minimum 공식: `pool size = Tn × (Cm − 1) + 1` (Tn=max threads, Cm=max simultaneous connections per thread) | [§Pool-locking] "pool size = Tn x (Cm - 1) + 1" | `official-vendor-doc` | 한 thread 가 동시에 다수 connection 을 점유할 수 있는 워크로드 | 이 값이 최적 (optimal) 이라는 뜻 아님 — "minimum required to avoid deadlock" |
| HIKARI-POOL-C5 | HikariPool MBean 은 다음 attribute 노출: `IdleConnections`, `ActiveConnections`, `TotalConnections`, `ThreadsAwaitingConnection`. Invocable: `softEvictConnections()`, `suspendPool()`, `resumePool()` | [§MBean — Accessible Attributes] "IdleConnections, ActiveConnections, TotalConnections, ThreadsAwaitingConnection" | `official-vendor-doc` | JMX / MBean 직접 조회 환경 | snapshot 값이며 page warning: "values are extremely ephemeral and reflect a snapshot in time when measured" — programmatic 결정 근거로 직접 사용 비권장 |
| HIKARI-POOL-C6 | Micrometer 통합이 제공하는 metric 이름 (`hikaricp.connections.active`, `.idle`, `.pending`, `.acquire` timer, `.usage` timer 등) | (원본 frontmatter 발췌 — HikariCP 측 wiki 가 아닌 Micrometer / Spring Boot Actuator 통합 문서에서 유래) | `needs-confirmation` | Spring Boot + Micrometer 환경 | HikariCP 공식 wiki 페이지 자체가 이 metric 명을 직접 정의하지는 않음 — Micrometer / Spring Boot 측 별도 출처 필요 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `HIKARI-POOL-C1` ~ `C5`: pool 크기 axiom, formula, pool-locking 공식, MBean attribute/action 이름
  - "작은 pool + 대기 thread" 가 throughput 측면에서 합리적이라는 정성적 근거
- **이 자료가 증명하지 않는 것**:
  - 정확한 SLA 수치 (예: "p99 acquire > 100ms 가 위험 임계") 는 HikariCP 가 직접 말하지 않음 — 운영자가 정해야 하는 SLO
  - `hikaricp.connections.acquire` 같은 Micrometer metric **이름** 은 HikariCP wiki 본문에 직접 등장하지 않음 (`HIKARI-POOL-C6` 참조 — Micrometer / Spring Boot Actuator 측 별도 검증 필요)
  - SSD/NVMe 또는 PgBouncer transaction pooling 환경에서의 formula 보정값은 본 페이지 범위 밖
  - "just trust me" 같은 paraphrase 는 현재 페이지에 verbatim 없음 — 원본 frontmatter 의 해당 인용은 paraphrase 임을 명시
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 `pool wait p99 > 100ms 5분` threshold 는 우리 SLA 기준이지 HikariCP 권고가 아님 — 별도 SLO 근거 문서 필요
  - Micrometer metric 이름 (`hikaricp.connections.acquire`, `.pending`, `.timeout`, `.creation`) 의 정확한 정의는 Spring Boot Actuator / Micrometer 측 raw 자료 추가 필요
  - PgBouncer 와 결합 시 application-side Hikari pool 크기의 의미 (별도 자료)

## 메모 / Notes (내 프로젝트 해석 — 검증 전 추론)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- **핵심 의미**:
  - pool 은 크게 둘수록 좋다는 직관이 틀렸다 (`HIKARI-POOL-C1`, `C3`). DB 의 동시 작업 처리량은 core 수에 묶임. pool 이 커지면 context switch overhead 로 throughput 감소.
  - pool 대기 시간 (`hikaricp.connections.acquire`) 이 진짜 SLA signal. 단순 active/max 비율이 아님 (HikariCP wiki 가 권고하는 axiom 의 해석).
- **ca-tmpl alert threshold 매핑 (해석)**:
  - `pool wait p99 > 100ms 5분` → `hikaricp.connections.acquire` p99 로 측정 가정 (Micrometer metric 명 확인 필요)
  - `pool exhaustion (active = max) > 1분` → `hikaricp.connections.pending > 0` 지속
- **추가 권장 metric (Micrometer 측 확인 후)**:
  - `hikaricp.connections.timeout` — `connectionTimeout` 초과 누적
  - `hikaricp.connections.creation` — 신규 connection 생성 시간 (DB/network 이슈 signal)
- **한계**: 공식 (`cores*2 + spindles`) 은 spinning disk 기준. SSD/NVMe 면 보정 필요. PgBouncer transaction pooling 을 쓰면 application pool size 의미가 달라짐 (`HIKARI-POOL-C2` 가 "starting point" 로 명시).

## Related / 관련

- 같은 주제 다른 official-doc / company-tech-blog: (Micrometer + Spring Boot Actuator 의 Hikari metric 정의는 별도 raw 후속 수집 필요)
- 인용하는 branch:
  - [[raw/branch-notes/feature-persistence-failure-baseline]]
  - [[raw/branch-notes/feature-metrics-alerting-contract]]
- 인용하는 wiki: (미작성 — `/ingest` 시 `wiki/concepts/connection-pooling` 또는 `wiki/concepts/hikaricp-tuning` 후보)
- 대안 그룹 (ca-tmpl 결정 컨텍스트): **Group G-C — Persistence failure** (Hikari 단일 pool / PgBouncer 사이드카 / DataSource proxy 측정 / per-tenant separate pool)