JDBC を使用して ClickHouse を外部データソースに接続する

clickhouse-jdbc-bridge には Experimental なコードが含まれており、現在はサポートされていません。信頼性やセキュリティ上の脆弱性が含まれている可能性があります。使用は自己責任でお願いします。

JDBC を使用するには ClickHouse JDBC Bridge が必要です。そのため、ローカルマシン上で clickhouse-local を使用して、データベースから ClickHouse Cloud へデータをストリーミングする必要があります。詳細については、ドキュメントの Migrate セクションにある Using clickhouse-local ページを参照してください。

概要: ClickHouse JDBC Bridge を jdbc テーブル関数または JDBC テーブルエンジンと組み合わせることで、JDBCドライバーが利用可能な任意の外部データソースに ClickHouse からアクセスできます。また、ネイティブな組み込みの integration engine が存在しないデータソースでも利用可能です: これは、対象の外部データソース向けのネイティブな組み込み integration engine、table function、または外部 Dictionary は利用できない一方で、そのデータソース向けの JDBCドライバーは存在する場合に便利です。 ClickHouse JDBC Bridge は、読み取りと書き込みの両方に使用できます。また、複数の外部データソースに対して並行して使用することも可能です。たとえば、複数の外部および内部データソースにまたがる分散クエリを ClickHouse 上でリアルタイムに実行できます。このレッスンでは、ClickHouse JDBC Bridge のインストール、設定、実行を行い、ClickHouse を外部データソースに接続する方法を紹介します。このレッスンでは、外部データソースとして MySQL を使用します。それでは始めましょう!

前提条件以下を満たすマシンにアクセスできること:

Unix シェルとインターネット接続を利用できる
wget がインストールされている
現行バージョンの Java (例: OpenJDK バージョン >= 17) がインストールされている
現行バージョンの MySQL (例: MySQL バージョン >=8) がインストールされ、実行中である
現行バージョンの ClickHouse がインストールされていて、実行中である

ClickHouse JDBC Bridge をローカルにインストールする

ClickHouse JDBC Bridge を利用する最も簡単な方法は、ClickHouse が動作しているのと同じホストにインストールして実行することです。まず、ClickHouse が動作しているマシンの Unix シェルに接続し、あとで ClickHouse JDBC Bridge をインストールするためのローカルフォルダーを作成します (フォルダー名や配置場所は任意です) :

mkdir ~/clickhouse-jdbc-bridge

次に、そのフォルダに ClickHouse JDBC Bridge の最新バージョンをダウンロードします。

cd ~/clickhouse-jdbc-bridge
wget https://github.com/ClickHouse/clickhouse-jdbc-bridge/releases/download/v2.0.7/clickhouse-jdbc-bridge-2.0.7-shaded.jar

MySQL に接続できるよう、名前付きデータソースを作成します。

 cd ~/clickhouse-jdbc-bridge
 mkdir -p config/datasources
 touch config/datasources/mysql8.json

以下の設定を ~/clickhouse-jdbc-bridge/config/datasources/mysql8.json ファイルにコピーして貼り付けます。

 {
   "mysql8": {
   "driverUrls": [
     "https://repo1.maven.org/maven2/mysql/mysql-connector-java/8.0.28/mysql-connector-java-8.0.28.jar"
   ],
   "jdbcUrl": "jdbc:mysql://<host>:<port>",
   "username": "<username>",
   "password": "<password>"
   }
 }

上記の設定ファイルについて

データソース名は自由に設定できます。ここでは mysql8 を使用しています
jdbcUrl の値では、実行中の MySQL インスタンスに合わせて <host> と <port> を適切な値に置き換える必要があります。例: "jdbc:mysql://localhost:3306"
<username> と <password> は MySQL の認証情報に置き換える必要があります。パスワードを使用しない場合は、上記の設定ファイルから "password": "<password>" の行を削除できます
driverUrls の値には、MySQL JDBCドライバーの現行バージョンをダウンロードできる URL を指定しているだけです。これだけで十分で、ClickHouse JDBC Bridge がその JDBCドライバーを自動的にダウンロードします (OS 固有のディレクトリに保存されます) 。

これで ClickHouse JDBC Bridge を起動する準備が整いました。

 cd ~/clickhouse-jdbc-bridge
 java -jar clickhouse-jdbc-bridge-2.0.7-shaded.jar

ClickHouse JDBC Bridge はフォアグラウンドモードで起動しました。Bridge を停止するには、先ほどの Unix シェルのウィンドウを前面に戻して CTRL+C を押します。

ClickHouse 内から JDBC 接続を使用する

ClickHouse では、jdbc テーブル関数または JDBC テーブルエンジンを使用して MySQL のデータにアクセスできます。以下の例を実行する最も簡単な方法は、clickhouse-client または Play UI にコピー＆ペーストすることです。

jdbc テーブル関数:

 SELECT * FROM jdbc('mysql8', 'mydatabase', 'mytable');

最初のパラメーターには、上で設定した名前付きデータソースの名前を jdbc テーブル関数に指定しています。

JDBC テーブルエンジン:

 CREATE TABLE mytable (
      <column> <column_type>,
      ...
 )
 ENGINE = JDBC('mysql8', 'mydatabase', 'mytable');

 SELECT * FROM mytable;

JDBC engine句の最初のパラメータとして、上で設定した名前付きデータソースの名前を使用していますClickHouse JDBC engineテーブルのスキーマと接続先のMySQLテーブルのスキーマは揃っている必要があります。たとえば、カラム名とその順序は同一である必要があり、カラムのデータ型には互換性が必要です

ClickHouse JDBC Bridge を外部にインストールする

分散 ClickHouse クラスター (ClickHouse ホストが複数あるクラスター) では、ClickHouse JDBC Bridge を専用ホストに外部インストールして実行するのが適切です。この構成には、各 ClickHouse ホストから JDBC Bridge にアクセスできるという利点があります。そうでない場合、Bridge 経由で外部データソースにアクセスする ClickHouse インスタンスごとに、JDBC Bridge をローカルにインストールする必要があります。 ClickHouse JDBC Bridge を外部にインストールするには、次の手順を実行します。

このガイドのセクション 1 に記載された手順に従って、専用ホストに ClickHouse JDBC Bridge をインストールし、設定して実行します。
各 ClickHouse ホストで、ClickHouse サーバー設定に次の設定ブロックを追加します (使用する設定フォーマットに応じて、XML 版または YAML 版を使用してください)。

XML
YAML

<jdbc_bridge>
   <host>JDBC-Bridge-Host</host>
   <port>9019</port>
</jdbc_bridge>

jdbc_bridge:
    host: JDBC-Bridge-Host
    port: 9019

JDBC-Bridge-Host は、専用の ClickHouse JDBC Bridge ホストのホスト名または IP アドレスに置き換える必要があります
ここでは ClickHouse JDBC Bridge のデフォルトポート 9019 を指定しています。JDBC Bridge で別のポートを使用している場合は、上記の設定もそれに応じて変更してください

​ClickHouse JDBC Bridge をローカルにインストールする

​ClickHouse 内から JDBC 接続を使用する

​ClickHouse JDBC Bridge を外部にインストールする

ClickHouse JDBC Bridge をローカルにインストールする

ClickHouse 内から JDBC 接続を使用する

ClickHouse JDBC Bridge を外部にインストールする