メインコンテンツまでスキップ
メインコンテンツまでスキップ

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

ClickHouseは、他のデータベースへの接続、ディスクからのロード/セーブ時のデータのデコード/エンコード、特定の専門的なSQL関数の実装など、さまざまな目的のためにサードパーティライブラリを利用しています。
ターゲットシステムに利用可能なライブラリに依存しないように、各サードパーティライブラリはClickHouseのソースツリーにGitサブモジュールとしてインポートされ、ClickHouseとともにコンパイルおよびリンクされます。
サードパーティライブラリおよびそのライセンスのリストは、以下のクエリを実行することで取得できます:

リストにあるライブラリは、ClickHouseリポジトリの contrib/ ディレクトリにあるものです。
ビルドオプションによっては、ライブラリがコンパイルされていない場合があり、その結果としてランタイム時にその機能が利用できないことがあります。

サードパーティライブラリの追加と管理

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

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

  • ライブラリがそのまま使用できる場合(デフォルトのケース)、上流リポジトリを直接参照できます。
  • ライブラリにパッチが必要な場合は、ClickHouseのGitHub組織に上流リポジトリのフォークを作成します。

後者の場合、カスタムパッチを上流のコミットから可能な限り隔離することを目指します。
そのため、統合したいブランチやタグから ClickHouse/ プレフィックスを持つブランチを作成します。例えば ClickHouse/2024_2(ブランチ 2024_2 用)や ClickHouse/release/vX.Y.Z(タグ release/vX.Y.Z 用)です。
上流の開発ブランチ master / main / dev を追うことは避けてください(つまり、フォークしたリポジトリでプレフィックスブランチ ClickHouse/master / ClickHouse/main / ClickHouse/dev を使用しないでください)。
そのようなブランチは移動する目的地であり、正しいバージョニングを難しくします。
「プレフィックスブランチ」により、フォーク内での上流リポジトリからのプルがカスタムの ClickHouse/ ブランチに影響を与えないことが保証されます。
contrib/ 内のサブモジュールは、フォークされたサードパーティレポジトリの ClickHouse/ ブランチのみを追跡する必要があります。

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

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

  • フォークされたリポジトリの ClickHouse/ プレフィックスブランチに対して新しい修正を行いたい場合、例えばサニタイザーの修正です。その場合、修正を ClickHouse/ プレフィックスを持つブランチ(例: ClickHouse/fix-sanitizer-disaster)としてプッシュします。次に、その新しいブランチからカスタムトラッキングブランチ(例: ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster)にPRを作成し、PRをマージします。
  • サブモジュールを更新し、以前のパッチを再適用する必要がある場合。この状況では、古いPRを再作成するのは手間がかかります。その代わりに、古いコミットを新しい ClickHouse/ ブランチ(新しいバージョンに対応)にチェリーピックしてください。複数のコミットがあったPRのコミットをまとめることも自由です。最良のケースでは、カスタムパッチを上流に戻し、新しいバージョンではパッチを省略できる状況です。

サブモジュールが更新されたら、ClickHouse内のサブモジュールを新しいハッシュを指すように更新します。

サードパーティライブラリのパッチは、公式リポジトリを考慮して作成し、パッチを上流リポジトリに戻すことを検討してください。
これにより、他の人もパッチの恩恵を受けることができ、ClickHouseチームにとってのメンテナンス負担も軽減されます。