Spring Boot HikariCP 커넥션 풀 설정 실무 가이드

maximum-pool-size, connection-timeout, max-lifetime을 제대로 이해하자

Spring Boot에서 DB 연결은 대부분 HikariCP를 사용합니다.
HikariCP는 JVM 기반 애플리케이션에서 가장 빠른 커넥션 풀로 알려져 있으며 Spring Boot 기본 설정입니다.

하지만 기본 설정을 그대로 사용하면 트래픽 상황이나 DB 환경에 따라 장애가 발생할 수 있습니다.

이번 글에서는 아래 설정을 기준으로 실무에서 어떤 의미를 가지는지 사례 중심으로 설명합니다.

 

spring:
datasource:
hikari:
maximum-pool-size: 10
connection-timeout: 30000
max-lifetime: 1800000

 

 

---

1. HikariCP란 무엇인가

HikariCP는 DB 커넥션을 미리 생성해두고 재사용하는 커넥션 풀(Connection Pool) 입니다.

애플리케이션이 요청을 받을 때마다 DB 연결을 생성하면 성능이 크게 떨어집니다.

그래서 보통 구조는 다음과 같습니다.

Client Request
↓
Spring Application
↓
Hikari Connection Pool
↓
Database

 

커넥션 풀은 DB 연결을 미리 만들어 두고 필요할 때 빌려주는 역할을 합니다.

---

2. maximum-pool-size

(최대 커넥션 개수)

 

maximum-pool-size: 10

 

이 설정은 애플리케이션이 동시에 사용할 수 있는 DB 커넥션의 최대 개수입니다.

예를 들어

maximum-pool-size = 10

 

이라면

동시에 10개의 DB 쿼리만 실행 가능

 

합니다.

---

사례 1: 트래픽이 낮은 서비스

예

• 내부 시스템
• 관리자 페이지
• 연구 시스템
• PoC 프로젝트

maximum-pool-size = 10

 

정도면 충분합니다.

---

사례 2: 트래픽 많은 API 서버

예

TPS 500 ~ 1000

 

이 경우

maximum-pool-size = 30 ~ 50

 

정도로 늘려야 합니다.

하지만 무조건 늘리는 것은 위험합니다.

왜냐하면 DB에도 max connection 제한이 있기 때문입니다.

예

PostgreSQL default
max_connections = 100

 

애플리케이션 서버가 4대라면

100 / 4 = 25

 

따라서

maximum-pool-size = 20

 

정도로 설정하는 것이 안전합니다.

---

3. connection-timeout

(커넥션을 기다리는 최대 시간)

 

connection-timeout: 30000

 

의미

DB 커넥션을 얻기 위해 최대 30초 기다림

 

만약 커넥션 풀이 꽉 차 있으면

Thread
↓
Connection pool 대기

 

이 상태가 됩니다.

30초 안에 커넥션을 못 얻으면

SQLTransientConnectionException

 

이 발생합니다.

---

사례 1: 커넥션 풀 부족

예

maximum-pool-size = 10

 

동시에

20개 요청 발생

 

구조

10개 → 실행
10개 → 대기

 

이때

connection-timeout = 5초

 

이면

5초 후 요청이 실패합니다.

---

사례 2: 너무 크게 잡으면 위험

connection-timeout = 5분

 

이렇게 잡으면

Thread가 계속 대기

 

합니다.

그러면

Tomcat Thread Pool 고갈

 

이 발생할 수 있습니다.

그래서 보통

30초 ~ 60초

 

정도가 적당합니다.

---

4. max-lifetime

(커넥션 최대 수명)

 

max-lifetime: 1800000

 

의미

커넥션을 30분 후 폐기

 

합니다.

왜냐하면 DB나 네트워크에서 유휴 커넥션을 끊는 경우가 있기 때문입니다.

---

사례 1: AWS RDS

AWS RDS는

idle connection timeout

 

이 존재합니다.

그래서 커넥션을 오래 유지하면

Broken pipe
Connection reset

 

같은 에러가 발생합니다.

---

사례 2: NAT / Firewall 환경

회사 내부망에서는

NAT timeout
Firewall idle timeout

 

이 존재합니다.

이때 오래된 커넥션이 끊어집니다.

그래서 HikariCP는 일정 시간 후 커넥션을 새로 생성합니다.

---

5. 실무에서 가장 흔한 장애

커넥션 풀 고갈

로그

HikariPool - Connection is not available

 

원인

1️⃣ DB 쿼리 느림
2️⃣ 트랜잭션 오래 유지
3️⃣ 커넥션 풀 부족

이때 해결 방법

maximum-pool-size 증가
쿼리 최적화
트랜잭션 범위 축소

 

---

6. 실무 추천 설정

보통 Spring Boot에서는 이렇게 시작합니다.

maximum-pool-size = CPU * 2 + disk

 

예

CPU = 4

 

pool = 10 ~ 15

 

추천 기본값

 

spring:
datasource:
hikari:
maximum-pool-size: 15
minimum-idle: 5
connection-timeout: 30000
max-lifetime: 1800000

 

---

7. 정리

HikariCP 설정은 단순한 옵션처럼 보이지만 DB 성능과 안정성에 직접적인 영향을 줍니다.

핵심 포인트는 다음입니다.

• maximum-pool-size
  → 동시 DB 작업 개수
• connection-timeout
  → 커넥션 대기 시간
• max-lifetime
  → 커넥션 재생성 주기

이 세 가지를 DB max connection, 트래픽, 서버 수와 함께 고려해야 합니다.

---

✔ 한 줄 정리

HikariCP 튜닝은 애플리케이션 성능이 아니라
DB 안정성을 위한 설정이다.