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

ClickHouseをJDBCで外部データソースに接続する

注記

JDBCを使用するにはClickHouse JDBCブリッジが必要ですので、ローカルマシンでclickhouse-localを使用してデータベースからClickHouse Cloudにデータをストリーミングする必要があります。詳細については、MigrateセクションのUsing clickhouse-localページを訪問してください。

概要: ClickHouse JDBC Bridgeは、jdbcテーブル関数やJDBCテーブルエンジンと組み合わせることで、任意の外部データソースからデータにアクセスできるようにします。この外部データソースにはJDBCドライバーが必要です：

ClickHouse JDBC Bridge architecture diagram

これは、外部データソース用のネイティブ組み込みインテグレーションエンジン、テーブル関数、または外部辞書が利用できない場合に便利ですが、データソース用の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ブリッジをローカルにインストールする​

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

ClickHouse JDBC Bridge locally deployment diagram

まず、ClickHouseが実行されているマシンのUnixシェルに接続し、後でClickHouse JDBCブリッジをインストールするためのローカルフォルダーを作成します（フォルダーの名前や場所は自由に決めてください）：

mkdir ~/clickhouse-jdbc-bridge

次に、そのフォルダーに現在のバージョンのClickHouse JDBCブリッジをダウンロードします：

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ブリッジを起動する準備が整いました：

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

私たちはフォアグラウンドモードでClickHouse JDBCブリッジを起動しました。ブリッジを停止するには、上記の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ブリッジを外部にインストールする​

分散ClickHouseクラスター（複数のClickHouseホストを持つクラスター）の場合、ClickHouse JDBCブリッジを専用ホスト上に外部でインストールして実行することが理にかなっています：

ClickHouse JDBC Bridge external deployment diagram

これにより、各ClickHouseホストがJDBCブリッジにアクセスできる利点があります。そうしないと、外部データソースにアクセスするために、各ClickHouseインスタンスごとにJDBCブリッジをローカルにインストールする必要があります。

ClickHouse JDBCブリッジを外部にインストールするために、次の手順を実行します：

  1. このガイドのセクション1の手順に従って、専用ホストにClickHouse JDBCブリッジをインストール、設定、実行します。

  2. 各ClickHouseホストに、ClickHouseサーバー設定への次の構成ブロックを追加します（選択した設定フォーマットに応じて、XMLまたはYAMLバージョンを使用してください）：

<jdbc_bridge>
   <host>JDBC-Bridge-Host</host>
   <port>9019</port>
</jdbc_bridge>
注記
  • JDBC-Bridge-Hostを専用のClickHouse JDBCブリッジホストのホスト名またはIPアドレスに置き換える必要があります。
  • デフォルトのClickHouse JDBCブリッジポート9019を指定しました。JDBCブリッジに異なるポートを使用している場合は、上記の構成を適宜修正する必要があります。