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

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

注記

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

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

ClickHouse JDBC Bridge architecture diagram

これは、外部データソースにネイティブな組み込み統合エンジン、テーブル関数、または外部辞書が利用できない場合でも、データソース用のJDBCドライバが存在する場合に便利です。

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

このレッスンでは、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 locally deployment diagram

まず、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をフォアグラウンドモードで起動しました。ブリッジを停止するには、上記の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 external deployment diagram

これにより、各ClickHouseホストがJDBC 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に別のポートを使用している場合は、上記の設定を適宜調整する必要があります。