JDBC ドライバー

v0.8+

注記

clickhouse-jdbcは最新のJavaクライアントを使用して標準JDBCインターフェースを実装しています。 パフォーマンスまたは直接アクセスが重要な場合は、最新のJavaクライアントを直接使用することを推奨します。

環境要件

• OpenJDK バージョン 8 以上

セットアップ

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.6</version>
    <classifier>all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.6:all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.6:all'

設定

ドライバークラス: com.clickhouse.jdbc.ClickHouseDriver

注記

com.clickhouse.jdbc.ClickHouseDriverは、新旧のJDBC実装に対するファサードクラスです。デフォルトでは新しいJDBC実装が使用されます。 接続プロパティでclickhouse.jdbc.v1プロパティをtrueに設定することにより、古いJDBC実装を使用できます。

com.clickhouse.jdbc.Driver は新しいJDBC実装です。 com.clickhouse.jdbc.DriverV1 は旧JDBC実装です。

URL構文: jdbc:(ch|clickhouse)[:<protocol>]://endpoint[:port][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]、例:

• jdbc:clickhouse:http://localhost:8123
• jdbc:clickhouse:https://localhost:8443?ssl=true

URL構文に関して、以下の点に注意してください:

• URL にはエンドポイントを 1 つのみ 設定できます
• デフォルトである 'HTTP' 以外のプロトコルを使用する場合は、プロトコルを明示的に指定する必要があります
• デフォルトのポート '8123' 以外を使用する場合は、ポート番号を明示的に指定する必要があります
• ドライバはポート番号からプロトコルを推測しないため、明示的に指定する必要があります。
• プロトコルを指定した場合は、ssl パラメータの指定は不要です。

接続プロパティ

主要な設定パラメータはJavaクライアントで定義されています。これらはそのままドライバに渡してください。ドライバには、クライアント設定には含まれない独自のプロパティがあり、以下に記載されています。

ドライバープロパティ:

プロパティ	デフォルト値	説明
disable_frameworks_detection	true	User-Agent に基づくフレームワーク検出を無効にする
jdbc_ignore_unsupported_values	false	SQLFeatureNotSupportedException がドライバーの動作に影響しない箇所では、その例外を抑制します
clickhouse.jdbc.v1	false	新しい JDBC 実装ではなく、旧 JDBC 実装を使用する
default_query_settings	null	クエリ操作にデフォルトのクエリ設定を渡せるようにする
jdbc_resultset_auto_close	true	Statement をクローズしたときに ResultSet も自動的にクローズします
beta.row_binary_for_simple_insert	false	RowBinary writer ベースの PreparedStatement 実装を使用します。INSERT INTO ... VALUES クエリに対してのみ有効です。
jdbc_resultset_auto_close	true	Statement のクローズ時に ResultSet を自動的にクローズします
jdbc_use_max_result_rows	false	サーバープロパティ max_result_rows の使用を有効にし、クエリで返される行数を制限します。有効化すると、ユーザー設定のオーバーフローモードを上書きします。詳細は JavaDoc を参照してください。
jdbc_sql_parser	JAVACC	使用する SQL パーサーを設定します。選択可能な値: ANTLR4, ANTLR4_PARAMS_PARSER, JAVACC。

サーバー設定

すべてのサーバー設定には clickhouse_setting_ のプレフィックスを付ける必要があります（クライアント設定と同様）。

Properties config = new Properties();
config.setProperty("user", "default");
config.setProperty("password", getPassword());

// set server setting
config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1");

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config);

設定例:

Properties properties = new Properties();
properties.setProperty("user", "default");
properties.setProperty("password", getPassword());
properties.setProperty("client_name", "my-app-01"); // when http protocol is used it will be `http_user_agent` in the query log but not `client_name`.

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

以下のJDBC URLと同等になります:

jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 
// credentials shoud be passed in `Properties`. Here it is just for example.

注記: JDBC URLやプロパティをURLエンコードする必要はありません。自動的にエンコードされます。

サポートされるデータ型

JDBCドライバは、基盤となるJavaクライアントと同じデータ型をサポートしています。

日付、時刻、タイムゾーンの処理

java.sql.Date、java.sql.Time、および java.sql.Timestamp はタイムゾーンの計算を複雑にする可能性があります。これらはもちろんサポートされていますが、 java.time パッケージの使用を検討してください。ZonedDateTime および OffsetDateTime は、java.sql.Timestamp、java.sql.Date、java.sql.Time の優れた代替手段です。

