Сторонние библиотеки

Страница с описанием использования сторонних компонентов в ClickHouse и того, как добавлять и сопровождать сторонние библиотеки.

ClickHouse использует сторонние библиотеки для различных целей, например для подключения к другим базам данных, декодирования/кодирования данных при загрузке с диска и сохранении на диск, а также для реализации некоторых специализированных SQL-функций. Чтобы не зависеть от библиотек, доступных в целевой системе, каждая сторонняя библиотека импортируется в дерево исходного кода ClickHouse как Git-подмодуль, а затем компилируется и линкуется вместе с ClickHouse. Список сторонних библиотек и их лицензий можно получить с помощью следующего запроса:

SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';

Обратите внимание, что перечисленные библиотеки находятся в каталоге contrib/ репозитория ClickHouse. В зависимости от параметров сборки некоторые из этих библиотек могли не скомпилироваться, и в результате их функциональность может быть недоступна при выполнении.

Пример

​

Добавление и сопровождение сторонних библиотек

Каждая сторонняя библиотека должна находиться в отдельном каталоге внутри каталога contrib/ репозитория ClickHouse. Не стоит просто складывать копии внешнего кода в каталог библиотеки. Вместо этого создайте Git-подмодуль, чтобы подтягивать сторонний код из внешнего upstream-репозитория.

Все submodule, используемые в ClickHouse, перечислены в файле .gitmodule.

• Если библиотеку можно использовать как есть (это вариант по умолчанию), можно напрямую ссылаться на upstream-репозиторий.
• Если библиотека требует патчей, создайте fork upstream-репозитория в организации ClickHouse на GitHub.

Во втором случае мы стремимся максимально изолировать собственные патчи от коммитов upstream-репозитория. Для этого создайте branch с prefix ClickHouse/ от branch или tag, который вы хотите интегрировать, например ClickHouse/2024_2 (для branch 2024_2) или ClickHouse/release/vX.Y.Z (для tag release/vX.Y.Z). Не используйте ветки разработки upstream-репозитория master/ main / dev (то есть ветки с префиксом ClickHouse/master / ClickHouse/main / ClickHouse/dev в fork-репозитории). Такие ветки постоянно меняются, что затрудняет корректное управление версиями. «Ветки с префиксом» гарантируют, что pulls из upstream-репозитория в fork не затронут собственные ветки ClickHouse/. Submodule в contrib/ должны отслеживать только ветки ClickHouse/ в fork-репозиториях сторонних библиотек.

Патчи применяются только к веткам ClickHouse/ внешних библиотек.

Это можно сделать двумя способами:

• если вы хотите внести новое исправление в ветку с префиксом ClickHouse/ в fork-репозитории, например исправление для sanitizer, отправьте его как branch с prefix ClickHouse/, например ClickHouse/fix-sanitizer-disaster. Затем создайте PR из новой ветки в пользовательскую ветку отслеживания, например ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster, и выполните merge PR.
• если вы обновляете submodule и вам нужно повторно применить более ранние патчи, заново создавать старые PR будет излишне. Вместо этого просто выполните cherry-pick старых коммитов в новую ветку ClickHouse/ (соответствующую новой версии). При необходимости можно сделать squash коммитов из PR, где было несколько коммитов. В идеале мы уже отправили собственные патчи обратно в upstream и можем не переносить их в новую версию.

После обновления submodule обновите ссылку на submodule в ClickHouse так, чтобы она указывала на новый hash в fork.

Создавайте патчи для сторонних библиотек с прицелом на официальный репозиторий и по возможности отправляйте их обратно в upstream-репозиторий. Это позволит и другим воспользоваться патчем и снизит нагрузку на сопровождение для команды ClickHouse.