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

JDBC Driver (0.8+)

clickhouse-jdbc は最新の java client を使用して標準的なJDBCインターフェースを実装しています。 パフォーマンスや直接アクセスが重要な場合は、最新の java client を直接使用することをお勧めします。

注記

以前のバージョンのJDBCドライバーのドキュメントをお探しの場合は、こちらをご覧ください。

Changes from 0.7.x​

0.8では、ドライバーをJDBC仕様により厳密に従うようにしました。そのため、いくつかの機能が削除されており、あなたに影響を及ぼす可能性があります：

古い機能注釈
トランザクションサポート初期バージョンのドライバーはトランザクションサポートを シミュレート していただけで、予期しない結果を引き起こす可能性がありました。
レスポンスカラムのリネームResultSet は可変でした - 効率のために現在は読み取り専用です。
マルチステートメントSQLマルチステートメントサポートは シミュレート されていただけで、現在は1:1に厳密に従います。
名前付きパラメータJDBC仕様の一部ではありません。
ストリームベースの PreparedStatement初期バージョンのドライバーでは PreparedStatement の非jdbc使用が許可されていました - このようなオプションが必要な場合は、Java Client とその 例 を確認することをお勧めします。
注記

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

環境要件​

セットアップ​

設定​

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

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

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

接続プロパティ:

標準JDBCプロパティの他に、ドライバーは基盤の java client が提供するClickHouse特有のプロパティもサポートします。サポートされていない機能がある場合、可能な限り SQLFeatureNotSupportedException が返されます。他のカスタムプロパティには以下が含まれます：

プロパティデフォルト説明
disable_frameworks_detectiontrueUser-Agentのフレームワーク検出を無効にする
jdbc_ignore_unsupported_valuesfalseSQLFeatureNotSupportedException を抑制
clickhouse.jdbc.v1false新しいJDBCの代わりに古いJDBC実装を使用する
default_query_settingsnullクエリ操作にデフォルトのクエリ設定を渡すことを可能にする

サポートされているデータ型​

JDBCドライバーは、基盤の java client と同じデータ形式をサポートしています。

日付、時間、タイムゾーンの取り扱い​

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

接続の作成​

資格情報と設定の提供​

シンプルステートメント​

挿入​

HikariCP​

その他の情報​

詳細については、GitHubリポジトリ と Java Client ドキュメント をご覧ください。

トラブルシューティング​

ロギング​

ドライバーは slf4j を使用してロギングを行い、classpath 上の最初の利用可能な実装を使用します。

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

長時間実行される大規模な挿入をClickHouseで行う場合、次のようなJDBCタイムアウトエラーに遭遇することがあります：

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

Mac OS​

Mac OSでは、次の設定を調整して問題を解決できます。

  • 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. カーネルパラメータを変更した後、次のコマンドを実行して変更を適用します：

これらの設定を行った後、クライアントがソケットのキープアライブオプションを有効にすることを確認する必要があります：