Databricks JDBC ドライバー (OSS)

[アーティクル]
11/16/2024

重要

このドライバーはパブリックプレビュー段階であり、オープンソースとしてはまだ利用できません。

Databricks には、DataGrip、DBeaver、SQL Workbench/J などのツールを JDBC 経由で Azure Databricks に接続できるオープンソースソフトウェア (OSS) JDBC ドライバーが用意されています。JDBC (Java Database Connectivity) は、データベース管理システムにアクセスする手段の業界標準仕様です。

このドライバーは JDBC API を実装しており、OAuth、Cloud Fetch、Unity Catalog ボリュームインジェストなどの機能を含むコア機能を提供します。これはネイティブクエリモードを実行し、ネイティブのパラメーター化クエリをサポートし、有益なクエリ結果保持機能を提供する Statement Execution API または Thrift を使用して実行できます。

この記事では、Databricks JDBC ドライバー (OSS) のインストールと使用に関する情報を提供します。 OSS ではない Databricks JDBC ドライバーの詳細については、Databricks JDBC ドライバーの説明を参照してください。

要件

Databricks JDBC ドライバー (OSS) を使用するには、以下の要件を満たす必要があります。

Java Runtime Environment (JRE) 11.0 以降。 CI テストは、JRE 11、17、および 21 でサポートされています。

Note

JDK 16 が変更され、JDBC ドライバーで使用される Apache Arrow ライブラリとの互換性の問題が発生したため、JDK 16 以降で JDBC ドライバーを使用するとランタイムエラーが発生する可能性があります。これらのエラーを回避するには、次の JVM コマンドオプションを使用して、アプリケーションまたはドライバーを再起動します。

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

ドライバーをインストールする

Databricks JDBC ドライバー (OSS) は Maven Repository で公開されています。最新バージョンは 0.9.6-oss です。

ドライバーをインストールするには、以下のいずれかの操作を行います。

Maven プロジェクトの場合は、指定したバージョンの JDBC ドライバーを自動的にダウンロードすることを Maven に指示するために、プロジェクトの pom.xml ファイルに以下の依存関係を追加します。
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
Gradle プロジェクトの場合は、指定したバージョンの JDBC ドライバーを自動的にダウンロードすることを Gradle に指示するために、プロジェクトのビルドファイルに以下の依存関係を追加します。
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

他の種類のプロジェクトで使用する依存関係構文と、Databricks JDBC ドライバー (OSS) の最新バージョン番号を確認する方法については、Maven リポジトリの説明を参照してください。

接続 URL を構成する

この JDBC ドライバーを使用して Azure Databricks ワークスペースに接続するには、JDBC 接続 URL を指定し、その中に Azure Databricks ワークスペースのサーバーホスト名、コンピューティングリソース設定、ワークスペースに接続するための認証資格情報などさまざまな接続設定を含める必要があります。

それらのプロパティの値は、JDBC 接続 URL で設定する方法、DriverManager.getConnection メソッドで設定して渡す方法、またはその両方を組み合わせて指定できます。特定のアプリ、クライアント、SDK、API、または SQL ツールを使用して接続する最適な方法については、プロバイダーのドキュメントを参照してください。

JDBC 接続 URL の形式は以下に従う必要があります。プロパティの大文字と小文字は区別されません。

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

この代わりに、java.util.Properties クラスまたは組み合わせによって設定を指定することもできます。

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

接続 URL 要素については、以下の表で説明するとおりです。認証プロパティなどの追加のプロパティについては、以下のセクションを参照してください。 URL 要素とプロパティの大文字と小文字は区別されません。

URL 要素またはプロパティ	説明
`<server-hostname>`	Azure Databricks コンピューティングリソースのサーバーホスト名の値。
`<port>`	Azure Databricks コンピューティングリソースのポート値。既定値は `443` です。
`<schema>`	スキーマの名前です。この代わりに、`ConnSchema` プロパティで設定することもできます。接続プロパティの説明を参照してください。
`httpPath`	Azure Databricks コンピューティングリソースの HTTP パス値。コネクタは、接続 URL で指定されたホストとポートに `httpPath` 値を付加することで、接続先の HTTP アドレスを形成します。たとえば、HTTP アドレス `http://localhost:10002/cliservice` に接続するための接続 URL は次のようなものになります: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Azure Databricks クラスターの JDBC 接続 URL を取得するには、以下のようにします。

Azure Databricks ワークスペースにログインします。
サイドバーの [コンピューティング] をクリックし、次に、ターゲットクラスターの名前をクリックします。
[構成] タブで、[詳細オプション] を展開します。
[JDBC/ODBC] タブをクリックします。
JDBC 接続 URL として使用する JDBC URL をコピーするか、サーバーホスト名、ポート、および HTTP パス フィールドの値から URL を作成します。

