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

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

注記

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

概要: ClickHouse JDBC Bridge を jdbc テーブル関数 または JDBC テーブルエンジン と組み合わせて使用することで、JDBC ドライバー が提供されている任意の外部データソース上のデータに ClickHouse からアクセスできるようになります。

ClickHouse JDBC Bridge のアーキテクチャ図

これは、対象の外部データソース向けのネイティブな組み込み integration engine、テーブル関数、または外部ディクショナリが存在しない場合でも、そのデータソース用の JDBC ドライバーがあれば利用できるため便利です。

ClickHouse JDBC Bridge は、読み取りと書き込みの両方に使用できます。また、複数の外部データソースに対して並行して利用でき、例えば、複数の外部および内部データソースにまたがる分散クエリを ClickHouse 上でリアルタイムに実行できます。

このレッスンでは、ClickHouse を外部データソースに接続するために ClickHouse JDBC Bridge をインストール、設定、実行する手順がいかに簡単かを説明します。このレッスンでは、外部データソースとして MySQL を使用します。

それでは始めましょう。

前提条件

次の要件を満たすマシンにアクセスできること:

  1. Unix シェルとインターネット接続がある
  2. wget がインストールされている
  3. 最新バージョンの Java（例: OpenJDK バージョン >= 17）がインストールされている
  4. 最新バージョンの MySQL（例: MySQL バージョン >= 8）がインストールされ、稼働している
  5. 最新バージョンの ClickHouse が インストール され、稼働している

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

ClickHouse JDBC Bridge を使用する最も簡単な方法は、ClickHouse が動作しているのと同じホスト上にインストールして実行することです。

ClickHouse JDBC Bridge をローカルにデプロイした構成図

まず、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": "<ユーザー名>",
  "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 エンジン句の最初のパラメータには、上で設定した名前付きデータソースの名前を指定しています。

ClickHouse JDBC エンジンテーブルのスキーマと、接続されている MySQL テーブルのスキーマは一致している必要があります。例えば、カラム名とその順序は同一でなければならず、カラムのデータ型も互換性がある必要があります。

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

分散 ClickHouse クラスター（複数の ClickHouse ホストを持つクラスター）の場合、ClickHouse JDBC Bridge を専用ホスト上にインストールして外部で実行するのが有効です。

ClickHouse JDBC Bridge 外部デプロイメントの構成図

この構成の利点は、各 ClickHouse ホストから JDBC Bridge にアクセスできる点にあります。そうでない場合は、Bridge 経由で外部データソースにアクセスする必要がある各 ClickHouse インスタンスごとに JDBC Bridge をローカルにインストールする必要があります。

ClickHouse JDBC Bridge を外部にインストールするには、次の手順を実行します。

  1. このガイドのセクション 1 で説明している手順に従って、専用ホスト上に ClickHouse JDBC Bridge をインストール、設定、および実行します。

  2. 各 ClickHouse ホストで、ClickHouse サーバーの設定 に次の設定ブロックを追加します（選択した設定形式に応じて XML 版または YAML 版のいずれかを使用してください）。

<jdbc_bridge>
   <host>JDBC-Bridge-Host</host>
   <port>9019</port>
</jdbc_bridge>
注記
  • JDBC-Bridge-Host は、専用の ClickHouse JDBC Bridge ホストのホスト名または IP アドレスに置き換えてください
  • ここでは ClickHouse JDBC Bridge のデフォルトポート 9019 を指定しています。JDBC Bridge に別のポートを使用している場合は、それに応じて上記の設定を調整してください