Date vs DateTime

Date はタイムゾーンなしで保存されますが、DateTime はタイムゾーン付きで保存されます。注意を怠ると予期しない結果を招く可能性があります。

接続の作成

String url = "jdbc:ch://my-server:8123/system";

Properties properties = new Properties();
DataSource dataSource = new DataSource(url, properties);//DataSource or DriverManager are the main entry points
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection

認証情報と設定の指定

String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";

Properties info = new Properties();
info.put("user", "default");
info.put("password", "password");
info.put("database", "some_db");

//Creating a connection with DataSource
DataSource dataSource = new DataSource(url, info);
try (Connection conn = dataSource.getConnection()) {
... // do something with the connection
}

//Alternate approach using the DriverManager
try (Connection conn = DriverManager.getConnection(url, info)) {
... // do something with the connection
}

単純なステートメント

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

Insert

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch();
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

HikariCP

// connection pooling won't help much in terms of performance,
// because the underlying implementation has its own pool.
// for example: HttpURLConnection has a pool for sockets
HikariConfig poolConfig = new HikariConfig();
poolConfig.setConnectionTimeout(5000L);
poolConfig.setMaximumPoolSize(20);
poolConfig.setMaxLifetime(300_000L);
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));

try (HikariDataSource ds = new HikariDataSource(poolConfig);
     Connection conn = ds.getConnection();
     Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
    while (rs.next()) {
        // handle row
        log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//Same column but different types
    }
}

詳細情報

詳細については、GitHubリポジトリおよびJavaクライアントのドキュメントを参照してください。

トラブルシューティング

ログ

このドライバはログ記録に slf4j を使用し、classpath 上で最初に利用可能な実装を使用します。

大規模挿入時のJDBCタイムアウトの解決

ClickHouseで実行時間の長い大規模なインサート処理を実行する際、次のようなJDBCタイムアウトエラーが発生することがあります:

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

これらのエラーはデータ挿入プロセスを中断し、システムの安定性に影響を与える可能性があります。この問題に対処するには、クライアントOS上のいくつかのタイムアウト設定を調整する必要がある場合があります。

macOS

macOSでは、以下の設定を調整することで問題を解決できます:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

Linuxでは、同等の設定のみでは問題が解決しない場合があります。Linuxにおけるソケットキープアライブ設定の処理方法の違いにより、追加の手順が必要です。以下の手順に従ってください:

1. /etc/sysctl.conf または関連する設定ファイルで、以下の Linux カーネルパラメータを調整します。

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60（デフォルトの 300 秒より短くすることを検討してください）

2. カーネルパラメーターを変更したら、次のコマンドを実行して変更を適用します。

sudo sysctl -p

これらの設定を行った後、クライアントがソケット上でKeep Aliveオプションを有効にしていることを確認する必要があります:

properties.setProperty("socket_keepalive", "true");

移行ガイド

主な変更点

機能	V1（旧）	V2（新）
トランザクション対応	一部サポートあり	サポートなし
レスポンスカラム名の変更	一部サポートあり	サポートなし
複数文 SQL	サポートなし	利用不可
名前付きパラメーター	サポートあり	サポートなし（JDBC 仕様に非準拠）
PreparedStatement を用いたデータストリーミング	サポートあり	サポートなし

• JDBC V2 は、より軽量にするために実装されており、一部の機能が削除されています。
  • ストリーミングデータは JDBC 仕様および Java の標準機能に含まれていないため、JDBC V2 ではサポートされていません。
• JDBC V2 では明示的な設定が必要です。フェイルオーバー用のデフォルト設定はありません。
  • プロトコルは URL で明示的に指定する必要があります。ポート番号に基づく暗黙的なプロトコルの自動判別は行われません。

設定の変更

列挙型は2つのみです:

• com.clickhouse.jdbc.DriverProperties - ドライバー固有の設定プロパティです。
• com.clickhouse.client.api.ClientConfigProperties - クライアントの構成プロパティを表します。クライアント構成の変更については、Java クライアントのドキュメントを参照してください。

接続プロパティは次のように解析されます:

