메인 콘텐츠로 건너뛰기
ClickHouse는 다양한 용도로 서드파티 라이브러리를 활용합니다. 예를 들어 다른 데이터베이스에 연결하거나, 디스크에서 데이터를 읽어오거나 디스크에 저장할 때 데이터를 디코딩/인코딩하거나, 특정한 전문 SQL 함수를 구현하는 데 사용합니다. 대상 시스템에서 사용 가능한 라이브러리에 의존하지 않도록, 각 서드파티 라이브러리는 Git 서브모듈 형태로 ClickHouse의 소스 트리에 포함되며, ClickHouse와 함께 컴파일 및 링크됩니다. 서드파티 라이브러리와 해당 라이선스 목록은 다음 쿼리로 확인할 수 있습니다. 
SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';
나열된 라이브러리는 ClickHouse 리포지토리의 contrib/ 디렉터리에 있는 라이브러리입니다. 빌드 옵션에 따라 일부 라이브러리는 컴파일되지 않았을 수 있으므로, 해당 기능을 런타임에서 사용할 수 없을 수도 있습니다. 예시

​
서드파티 라이브러리 추가 및 유지 관리

각 서드파티 라이브러리는 ClickHouse 리포지토리의 contrib/ 디렉터리 아래에 있는 전용 디렉터리에 있어야 합니다. 라이브러리 디렉터리에 외부 코드 사본을 그대로 넣지 마십시오. 대신 외부 업스트림 리포지토리에서 서드파티 코드를 가져오는 Git 서브모듈을 생성하십시오. ClickHouse에서 사용하는 모든 서브모듈은 .gitmodule 파일에 나열되어 있습니다.
  • 라이브러리를 그대로 사용할 수 있다면(일반적인 경우), 업스트림 리포지토리를 직접 참조할 수 있습니다.
  • 라이브러리에 패치가 필요하다면 GitHub의 ClickHouse organization에 업스트림 리포지토리의 포크를 만드십시오.
후자의 경우, 사용자 지정 패치를 업스트림 커밋과 가능한 한 분리하는 것을 목표로 합니다. 이를 위해 통합하려는 브랜치 또는 태그에서 ClickHouse/ 접두어를 가진 브랜치를 만드십시오. 예를 들어 ClickHouse/2024_2(브랜치 2024_2의 경우) 또는 ClickHouse/release/vX.Y.Z(태그 release/vX.Y.Z의 경우)입니다. 업스트림 개발 브랜치인 master/ main / dev를 그대로 따라가지 마십시오(즉, 포크 리포지토리에서 ClickHouse/master / ClickHouse/main / ClickHouse/dev 같은 접두어 브랜치를 만들지 마십시오). 이러한 브랜치는 계속 변경되므로 올바른 버전 관리를 더 어렵게 만듭니다. “접두어 브랜치”를 사용하면 업스트림 리포지토리에서 포크로 pull하더라도 사용자 지정 ClickHouse/ 브랜치는 영향을 받지 않습니다. contrib/의 서브모듈은 포크된 서드파티 리포지토리의 ClickHouse/ 브랜치만 추적해야 합니다. 패치는 외부 라이브러리의 ClickHouse/ 브랜치에만 적용해야 합니다. 이를 수행하는 방법은 두 가지입니다.
  • 포크된 리포지토리의 ClickHouse/ 접두어 브랜치에 새 수정 사항을 추가하려는 경우입니다. 예를 들어 sanitizer 수정이 이에 해당합니다. 이 경우 수정 사항을 ClickHouse/ 접두어가 붙은 브랜치(예: ClickHouse/fix-sanitizer-disaster)로 push하십시오. 그런 다음 새 브랜치에서 사용자 지정 추적 브랜치로 PR을 생성하십시오. 예: ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster. 이후 PR을 머지하십시오.
  • 서브모듈을 업데이트하면서 이전 패치를 다시 적용해야 하는 경우입니다. 이 경우 예전 PR을 다시 만드는 것은 과도합니다. 대신 이전 커밋을 새 ClickHouse/ 브랜치(새 버전에 해당)에 체리픽하면 됩니다. 여러 커밋으로 이루어진 PR이라면 커밋을 자유롭게 squash해도 됩니다. 가장 이상적인 경우는 사용자 지정 패치를 이미 업스트림에 기여해 두어, 새 버전에서는 해당 패치를 생략할 수 있는 경우입니다.
서브모듈 업데이트가 완료되면 ClickHouse에서 서브모듈을 갱신하여 포크의 새 hash를 가리키도록 하십시오. 서드파티 라이브러리용 패치는 공식 리포지토리를 염두에 두고 작성하고, 해당 패치를 업스트림 리포지토리에 다시 기여하는 것도 고려하십시오. 이렇게 하면 다른 사용자도 패치의 혜택을 받을 수 있고, ClickHouse 팀의 유지 관리 부담도 줄일 수 있습니다.
마지막 수정일 2026년 6월 10일