メインコンテンツへスキップ
メインコンテンツへスキップ

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

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

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

以下に列挙しているライブラリは、いずれも ClickHouse リポジトリ内の contrib/ ディレクトリにあるものです。 ビルドオプションによっては、一部のライブラリがコンパイルされず、その結果、実行時にそれらの機能を利用できない場合があります。

例

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

各サードパーティライブラリは、ClickHouse リポジトリの contrib/ ディレクトリ配下に専用ディレクトリを持つ必要があります。 ライブラリ用ディレクトリに外部コードをそのままコピーして放り込むことは避けてください。 代わりに、外部の上流リポジトリからサードパーティコードを取得するための Git サブモジュールを作成してください。

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

  • ライブラリをそのまま（デフォルトのケース）利用できる場合は、上流リポジトリを直接参照できます。
  • ライブラリにパッチ適用が必要な場合は、GitHub の ClickHouse 組織内に上流リポジトリのフォークを作成してください。

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

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

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

  • フォークしたリポジトリ内の ClickHouse/ プレフィックス付きブランチに対して新しい修正を加えたい場合（例: sanitizer の修正）。この場合、修正を ClickHouse/ プレフィックス付きのブランチとして push します（例: ClickHouse/fix-sanitizer-disaster）。その後、新しいブランチからカスタムのトラッキングブランチ（例: ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster）への PR を作成し、PR をマージします。
  • サブモジュールを更新し、以前のパッチを再適用する必要がある場合。このケースでは、古い PR を作り直すのはやり過ぎです。代わりに、古いコミットを新しいバージョンに対応した新しい ClickHouse/ ブランチに単に cherry-pick すれば十分です。複数コミットからなる PR のコミットは、適宜 squash してかまいません。理想的には、カスタムパッチを上流にもコントリビュートしておき、新しいバージョンではそのパッチを省略できるようにします。

サブモジュールを更新したら、フォーク内の新しいハッシュを指すように ClickHouse 内のサブモジュールの参照を更新してください。

サードパーティライブラリ向けのパッチは公式リポジトリを念頭に置いて作成し、可能であればそのパッチを上流リポジトリへコントリビュートすることを検討してください。 そうすることで他のユーザーもそのパッチの恩恵を受けられるようになり、ClickHouse チームの保守負荷を増やさずに済みます。