Databricks SQL ウェアハウスの JDBC 接続 URL を取得するには、以下のようにします。

Azure Databricks ワークスペースにログインします。
サイドバーの [SQL ウェアハウス] をクリックし、次に、ターゲットウェアハウスの名前をクリックします。
[接続の詳細] タブをクリックします。
JDBC 接続 URL として使用する JDBC URL をコピーするか、サーバーホスト名、ポート、および HTTP パス フィールドの値から URL を作成します。

ドライバーを認証する

JDBC ドライバー接続の認証には、以下のいずれかの認証メカニズムを使用できます。

OAuth ユーザー対マシン (U2M) 認証 (推奨)
OAuth マシン間 (M2M) 認証
Azure Databricks 個人用アクセストークン

OAuth ユーザー対マシン (U2M) 認証

JDBC ドライバーは、OAuth ユーザー対マシン (U2M) 認証に対応しており、リアルタイムの人間のサインインと同意を使用して、ターゲットの Databricks ユーザーアカウントを認証します。これは、ブラウザーベースの OAuth 認証とも呼ばれます。

Azure Databricks は、顧客用に OAuth クライアント ID databricks-sql-jdbc を作成しました。これは、JDBC ドライバーで使用される既定の OAuth クライアント ID でもあります。 OAuth U2M 認証を設定するには、既存の JDBC 接続 URL または java.util.Properties オブジェクトに次のプロパティを追加するだけです。

プロパティ	値
`AuthMech`	`11`
`Auth_Flow`	`2`

OAuth マシン間 (M2M) 認証

JDBC ドライバーは、Azure Databricks サービスプリンシパルを使用した OAuth マシン間 (M2M) 認証をサポートしています。これは、OAuth 2.0 ''クライアント資格情報'' 認証とも呼ばれます。「OAuth(OAuth M2M)を使用してサービスプリンシパルで Azure Databricks へのアクセスを認証する」を参照してください。

OAuth M2M または OAuth 2.0 クライアント資格情報認証を構成するには、以下のようにします。

Microsoft Entra ID マネージドサービスプリンシパルを作成し、それを Azure Databricks アカウントとワークスペースに割り当てます。詳細については、サービスプリンシパルの管理に関する説明を参照してください。

重要

Databricks JDBC ドライバー (OSS) は、OAuth M2M または OAuth 2.0 クライアント資格情報認証用の Azure Databricks OAuth シークレットをサポートしています。 Microsoft Entra ID シークレットはサポートされません。
サービスプリンシパルの Azure Databricks OAuth シークレットを作成します。これを行うには、「OAuth M2M 認証用のアクセストークンを手動で生成して使用する」を参照してください。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセス権を付与します。「コンピューティングのアクセス許可」または「SQL ウェアハウスを管理する」を参照してください。

以下のプロパティを、既存の JDBC 接続 URL または java.util.Properties オブジェクトに追加します。

プロパティ	値
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	サービスプリンシパルのアプリケーション (クライアント) ID 値。
`OAuth2Secret`	サービスプリンシパルの Azure Databricks OAuth シークレット。 (Microsoft Entra ID シークレットは、OAuth M2M または OAuth 2.0 クライアント資格情報認証ではサポートされていません。)

Azure Databricks 個人用アクセストークン

Azure Databricks 個人用アクセストークンを使用して JDBC ドライバー接続を認証する場合は、JDBC 接続 URL または java.util.Properties オブジェクトに以下のプロパティを追加します。

プロパティ	値
`AuthMech`	`3`
`user`	`token` 値 (文字列)。
`PWD` または `password`	Azure Databricks 個人用アクセストークン値 (文字列)。

接続のプロパティ

この JDBC ドライバーでは、以下に示す追加の接続プロパティがサポートされています。プロパティの大文字と小文字は区別されません。

