> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse의 서드파티 사용 방식과 서드파티 라이브러리를 추가하고 유지 관리하는 방법을 설명하는 페이지입니다.

# 서드파티 라이브러리

ClickHouse는 다양한 용도로 서드파티 라이브러리를 활용합니다. 예를 들어 다른 데이터베이스에 연결하거나, 디스크에서 데이터를 읽어오거나 디스크에 저장할 때 데이터를 디코딩/인코딩하거나, 특정한 전문 SQL 함수를 구현하는 데 사용합니다.
대상 시스템에서 사용 가능한 라이브러리에 의존하지 않도록, 각 서드파티 라이브러리는 Git 서브모듈 형태로 ClickHouse의 소스 트리에 포함되며, ClickHouse와 함께 컴파일 및 링크됩니다.
서드파티 라이브러리와 해당 라이선스 목록은 다음 쿼리로 확인할 수 있습니다.

```sql theme={null}
SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';
```

나열된 라이브러리는 ClickHouse 리포지토리의 `contrib/` 디렉터리에 있는 라이브러리입니다.
빌드 옵션에 따라 일부 라이브러리는 컴파일되지 않았을 수 있으므로, 해당 기능을 런타임에서 사용할 수 없을 수도 있습니다.

[예시](https://sql.clickhouse.com?query_id=478GCPU7LRTSZJBNY3EJT3)

<div id="adding-and-maintaining-third-party-libraries">
  ## 서드파티 라이브러리 추가 및 유지 관리
</div>

각 서드파티 라이브러리는 ClickHouse 리포지토리의 `contrib/` 디렉터리 아래에 있는 전용 디렉터리에 있어야 합니다.
라이브러리 디렉터리에 외부 코드 사본을 그대로 넣지 마십시오.
대신 외부 업스트림 리포지토리에서 서드파티 코드를 가져오는 Git 서브모듈을 생성하십시오.

ClickHouse에서 사용하는 모든 서브모듈은 `.gitmodule` 파일에 나열되어 있습니다.

* 라이브러리를 그대로 사용할 수 있다면(일반적인 경우), 업스트림 리포지토리를 직접 참조할 수 있습니다.
* 라이브러리에 패치가 필요하다면 [GitHub의 ClickHouse organization](https://github.com/ClickHouse)에 업스트림 리포지토리의 포크를 만드십시오.

후자의 경우, 사용자 지정 패치를 업스트림 커밋과 가능한 한 분리하는 것을 목표로 합니다.
이를 위해 통합하려는 브랜치 또는 태그에서 `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 팀의 유지 관리 부담도 줄일 수 있습니다.