DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유

DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유

커넥션 풀은 많을수록 좋지 않다. DB가 동시에 처리할 수 있는 양보다 커넥션이 더 많아지면 대기열만 늘어난다.

중급 운영에서는 애플리케이션 스레드 수와 DB 동시 실행 능력, 쿼리 특성을 함께 보고 풀 크기를 정해야 한다.

왜 지금 이 주제가 중요한가

• 커넥션 부족은 바로 느껴지지만, 과도한 풀 크기는 조용히 DB를 포화시킨다.
• 풀 대기 시간은 애플리케이션 병목인지 DB 병목인지 구분하는 핵심 지표다.
• thread pool, HTTP timeout, transaction 길이와 연결하지 않으면 숫자만 바꾸는 튜닝이 된다.

핵심 설계 포인트

• pool size는 DB CPU 코어 수와 평균 쿼리 시간, 동시성 모델을 기준으로 계산한다.
• connection timeout은 사용자 요청 timeout보다 짧아야 한다.
• 읽기/쓰기 풀 분리나 bulk job 전용 풀을 통해 서로 다른 워크로드를 격리한다.
• 긴 트랜잭션과 N+1 쿼리를 먼저 줄이지 않으면 풀 확장은 임시 처치에 그친다.

예시 구성

spring:
  datasource:
    hikari:
      maximum-pool-size: 24
      minimum-idle: 8
      connection-timeout: 2000

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

1. 현재 Hikari 지표(active, idle, pending, acquire time)를 수집한다.
2. DB slow query와 app thread dump를 같이 확인해 병목 위치를 구분한다.
3. 커넥션 풀 크기를 소폭 조정하며 p95 acquire time 변화를 비교한다.
4. 배치 잡과 온라인 요청이 같은 풀을 쓰는지 점검하고 필요하면 분리한다.
5. 최종 값은 문서와 코드 설정에 같이 남긴다.

운영 체크포인트

• 풀 크기를 올리기 전에 쿼리 최적화와 transaction length를 먼저 본다.
• DB max_connections와 애플리케이션 인스턴스 수를 같이 계산한다.
• 장애 시 pending thread가 폭증하는지 대시보드에 노출한다.

운영 지표/알람 추천

• event loop lag 또는 GC pause time
• CPU 사용률, 스레드/핸들러 대기 시간
• 메모리 사용량과 heap pressure
• timeout/retry 비율과 다운스트림 오류 상관관계

빠른 점검 명령/쿼리

# event loop lag 또는 GC pause 로그를 먼저 본다
# CPU 100% 구간과 외부 호출 timeout 구간을 같이 본다
# 병목 함수/핫스팟이 요청 경로와 직접 연결되는지 확인

구조화 로그 필드 추천

• traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
• endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

• 운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
• 기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
• 팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행 또는 데이터 유실: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. 응답이 느리니 pool size부터 늘린다: DB 포화를 더 빠르게 만든다.
2. connection timeout이 너무 길다: 사용자 요청이 불필요하게 오래 매달린다.
3. batch job과 API 트래픽이 같은 풀을 쓴다: 서로의 tail latency를 망친다.

바로 적용 템플릿

풀 튜닝 템플릿:
DB max_connections / 앱 인스턴스 수 / 목표 pool size
connection timeout < request timeout
active/pending/acquire time 대시보드
긴 쿼리 상위 N개 점검

검증 방법

• 부하 테스트에서 acquire time p95가 줄었는지, 동시에 DB CPU가 포화되지 않는지 확인한다.
• 일부 인스턴스 재시작 상황에서도 DB max_connections를 넘지 않는지 검증한다.

장애 대응 Runbook(초안)

• 현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
• 범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
• 근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

1. 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
3. 관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "DB 커넥션 풀 튜닝 실전: HikariCP maximumPoolSize를 감으로 정하면 안 되는 이유"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

• HikariCP Configuration
• Spring Boot DataSource Configuration