プロパティ	既定値	説明
`AuthMech`	必須	認証メカニズム。`3` はメカニズムが Azure Databricks 個人用アクセストークンであること、`11` はメカニズムが OAuth 2.0 トークンであることを示します。いずれのメカニズムにも、追加のプロパティが必要です。ドライバーの認証に関する説明を参照してください。
`Auth_Flow`	`0`	ドライバー接続の OAuth2 認証フロー。このプロパティは、`AuthMech` が `11` である場合に必須です。
`SSL`	`1`	コネクタが Spark サーバーとの通信を SSL 対応ソケット経由で行うかどうか。
`ConnCatalog` または `catalog`	`SPARK`	使う既定のカタログの名前。
`ConnSchema` または `schema`	`default`	使う既定のスキーマの名前。これを指定するには、使用するスキーマの名前で URL 内の `<schema>` を置き換えるか、`ConnSchema` プロパティに使用するスキーマの名前を設定します。
`ProxyAuth`	`0`	`1` に設定した場合、ドライバーは、`ProxyUID` と `ProxyPwd` で表されたプロキシ認証ユーザーとパスワードを使用します。
`ProxyHost`	`null`	`UseProxy` も `1` に設定されている場合に使用する、プロキシホストの名前を表す文字列。
`ProxyPort`	`null`	`UseProxy` も `1` に設定されている場合に使用する、プロキシポートの番号を表す整数。
`ProxyUID`	`null`	`ProxyAuth` と `UseProxy` も `1` に設定されている場合に使用する、プロキシ認証用のユーザー名を表す文字列。
`ProxyPwd`	`null`	`ProxyAuth` と `UseProxy` も `1` に設定されている場合に使用する、プロキシ認証用のパスワードを表す文字列。
`UseProxy`	`0`	`1` に設定した場合、ドライバーは、指定されたプロキシ設定を使用します (例: `ProxyAuth`、`ProxyHost`、`ProxyPort`、`ProxyPwd`、`ProxyUID`)。
`UseSystemProxy`	`0`	`1` に設定した場合、ドライバーは、システムレベルで設定されたプロキシ設定を使用します。接続 URL 内に追加のプロキシプロパティが設定されている場合、それらの追加のプロキシプロパティは、システムレベルで設定されたプロキシプロパティよりも優先されます。
`UseCFProxy`	`0`	`1` に設定した場合、ドライバーは、クラウドフェッチプロキシ設定が提供されていればそれを使用し、そうでない場合は通常のプロキシを使用します。
`CFProxyAuth`	`0`	`1` に設定した場合、ドライバーは、`CFProxyUID` と `CFProxyPwd` で表されたプロキシ認証ユーザーとパスワードを使用します。
`CFProxyHost`	`null`	`UseCFProxy` も `1` に設定されている場合に使用する、プロキシホストの名前を表す文字列。
`CFProxyPort`	`null`	`UseCFProxy` も `1` に設定されている場合に使用する、プロキシポートの番号を表す整数。
`CFProxyUID`	`null`	`CFProxyAuth` と `UseCFProxy` も `1` に設定されている場合に使用する、プロキシ認証用のユーザー名を表す文字列。
`CFProxyPwd`	`null`	`CFProxyAuth` と `UseCFProxy` も `1` に設定されている場合に使用する、プロキシ認証用のパスワードを表す文字列。
`AsyncExecPollInterval`	`200`	非同期クエリ実行ステータスを確認するポーリング間隔の時間 (ミリ秒単位)。ここでいう非同期は、Spark に対するクエリ実行のための RPC 呼び出しが非同期に処理されるという事実を指します。 JDBC 非同期操作のサポートを意味するものではありません。
`UserAgentEntry`	`browser`	HTTP 要求に含められる User-Agent エントリ。この値の形式は次のとおりです: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Thrift クライアントで JDBC ドライバーを使用して汎用クラスターに接続する必要があるかどうか。既定値は、SQL ウェアハウスで機能します。

SQL 構成プロパティ

この JDBC ドライバーでは、以下に示す SQL 構成プロパティがサポートされています。これらについては、設定パラメータの説明も参照してください。プロパティの大文字と小文字は区別されません。

プロパティ	既定値	説明
`ansi_mode`	`TRUE`	特定の関数とキャストルールに関して、厳密な ANSI SQL 動作を有効にするかどうか。
`enable_photo`	`TRUE`	Photon ベクター化クエリエンジンを有効にするかどうか。
`legacy_time_parser_policy`	`EXCEPTION`	日付とタイムスタンプの解析と書式設定に使用するメソッド。有効な値は、`EXCEPTION`、`LEGACY`、`CORRECTED` です。
`max_file_partition_bytes`	`128m`	ファイルベースのソースからの読み取り時に 1 つのパーティションに取り込める最大バイト数です。この設定には任意の正の整数を使用でき、オプションとして、単位 `b` (バイト)、`k` または `kb` (1024 バイト) などを付けることもできます。
`read_only_external_metastore`	`false`	外部メタストアを読み取り専用として扱うかどうかを制御します。
`statement_timeout`	`172800`	SQL ステートメントのタイムアウトを 0 から 172,800 秒までの範囲で設定します。
`timezone`	`UTC`	ローカルタイムゾーンを設定します。 `area/city` 形式 (America/Los_Angeles など) のリージョン ID、または (+\|-)HH、(+\|-)HH:mm または (+\|-)HH:mm:ss 形式 (例: -08、+01:00、-13:33:33) のゾーンオフセット。また、`UTC` は、+00:00 の別名としてサポートされています。
`use_cached_result`	`true`	可能な限り Databricks SQL が結果をキャッシュして再利用するかどうか。