• URL は最初にプロパティとして解析され、その値が他のすべてのプロパティより優先されます。
• ドライバーのプロパティはクライアント側に渡されません。
• エンドポイント（ホスト、ポート、プロトコル）は URL から解析されます。

例:

String url = "jdbc:ch://my-server:8443/default?" +
            "jdbc_ignore_unsupported_values=true&" +
            "socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
    // Connection will use socket_rcvbuf=800000 and jdbc_ignore_unsupported_values=true
    // Endpoints: my-server:8443 protocol: http (not secure)
    // Database: default
}

データ型の変更

ClickHouse 型	符号なし	JDBC 型 (V2)	Java クラス (V2)	JDBC 型 (V1)	Java クラス (V1)
Int8	いいえ	TINYINT	java.lang.Byte	TINYINT	java.lang.Byte
Int16	いいえ	SMALLINT	java.lang.Short	SMALLINT	java.lang.Short
Int32	いいえ	INTEGER	java.lang.Integer	INTEGER	java.lang.Integer
Int64	いいえ	BIGINT	java.lang.Long	BIGINT	java.lang.Long
UInt8	はい	OTHER	java.lang.Short	OTHER	com.clickhouse.data.value.UnsignedByte
UInt16	はい	OTHER	java.lang.Integer	OTHER	com.clickhouse.data.value.UnsignedShort
UInt32	はい	OTHER	java.lang.Long	OTHER	com.clickhouse.data.value.UnsignedInteger
UInt64	はい	OTHER	java.math.BigInteger	OTHER	com.clickhouse.data.value.UnsignedLong
Int128	いいえ	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt128	いいえ	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Int256	いいえ	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
UInt256	いいえ	OTHER	java.math.BigInteger	OTHER	java.math.BigInteger
Float32	いいえ	REAL	java.lang.Float	REAL	java.lang.Float
Float64	いいえ	DOUBLE	java.lang.Double	DOUBLE	java.lang.Double
Decimal32	いいえ	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal64	いいえ	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal128	いいえ	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Decimal256	いいえ	DECIMAL	java.math.BigDecimal	DECIMAL	java.math.BigDecimal
Bool	いいえ	BOOLEAN	java.lang.Boolean	BOOLEAN	java.lang.Boolean
String	いいえ	VARCHAR	java.lang.String	VARCHAR	java.lang.String
FixedString	いいえ	CHAR	java.lang.String	CHAR	java.lang.String
Date	はい	DATE	java.sql.Date	DATE	java.time.LocalDate
Date32	はい	DATE	java.sql.Date	DATE	java.time.LocalDate
DateTime	はい	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
DateTime64	はい	TIMESTAMP	java.sql.Timestamp	TIMESTAMP	java.time.OffsetDateTime
UUID	いいえ	OTHER	java.util.UUID	OTHER	java.util.UUID
IPv4	いいえ	OTHER	java.net.Inet4Address	OTHER	java.net.Inet4Address
IPv6	いいえ	OTHER	java.net.Inet6Address	OTHER	java.net.Inet6Address

• 符号なし型はポータビリティを高めるために Java 型にマップされます。
• Date と Date32 は、JDBC との互換性を高めるために java.sql.Date にマッピングされます。ただし、ResultSet.getObject(int, Class<T>) の第 2 引数に java.time.LocalDate.class を指定することで、java.time.LocalDate を取得することも可能です。
• Array 型は java.sql.Array オブジェクトにマッピングされます。
• Tuple は java.sql.Struct オブジェクトにマッピングされますが、Array としても扱うことができます。

clickhouse-jdbcは標準のJDBCインターフェースを実装しています。clickhouse-client上に構築されており、カスタム型マッピング、トランザクションサポート、標準的な同期UPDATEおよびDELETE文などの追加機能を提供するため、レガシーアプリケーションやツールと容易に使用できます。

注記

最新のJDBC（0.7.2）バージョンはClient-V1を使用しています

clickhouse-jdbc APIは同期的であり、一般的にはより多くのオーバーヘッド(例:SQLの解析や型のマッピング/変換など)が発生します。パフォーマンスが重要な場合、またはClickHouseへのより直接的なアクセス方法を希望する場合は、clickhouse-clientの使用を検討してください。

環境要件

• OpenJDK バージョン 8 以上

セットアップ

Maven

<!-- https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc -->
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.7.2</version>
    <!-- すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください -->
    <classifier>shaded-all</classifier>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください
