개요
현재 직장의 프로젝트를 진행하면서 HikariCP 관련 설정을 건드리게 되었다.
HikariCP는 Spring Boot에서 기본으로 제공하는 데이터 소스이며, 추가 설정의 경우 코드 또는 application.yml(또는 properties)에서 구성할 수 있다.
사실 이전까지 개인 / 회사 프로젝트를 진행했을 때 HikariCP 관련 설정을 많이 건드려 본 적이 없었다. 그도 그럴 것이, 첫번째 직장에서는 주력 DB가 MongoDB였고 두번째 직장에서는 SQLAlchemy를 사용했기 때문에 HikariCP 관련 설정을 직접 확인하고 건드린 것은 이번 직장이 처음이다.
다행히 HikariCP 공식 GitHub에서 옵션에 대한 설명과, 자주 사용되는 옵션들에 대해 친절히 정리를 해준 것들이 있었는데 참고를 해보았다.
자주 사용되는 옵션
회사 프로젝트에 적용했던 옵션, 그리고 HikariCP 공식 문서에서 소개하는 자주 사용되는 옵션들을 정리해보았다.
maximum-pool-size
- HikariCP의 커넥션 풀에서 유지할 수 있는 최대 커넥션 수이며 한 번에 처리할 수 있는 최대 데이터베이스 연결 수를 제한, 기본값은 10
- 너무 높은 값 설정 → 데이터베이스 과부하
- 너무 낮은 값 설정 → 연결 대기 시간이 길어짐
max-lifetime
- 각 데이터베이스 커넥션의 최대 생존 시간(밀리초 단위)이며 기본값은 30분
- 데이터베이스 연결이 이 시간을 초과하면 커넥션 풀에서 해당 연결을 종료하고 새로운 연결을 생성
- 데이터베이스 드라이버가 유지할 수 있는 커넥션의 타임아웃 시간보다 약간 짧게 설정하는 것이 좋다고 한다.
connection-timeout
- 커넥션을 요청했을 때, HikariCP가 커넥션을 반환하기 위해 대기하는 최대 시간(밀리초 단위)이며 기본값은 30초.
- 이 시간이 초과될 경우
SQLTimeoutException발생
minimum-idle
- 풀에서 유지할 최소 유휴 커넥션 수이며 기본값은 maximum-pool-size와 동일하게 설정
- 너무 낮게 설정하면 트래픽 급증 시 커넥션 부족 문제가 발생
idle-timeout
- 유휴 상태의 커넥션이 풀에서 유지되는 최대 시간이며 기본값은 10분
- 이 시간이 지나면 커넥션이 제거되며 0으로 설정 시 유휴 커넥션이 제거되지 않음.
pool-name
- 풀의 이름을 지정하며, 기본값은 자동으로 생성된 이름
- 여러 풀을 사용할 경우 유용.
keepalive-time
- HikariCP가 연결을 활성 상태로 유지하려고 시도하는 빈도를 제어하며 기본값은 2분.
- max-lifetime 값보다 작아야 함
auto-commit
- 기본값은 true이며 각 쿼리 실행 후 자동 커밋
- 명시적 트랜잭션 관리가 필요할 경우 비활성화
data-source-properties
- 데이터 소스의 추가 속성을 설정하며, JDBC 드라이버에 전달될 MySQL 전용 속성 등을 정의
cachePrepStmts- true 시 Prepared Statement 캐싱을 활성화
- 동일한 쿼리가 여러 번 실행될 때, 서버 측에서 SQL 파싱을 생략하고 캐싱된 쿼리를 재사용 (성능 최적화에 유용)
prepStmtCacheSize- 캐싱할 Prepared Statement의 최대 개수이며, 기본값은 25
prepStmtCacheSqlLimit- 캐싱할 SQL 쿼리의 최대 길이를 설정. 이 값을 초과하면 캐싱되지 않음
useServerPrepStmts- 서버 측 Prepared Statement를 사용하도록 설정
- 기본값은 false이며 기본적으로 MySQL에서는 클라이언트가 쿼리를 준비하고 실행
- 이 옵션 활성화 시 쿼리 실행 속도를 개선할 수 있음
기타 옵션
validation-timeout
- 커넥션의 유효성 검사에 허용되는 최대 시간. 기본값은 5초.
leak-detection-threshold
- 커넥션이 풀에서 반환되지 않는 경우(누수), 로그를 출력하는데 사용할 임계값. 기본값은 0으로 비활성화됨. 누수 문제를 디버깅 할 때 유용.
read-only
- 데이터베이스 커넥션을 읽기 전용 모드로 설정
connection-test-query
- 커넥션 풀에 반환되기 전에 커녁센 유효성을 검사하는 쿼리를 지정. MySQL의 경우 SELECT 1 등을 사용. 단, 드라이버가 JDBC4를 지원하는 경우 이 속성을 설정하지 않는 것이 좋다고 함.
metrics-tracker-factory
- 커넥션 풀의 성능을 모니터링할 수 있는 메트릭을 활성화. 보통 Prometheus, JMX와 통합하여 실시간 데이터를 수집.
health-check-properties
- HikariCP에서 커넥션 풀의 상태를 모니터링하기 위한 헬스 체크 관련 속성을 정의.
Reference
Backend Developer