왜 멀티버전 환경이 필요한가?

ClickHouse는 활발하게 개발되는 오픈소스 프로젝트로, 매 릴리스마다 의미 있는 성능 개선과 새로운 기능이 추가됩니다. 특히 쿼리 최적화나 실행 엔진의 개선은 버전마다 극적인 차이를 보일 수 있습니다.

대표적인 예로 Join Reordering 최적화를 들 수 있습니다. 이 기능은 24.10, 25.6, 25.10 버전에서 각각 다른 수준의 최적화를 제공하며, 실제 워크로드에서 쿼리 성능이 수배에서 수십 배까지 차이날 수 있습니다. 이러한 개선 사항을 직접 확인하고 비교하기 위해서는 여러 버전을 동시에 실행할 수 있는 환경이 필수적입니다.

프로젝트 소개

clickhouse-hols/oss-mac-setup은 Docker를 활용하여 여러 버전의 ClickHouse를 동시에 실행할 수 있는 macOS 전용 환경 구축 도구입니다.

주요 특징

• 멀티버전 동시 실행: 원하는 ClickHouse 버전을 여러 개 동시에 실행
• 포트 자동 매핑: 각 버전마다 고유한 HTTP/TCP 포트 자동 할당
• 데이터 영속성: Named Volume을 통한 데이터 보존
• macOS 최적화: Seccomp 프로파일 적용으로 NUMA syscall 에러 해결
• 간편한 관리: 시작/종료/상태확인/클라이언트 연결을 위한 스크립트 제공

실제 사용법

1. 환경 설정

원하는 버전을 지정하여 환경을 구성합니다:

./set.sh 24.9 25.10

이 명령은 다음 작업을 자동으로 수행합니다:

• Docker Compose 설정 파일 생성
• 버전별 포트 매핑 설정 (24.9 → HTTP:2409/TCP:24091, 25.10 → HTTP:2510/TCP:25101)
• Seccomp 보안 프로파일 구성
• 관리 스크립트 생성
• ClickHouse 이미지 다운로드

2. ClickHouse 시작

bash

3. 클라이언트 연결

특정 버전에 CLI로 접속하려면:

./client.sh 2409  # 24.9 버전 접속
./client.sh 2510  # 25.10 버전 접속

clickhouse-24-9 :) SELECT version();
   ┌─version()──┐
1. │ 24.9.3.128 │
   └────────────┘

clickhouse-25-10 :) SELECT version();
   ┌─version()──┐
1. │ 25.10.2.65 │
   └────────────┘

4. 상태 확인 및 종료

bash

./status.sh              # 모든 버전의 상태 및 리소스 사용량 확인
./stop.sh                # 모든 버전 종료 (데이터 보존)
./stop.sh --cleanup      # 모든 버전 종료 및 데이터 삭제

활용 시나리오

성능 비교 테스트

동일한 쿼리를 여러 버전에서 실행하여 성능 개선을 정량적으로 측정:

- 24.9 버전 (localhost:2409)
SELECT ... FROM large_table t1 JOIN table2 t2 JOIN table3 t3 ...;
- 25.10 버전 (localhost:2510) 
SELECT ... FROM large_table t1 JOIN table2 t2 JOIN table3 t3 ...;

기능 검증

새 버전의 기능을 기존 버전과 비교하여 호환성 및 동작 차이 확인

마이그레이션 준비

프로덕션 업그레이드 전에 실제 워크로드를 여러 버전에서 테스트하여 리스크 평가

기술적 구현

이 도구는 Docker Compose를 활용하여 각 ClickHouse 버전을 독립적인 컨테이너로 실행합니다.

주요 구성 요소:

• 네트워크 격리: 각 버전은 독립적인 포트를 사용하지만 동일한 Docker 네트워크를 공유
• 볼륨 관리: 버전별로 별도의 Named Volume을 사용하여 데이터 충돌 방지
• Seccomp 프로파일: macOS 환경에서 발생하는 NUMA 관련 syscall 에러를 해결

결론

ClickHouse의 빠른 발전 속도를 따라가고 최신 최적화의 이점을 활용하기 위해서는 버전 간 비교가 필수적입니다. 이 도구를 통해 개발자와 엔지니어는 로컬 환경에서 손쉽게 멀티버전 테스트를 수행하고, 데이터 기반의 업그레이드 결정을 내릴 수 있습니다.

clickhouse-hols/local/oss-mac-setup at main · litkhai/clickhouse-hols

ClickHouse Hands-on Labs . Contribute to litkhai/clickhouse-hols development by creating an account on GitHub.

github.com