JDBC 드라이버 로드밸런싱의 이론과 실제동작

About this offer

2026.3.20 에 작성한 글을 옮깁니다. ClickHouse JDBC 드라이버의 로드밸런싱은 기대한 대로 동작하지 않는다 TL;DR load_balancing_policy=roundRobin 을 걸어도 INSERT 는 첫 번째 노드로 쏠렸다. 로드밸런싱은 쿼리 단위가 아니라 커넥션 생성 시점 에만 동작한다. 커넥션 풀이 재사용되는 순간 분산은 멈춘다. failover 는 잘 되지만, 내렸던 노드를 복구해도 원래 노드로 자동 복귀하지 않는다. 앱 재기동이 필요하다. 실시간 균등 분산이 필요하면 HAProxy 같은 프록시 를 두는 게 맞다. 배치성 적재라면 JDBC 멀티호스트로도 충분하다. 1. 테스트 환경 항목 내용 ClickHouse 노드 ch-test-01 (192.168.0.11), ch-test-02 (192.168.0.12) ClickHouse Keeper ch-test-01 (192.168.0.11), ch-test-02 (192.168.0.12), ch-test-03 (192.168.0.13) JDBC 드라이버 com.clickhouse:clickhouse-jdbc:0.6.5 커넥션 풀 HikariCP jdbc:clickhouse://192.168.0.11:8123,192.168.0.12:8123/test_db ?load_balancing_policy=roundRobin &health_check_interval=2000 &failover=1 &check_all_nodes=true 배치 애플리케이션이 두 노드에 INSERT 를 분산하도록 구성한 뒤, 노드를 하나씩 내렸다 올리면서 동작을 관찰했다. 2. 기대한 결과 vs 실제 결과 문서만 보고 예상한 동작과 실제 동작이 꽤 달랐다. 두 정책을 각각 돌려봤다. 2.1 roundRobin 시나리오 기대 결과 실제 결과 앱 기동 시 01, 02 균등 INSERT ❌ 01번에만 INSERT 집중 01번 중지 시 failover 02번으로 자동 failover ✅ 02번으로 전환됨 01번 중지 중 트래픽 01번 시도하다 02번 폴백 01번을 계속 시도하다 02번 폴백 (01번 복구 전까지 에러 로그 계속 발생) 01번 복구 후 다시 01번으로 복귀 ❌ 02번에 계속 INSERT check_all_nodes=true 추가 균등 분산 분산은 되나 균등하지는 않음 2.2 firstAlive 시나리오 기대 결과 실제 결과 앱 기동 시 01번(첫 alive) 우선 사용 ✅ 01번으로 INSERT 01번 중지 시 failover 02번으로 자동 failover ✅ 02번으로 전환됨 01번 중지 중 트래픽 02번으로 100% 이동 01번을 계속 시도하다 02번 폴백 (01번 복구 전까지 에러 로그 계속 발생) 01번 복구 후 다시 01번으로 복귀 ❌ 02번에 계속 INSERT check_all_nodes=true 추가 01번 우선 사용 ✅ 01번 우선 사용 앱 재시작 후 01번으로 복귀 ✅ 01번으로 복귀됨 두 정책 모두 failover 는 되는데 fallback(원복)이 안 된다 는 점이 공통이다. 3. 발견된 이슈 이슈 1 roundRobin 로드밸런싱이 사실상 동작하지 않음 현상 : load_balancing_policy=roundRobin 을 걸었는데도 INSERT 가 항상 첫 번째 노드로 집중된다. 원인 : clickhouse-jdbc 0.6.x 의 client-v2 는 단일 타깃 호스트에만 연결하는 구조 로 설계되어 있어, 클라이언트 사이드 로드밸런싱이 실질적으로 동작하지 않는다. 추가 원인 : HikariCP 커넥션 풀 초기화 시 roundRobin 카운터의 race condition 때문에 대부분의 커넥션이 첫 번째 호스트로 생성된다. 그리고 가장 중요한 부분은 이거다. 커넥션 풀이 한번 만들어지면 → 계속 재사용 → 재사용 중에는 roundRobin 이 동작하지 않음 → 같은 노드로만 감 새 커넥션 생성 시점에만 → 01, 02 번갈아 배정 결론 : roundRobin 은 커넥션 생성 시점 에만 동작한다. 한번 생성된 커넥션은 재사용되므로 쿼리 레벨의 분산은 불가능 하다. 이슈 2 failover 후 원래 노드로 복귀하지 않음 현상 : 01번 노드를 내리면 02번으로 failover 는 정상 동작하는데, 01번을 복구해도 계속 02번으로만 INSERT 된다. 원인 : firstAlive , roundRobin 두 정책 모두 마지막으로 성공한 노드를 유지 하는 방식이라, 복구된 노드로 자동 복귀하지 않는다. 즉 노드 한 대에 잠깐 문제가 생기면, 그 뒤로는 앱을 재기동하기 전까지 트래픽이 한쪽으로 몰린 채 유지된다. 4. 임시 조치와 그 한계 check_all_nodes=true 를 추가하면 양쪽 노드에 INSERT 가 들어가는 것은 확인된다. jdbc:clickhouse://192.168.0.11:8123,192.168.0.12:8123/test_db ?load_balancing_policy=roundRobin &health_check_interval=2000 &failover=1 &check_all_nodes=true 다만 균등 분산까지는 아니다. 커넥션이 언제 생성되느냐에 따라 비율이 달라지는 한계는 그대로 남는다. 5. 정리 — JDBC 드라이버의 구조적 한계 항목 내용 로드밸런싱 단위 쿼리(요청)가 아닌 커넥션 생성 시점 기준 자동 복귀 failover 후 원래 노드로 자동 복귀 불가 (앱 재기동 필요) 균등 분산 커넥션 풀 재사용 구조상 쿼리 레벨 균등 분산 불가 드라이버 방향성 공식 이슈에서도 클라이언트 사이드 로드밸런싱보다 프록시 사용을 권장 이건 설정을 잘못한 문제가 아니라 커넥션 풀 + 클라이언트 사이드 LB 조합의 구조적 특성 에 가깝다. 커넥션을 오래 들고 쓰는 게 풀의 존재 이유인데, 로드밸런싱은 커넥션을 새로 만들 때만 개입하니 둘이 정면으로 어긋난다. 6. 권장 아키텍처 실시간 트래픽을 받는 서비스 Application → HAProxy → ClickHouse ch-test-01 → ClickHouse ch-test-02 HAProxy 가 쿼리 레벨에서 균등 분산과 자동 복귀를 처리한다. 노드 중지/복구와 무관하게 라우팅이 안정적으로 유지된다. 배치 / 조회용 데이터 적재 Batch Application → JDBC (멀티호스트) → ClickHouse ch-test-01 → ClickHouse ch-test-02 실시간 균등 분산이 필수가 아닌 배치성 INSERT/SELECT 라면 JDBC 만으로도 충분하다. failover=1 , check_all_nodes=true 조합으로 단일 노드 중지 시 자동 전환은 보장된다. 7. 테스트 결과에 따른 판단 배치를 통한 조회용 데이터 적재 구조라면, 실시간 균등 분산보다 안정적인 적재 가 우선이므로 JDBC 멀티호스트 구성으로도 문제가 없다는 판단이다. 다만 아래 세 가지는 팀 전체가 인지한 상태로 써야 한다. JDBC 로드밸런싱은 완전한 균등 분산을 보장하지 않는다. failover 후 수동 개입(앱 재시작) 없이는 원래 노드로 복귀하지 않는다. 실시간 트래픽을 받는 구성으로 바꾼다면 HAProxy 도입이 필요하다. 그래서 최종적으로는 분산 흉내를 내는 roundRobin 보다, 동작이 예측 가능한 firstAlive 쪽을 택했다. 어차피 균등 분산이 안 될 거라면 어느 노드를 쓰는지 명확한 편 이 운영하기 낫다는 이유다. jdbc:clickhouse://192.168.0.11:8123,192.168.0.12:8123/test_db ?load_balancing_policy=firstAlive &health_check_interval=5000 &failover=1 &check_all_nodes=true 본 글은 개인 테스트 환경(ClickHouse 2노드 + Keeper 3노드)에서 직접 재현·확인한 내용을 정리한 것입니다.