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

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

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

Пример

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

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

Все подмодули, используемые 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/ в форкнутом репозитории, например, фиксацию санитайзера. В этом случае запушьте фикс как ветку с префиксом ClickHouse, например, ClickHouse/fix-sanitizer-disaster. Затем создайте PR из новой ветки к пользовательской отслеживаемой ветке, например, ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster и объедините PR.
• Если вы обновили подмодуль и нужно повторно применить ранние патчи. В этом случае повторное создание старых PR слишком громоздко. Вместо этого просто перенесите старые коммиты в новую ветку ClickHouse/ (соответствующую новой версии). Не стесняйтесь объединять коммиты PR, имеющие несколько коммитов. В лучшем случае мы внесли пользовательские патчи обратно в upstream и можем опустить патчи в новой версии.

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

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