ログのプロパティ

この JDBC ドライバーでは、以下のログ記録プロパティがサポートされています。プロパティの大文字と小文字は区別されません。

プロパティ	既定値	説明
`LogLevel`	`OFF`	ログレベル (0 から 6 までの値): - 0: すべてのログ取得を無効にします。 - 1: FATAL レベルのログ記録を有効にして、コネクタの動作中止を引き起こすような非常に重大なエラーイベントをログに記録します。 - 2: ERROR レベルのログ記録を有効にして、コネクタの実行を継続できる可能性があるエラーイベントをログに記録します。 - 3: WARNING レベルのログ記録を有効にして、対応アクションが行われないとエラーになる可能性があるイベントをログに記録します。 - 4: INFO レベルのログ記録を有効にして、コネクタの処理進行状況を伝える一般的な情報をログに記録します。 - 5: DEBUG レベルのログ記録を有効にして、コネクタのデバッグに役立つ詳細情報をログに記録します。 - 6: TRACE レベルのログ記録を有効にして、すべてのコネクタアクティビティをログに記録します。このプロパティでは、コネクタでのログ記録を有効または無効に設定することや、ログファイルに含める詳細情報の量を指定することができます。
`LogPath`	ログの既定のパスを決定するために、ドライバーは、次の優先順位で、これらのシステムプロパティに設定された値を使用します。 1. `user.dir` 2. `java.io.tmpdir` 3. 現在のディレクトリ、つまり `.`	ログ記録を有効にした場合にコネクタのログファイルを保存するフォルダの絶対パス (文字列)。接続 URL がすべての JDBC アプリケーションと互換性があることを確認するには、別の円記号を入力して、ファイルパス内の円記号 (`\`) をエスケープします。 `LogPath`値が無効な場合、コネクタはログに記録された情報を標準出力ストリーム (System.out) に送信します。
`LogFileSize`	最大値なし	許可されるログファイルの最大サイズ (MB 単位)
`LogFileCount`	最大値なし	許可されるログファイルの最大数

ログ記録の有効化と構成

JDBC ドライバーは、Java (SLF4J) および java.util.logging (JUL) フレームワークの Simple Logging Facade をサポートしています。ドライバーは、既定で JUL ログフレームワークを使用します。

JDBC ドライバーのログ記録を有効にして構成するには:

使用するログ記録フレームワークを有効にします。
- SLF4J ログの場合は、システム・プロパティー -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER 設定し、SLF4J バインディング実装 (SLF4J バージョン 2.0.13 以降と互換性があります) と、対応する構成ファイルをクラスパスに提供します。
- JUL ログの場合は、システムプロパティの -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERを設定します。これが既定です。
接続文字列のLogLevel プロパティを、ログファイルに含める必要な情報レベルに設定します。
接続文字列の LogPath プロパティを、ログファイルを保存するフォルダーへの完全なパスに設定します。

たとえば、次の接続 URL を使用すると、ログレベル 6 が有効になり、ログファイルが C:temp フォルダーに保存されます。
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
JDBC アプリケーションを再起動し、サーバーに再接続して設定を適用します。

例: JDBC ドライバーを使用したクエリ実行

以下の例は、Azure Databricks コンピューティングリソースを使用する Databricks SQL クエリを、JDBC ドライバーを使用して実行する方法を示しています。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

次の方法で共有

Databricks JDBC ドライバー (OSS)

要件

ドライバーをインストールする

接続 URL を構成する

ドライバーを認証する

OAuth ユーザー対マシン (U2M) 認証

OAuth マシン間 (M2M) 認証

Azure Databricks 個人用アクセストークン

接続のプロパティ

SQL 構成プロパティ

ログのプロパティ

ログ記録の有効化と構成

例: JDBC ドライバーを使用したクエリ実行

その他のリソース

フィードバック

その他のリソース

次の方法で共有

Databricks JDBC ドライバー (OSS)

要件

ドライバーをインストールする

接続 URL を構成する

ドライバーを認証する

OAuth ユーザー対マシン (U2M) 認証

OAuth マシン間 (M2M) 認証

Azure Databricks 個人用アクセス トークン

接続のプロパティ

SQL 構成プロパティ

ログのプロパティ

ログ記録の有効化と構成

例: JDBC ドライバーを使用したクエリ実行

その他のリソース

フィードバック

その他のリソース

Azure Databricks 個人用アクセストークン