Перейти к основному содержанию
Перейти к основному содержанию

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

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

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

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

Пример

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

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

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

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

Во втором случае мы стремимся максимально изолировать собственные патчи от upstream‑коммитов. Для этого создайте ветку с префиксом ClickHouse/ от ветки или тега, который вы хотите интегрировать, например ClickHouse/2024_2 (для ветки 2024_2) или ClickHouse/release/vX.Y.Z (для тега release/vX.Y.Z). Избегайте слежения за upstream‑ветками разработки master / main / dev (то есть создания веток с префиксом ClickHouse/master / ClickHouse/main / ClickHouse/dev в форке). Такие ветки являются «движущимися целями» и осложняют корректное версионирование. «Префиксные ветки» гарантируют, что подтягивание изменений из upstream‑репозитория во форк не затронет пользовательские ветки ClickHouse/. Подмодули в contrib/ должны отслеживать только ветки ClickHouse/ форкнутых сторонних репозиториев.

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

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

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

После обновления подмодуля обновите ссылку на подмодуль в ClickHouse так, чтобы она указывала на новый хеш во форке.

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