implementation("com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all")

Gradle

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
// すべての依存関係を含む Uber JAR を使用します。JAR を小さくするには classifier を http に変更してください
implementation 'com.clickhouse:clickhouse-jdbc:0.7.2:shaded-all'

バージョン 0.5.0 以降、クライアントにバンドルされた Apache HTTP Client を使用しています。このパッケージには共有バージョンが存在しないため、ロガーを依存関係として追加する必要があります。

Maven

<!-- https://mvnrepository.com/artifact/org.slf4j/slf4j-api -->
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.16</version>
</dependency>

Gradle (Kotlin)

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation("org.slf4j:slf4j-api:2.0.16")

Gradle

// https://mvnrepository.com/artifact/org.slf4j/slf4j-api
implementation 'org.slf4j:slf4j-api:2.0.16'

設定

ドライバークラス: com.clickhouse.jdbc.ClickHouseDriver

URL構文: jdbc:(ch|clickhouse)[:<protocol>]://endpoint1[,endpoint2,...][/<database>][?param1=value1&param2=value2][#tag1,tag2,...]、例:

• jdbc:ch://localhost は jdbc:clickhouse:http://localhost:8123 と同じです。
• jdbc:ch:https://localhost は jdbc:clickhouse:http://localhost:8443?ssl=true&sslmode=STRICT と同等です
• jdbc:ch:grpc://localhost は jdbc:clickhouse:grpc://localhost:9100 と等価です。

接続プロパティ:

プロパティ	既定値	説明
continueBatchOnError	false	エラーが発生してもバッチ処理を継続するかどうか
createDatabaseIfNotExist	false	データベースが存在しない場合に作成するかどうか
custom_http_headers		カンマ区切りで指定するカスタム HTTP ヘッダー。例: User-Agent=client1,X-Gateway-Id=123
custom_http_params		カンマ区切りのカスタム HTTP クエリパラメータ（例：extremes=0,max_result_rows=100）
nullAsDefault	0	0 - null 値をそのまま扱い、null 非許容のカラムに null を挿入しようとした場合は例外をスローする; 1 - null 値をそのまま扱い、挿入時の null チェックを無効化する; 2 - クエリおよび挿入の両方で、null を対応するデータ型のデフォルト値に置き換える
jdbcCompliance	true	標準的な同期 UPDATE/DELETE と疑似トランザクションをサポートするかどうか
typeMappings		ClickHouse のデータ型と Java クラスとの対応付けをカスタマイズします。これは、getColumnType() と getObject(Class<>?>) の両方の戻り値に影響します。例：UInt128=java.lang.String,UInt256=java.lang.String
wrapperObject	false	getObject() が Array / Tuple 型に対して java.sql.Array / java.sql.Struct を返すかどうかを指定します。

注記: 詳細はJDBC固有の設定を参照してください。

サポートされるデータ型

JDBCドライバは、クライアントライブラリと同じデータ形式をサポートしています。

注記

• AggregatedFunction - ⚠️ SELECT * FROM table ... はサポートしていません
• 10進数 - 一貫性を保つため、21.9 以降では SET output_format_decimal_trailing_zeros=1 を設定
• Enum - 文字列型および整数型の両方として扱える
• UInt64 - client-v1 では long にマップされます

接続の作成

String url = "jdbc:ch://my-server/system"; // use http protocol and port 8123 by default

Properties properties = new Properties();

ClickHouseDataSource dataSource = new ClickHouseDataSource(url, properties);
try (Connection conn = dataSource.getConnection("default", "password");
    Statement stmt = conn.createStatement()) {
}

単純なステートメント

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

Insert

注記

• Statement ではなく PreparedStatement を使用してください

使用は容易ですが、input関数と比較してパフォーマンスが劣ります（以下を参照）：

