サードパーティライブラリ

ClickHouse におけるサードパーティライブラリの利用と、その追加および保守方法を説明するページ。

ClickHouse は、さまざまな目的でサードパーティライブラリを利用しています。たとえば、他のデータベースへの接続、ディスクへの読み書き時のデータのデコード／エンコード、あるいは特定の特殊な SQL 関数の実装などです。 対象システム上で利用可能なライブラリに依存しないよう、各サードパーティライブラリは Git サブモジュールとして ClickHouse のソースツリーに取り込まれ、ClickHouse とともにコンパイルおよびリンクされます。 サードパーティライブラリとそのライセンスの一覧は、次のクエリで取得できます。

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

記載されているライブラリは、ClickHouse リポジトリの contrib/ ディレクトリに配置されているものです。 build options によっては、一部のライブラリがコンパイルされていないため、それらの機能を runtime で利用できない場合があります。

例

​

サードパーティライブラリの追加と保守

各サードパーティライブラリは、ClickHouse リポジトリの contrib/ ディレクトリ配下にある専用ディレクトリに配置する必要があります。 外部コードのコピーをライブラリディレクトリにそのまま置くのは避けてください。 代わりに、外部のアップストリームリポジトリからサードパーティコードを取得する Git サブモジュール を作成してください。

ClickHouse で使用されるすべての サブモジュール は、.gitmodule ファイルに一覧化されています。

• ライブラリをそのまま利用できる場合 (通常はこれです) は、アップストリームリポジトリを直接参照できます。
• ライブラリにパッチの適用が必要な場合は、GitHub 上の ClickHouse organization にアップストリームリポジトリの fork を作成してください。

後者の場合、カスタムパッチはできるだけアップストリームのコミットから分離することを目指します。 そのため、取り込みたいブランチまたはタグから、ClickHouse/ プレフィックス付きのブランチを作成してください。たとえば ClickHouse/2024_2 (ブランチ 2024_2 の場合) や ClickHouse/release/vX.Y.Z (タグ release/vX.Y.Z の場合) です。 アップストリームの開発ブランチ master / main / dev を追従するのは避けてください (つまり、fork リポジトリで ClickHouse/master / ClickHouse/main / ClickHouse/dev のようなプレフィックス付きブランチは作成しないでください) 。 このようなブランチは常に変化するため、適切なバージョニングが難しくなります。 「プレフィックス付きブランチ」にしておけば、アップストリームリポジトリから fork に pull しても、カスタムの ClickHouse/ ブランチには影響しません。 contrib/ 内の サブモジュール は、fork されたサードパーティリポジトリの ClickHouse/ ブランチのみを追跡しなければなりません。

パッチは、外部ライブラリの ClickHouse/ ブランチに対してのみ適用します。

これを行う方法は 2 つあります。

• fork したリポジトリ内の ClickHouse/ プレフィックス付きブランチに対して、新しい修正 (たとえば sanitizer の修正) を加えたい場合です。この場合、修正を ClickHouse/ プレフィックス付きのブランチ、たとえば ClickHouse/fix-sanitizer-disaster として push してください。続いて、新しいブランチからカスタム追跡ブランチに向けて PR を作成します。たとえば ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster のようにし、その PR をマージします。
• サブモジュール を更新し、以前のパッチを再適用する必要がある場合です。この場合、古い PR を作り直すのは大げさです。代わりに、古いコミットを新しい ClickHouse/ ブランチ (新しいバージョンに対応するもの) にそのまま cherry-pick してください。複数のコミットを含む PR であれば、コミットを squash して構いません。理想的には、カスタムパッチをすでに upstream に還元できていれば、新しいバージョンではパッチを省略できます。

サブモジュール を更新したら、ClickHouse 側の サブモジュール も更新して、fork 内の新しい hash を指すようにしてください。

サードパーティライブラリのパッチは、公式リポジトリに取り込まれることを意識して作成し、アップストリームリポジトリへの還元も検討してください。 そうすることで、他の人もそのパッチの恩恵を受けられ、ClickHouse チームの保守負担も軽減できます。