try (PreparedStatement ps = conn.prepareStatement("insert into mytable(* except (description))")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

input テーブル関数を使用する

高いパフォーマンス特性を持つオプション:

try (PreparedStatement ps = conn.prepareStatement(
    "insert into mytable select col1, col2 from input('col1 String, col2 DateTime64(3), col3 Int32')")) {
    // The column definition will be parsed so the driver knows there are 3 parameters: col1, col2 and col3
    ps.setString(1, "test"); // col1
    ps.setObject(2, LocalDateTime.now()); // col2, setTimestamp is slow and not recommended
    ps.setInt(3, 123); // col3
    ps.addBatch(); // parameters will be write into buffered stream immediately in binary format
    ...
    ps.executeBatch(); // stream everything on-hand into ClickHouse
}

• 可能な限り input 関数のドキュメント を参照してください

プレースホルダーを使用した挿入

このオプションは小規模な挿入にのみ推奨されます。長いSQL式が必要となり、クライアント側で解析されてCPUとメモリを消費するためです:

try (PreparedStatement ps = conn.prepareStatement("insert into mytable values(trim(?),?,?)")) {
    ps.setString(1, "test"); // id
    ps.setObject(2, LocalDateTime.now()); // timestamp
    ps.setString(3, null); // description
    ps.addBatch(); // append parameters to the query
    ...
    ps.executeBatch(); // issue the composed query: insert into mytable values(...)(...)...(...)
}

DateTimeとタイムゾーンの取り扱い

java.sql.Timestampの代わりにjava.time.LocalDateTimeまたはjava.time.OffsetDateTimeを、java.sql.Dateの代わりにjava.time.LocalDateを使用してください。

try (PreparedStatement ps = conn.prepareStatement("select date_time from mytable where date_time > ?")) {
    ps.setObject(2, LocalDateTime.now());
    ResultSet rs = ps.executeQuery();
    while(rs.next()) {
        LocalDateTime dateTime = (LocalDateTime) rs.getObject(1);
    }
    ...
}

AggregateFunctionの取り扱い

注記

現時点では、groupBitmap のみサポートされています。

// batch insert using input function
try (ClickHouseConnection conn = newConnection(props);
        Statement s = conn.createStatement();
        PreparedStatement stmt = conn.prepareStatement(
                "insert into test_batch_input select id, name, value from input('id Int32, name Nullable(String), desc Nullable(String), value AggregateFunction(groupBitmap, UInt32)')")) {
    s.execute("drop table if exists test_batch_input;"
            + "create table test_batch_input(id Int32, name Nullable(String), value AggregateFunction(groupBitmap, UInt32))engine=Memory");
    Object[][] objs = new Object[][] {
            new Object[] { 1, "a", "aaaaa", ClickHouseBitmap.wrap(1, 2, 3, 4, 5) },
            new Object[] { 2, "b", null, ClickHouseBitmap.wrap(6, 7, 8, 9, 10) },
            new Object[] { 3, null, "33333", ClickHouseBitmap.wrap(11, 12, 13) }
    };
    for (Object[] v : objs) {
        stmt.setInt(1, (int) v[0]);
        stmt.setString(2, (String) v[1]);
        stmt.setString(3, (String) v[2]);
        stmt.setObject(4, v[3]);
        stmt.addBatch();
    }
    int[] results = stmt.executeBatch();
    ...
}

// use bitmap as query parameter
try (PreparedStatement stmt = conn.prepareStatement(
    "SELECT bitmapContains(my_bitmap, toUInt32(1)) as v1, bitmapContains(my_bitmap, toUInt32(2)) as v2 from {tt 'ext_table'}")) {
    stmt.setObject(1, ClickHouseExternalTable.builder().name("ext_table")
            .columns("my_bitmap AggregateFunction(groupBitmap,UInt32)").format(ClickHouseFormat.RowBinary)
            .content(new ByteArrayInputStream(ClickHouseBitmap.wrap(1, 3, 5).toBytes()))
            .asTempTable()
            .build());
    ResultSet rs = stmt.executeQuery();
    Assert.assertTrue(rs.next());
    Assert.assertEquals(rs.getInt(1), 1);
    Assert.assertEquals(rs.getInt(2), 0);
    Assert.assertFalse(rs.next());
}

HTTPライブラリの設定

ClickHouse JDBCコネクタは、以下の3つのHTTPライブラリをサポートしています:HttpClient、HttpURLConnection、およびApache HttpClient。

注記

HttpClient は JDK 11 以降でのみサポートされています。

JDBCドライバーはデフォルトでHttpClientを使用します。ClickHouse JDBCコネクタが使用するHTTPライブラリを変更するには、以下のプロパティを設定します:

properties.setProperty("http_connection_provider", "APACHE_HTTP_CLIENT");

対応する値の一覧は以下の通りです:

プロパティ値	HTTPライブラリ
HTTP_CLIENT	HttpClient
HTTP_URL_CONNECTION	HttpURLConnection
APACHE_HTTP_CLIENT	Apache HttpClient

SSLでClickHouseに接続する

SSLを使用してClickHouseへの安全なJDBC接続を確立するには、JDBCプロパティにSSLパラメータを含めるよう設定する必要があります。通常、JDBC URLまたはPropertiesオブジェクトにsslmodeやsslrootcertなどのSSLプロパティを指定します。

SSL プロパティ

名前	デフォルト値	選択可能な値	説明
ssl	false	true, false	接続で SSL/TLS を有効にするかどうか
sslmode	strict	strict, none	SSL/TLS 証明書を検証するかどうか
sslrootcert			SSL/TLS ルート証明書へのパス
sslcert			SSL/TLS 証明書へのパス
sslkey			PKCS#8 形式の RSA 鍵
key_store_type		JKS, PKCS12	KeyStore/TrustStore ファイルの種別または形式を指定します
trust_store			TrustStore ファイルのパス
key_store_password			KeyStore 設定で指定された KeyStore ファイルへアクセスするためのパスワード

これらのプロパティにより、JavaアプリケーションがClickHouseサーバーと暗号化接続で通信することが保証され、転送中のデータセキュリティが向上します。

  String url = "jdbc:ch://your-server:8443/system";

  Properties properties = new Properties();
  properties.setProperty("ssl", "true");
  properties.setProperty("sslmode", "strict"); // NONE to trust all servers; STRICT for trusted only
  properties.setProperty("sslrootcert", "/mine.crt");
  try (Connection con = DriverManager
          .getConnection(url, properties)) {

      try (PreparedStatement stmt = con.prepareStatement(

          // place your code here

      }
  }

大量挿入時のJDBCタイムアウトの解決

ClickHouseで実行時間の長い大規模なインサート処理を実行する際、次のようなJDBCタイムアウトエラーが発生することがあります:

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

これらのエラーはデータ挿入プロセスを中断し、システムの安定性に影響を与える可能性があります。この問題に対処するには、クライアントOS上のいくつかのタイムアウト設定を調整する必要があります。

Mac OS

macOSでは、以下の設定を調整することで問題を解決できます:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

Linux

Linuxでは、同等の設定のみでは問題が解決しない場合があります。Linuxにおけるソケットキープアライブ設定の処理方法の違いにより、追加の手順が必要です。以下の手順に従ってください:

1. /etc/sysctl.conf または関連する設定ファイルで、以下の Linux カーネルパラメータを調整します：

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60（デフォルト値の 300 秒から 60 秒へ下げることを検討してもよいでしょう）

2. カーネルパラメータを変更したら、以下のコマンドを実行して変更を反映します。

sudo sysctl -p

これらの設定を行った後、クライアントがソケット上でKeep Aliveオプションを有効にしていることを確認する必要があります:

properties.setProperty("socket_keepalive", "true");

注記

現在、ソケットのキープアライブを設定する際は、Apache HTTP Clientライブラリを使用する必要があります。clickhouse-javaがサポートする他の2つのHTTPクライアントライブラリでは、ソケットオプションの設定が許可されていないためです。詳細なガイドについては、HTTPライブラリの設定を参照してください。

または、JDBC URLに同等のパラメータを追加することもできます。

JDBCドライバーのデフォルトのソケットおよび接続タイムアウトは30秒です。大規模なデータ挿入操作をサポートするために、タイムアウトを延長できます。ClickHouseClientのoptionsメソッドを使用し、ClickHouseClientOptionで定義されているSOCKET_TIMEOUTおよびCONNECTION_TIMEOUTオプションを指定してください:

final int MS_12H = 12 * 60 * 60 * 1000; // 12 h in ms
final String sql = "insert into table_a (c1, c2, c3) select c1, c2, c3 from table_b;";

try (ClickHouseClient client = ClickHouseClient.newInstance(ClickHouseProtocol.HTTP)) {
    client.read(servers).write()
        .option(ClickHouseClientOption.SOCKET_TIMEOUT, MS_12H)
        .option(ClickHouseClientOption.CONNECTION_TIMEOUT, MS_12H)
        .query(sql)
        .executeAndWait();
}