JDBC接続

注記

この機能は、Databricks Runtime 18.1、およびDBSQL 2025.40以降でパブリックプレビュー版として提供されています。SQLウェアハウスの場合は、 「サーバレスSQLウェアハウスで分離されたワークロードのネットワークを有効にする」 プレビューもオプトインする必要があります。

Databricks は、JDBC を使用した外部データベースへの接続をサポートしています。JDBC Unity Catalog接続を使用して、 SparkデータソースAPIまたはDatabricks Remote Query SQL APIでデータソースの読み取りと書き込みを行うことができます。 JDBC 接続は、Unity Catalog 内のセキュリティ保護可能なオブジェクトであり、外部データベースにアクセスするための JDBC ドライバー、URL パス、および資格情報を指定します。JDBC接続は、サーバレス、標準クラスタ、専用クラスタ、 Databricks SQLなどのUnity Catalogコンピュートタイプ全体でサポートされています。

JDBC接続を使用する利点

JDBCとSparkデータソースAPIを使用してデータソースの読み取りと書き込みを行います。
Remote Query SQL APIを使用してJDBCでデータソースから読み取ります。
Unity Catalog接続を使用したデータソースへの管理されたアクセス。
接続を一度作成すると、 Unity Catalogコンピュート全体で再利用できます。
Sparkおよびコンピュートのアップグレードに対して安定しています。
接続資格情報はクエリを実行するユーザーに対して非表示になります。

JDBCとクエリフェデレーション

JDBC はクエリフェデレーションを補完します。Databricks では、次の理由からクエリフェデレーションを選択することを推奨しています。

クエリフェデレーションは、フォーリンカタログを使用してテーブルレベルでのきめ細かいアクセス制御とガバナンスを提供します。 JDBC Unity Catalog接続は、接続レベルでのみガバナンスを提供します。
クエリフェデレーションは、最適なクエリパフォーマンスを実現するために Spark クエリをプッシュダウンします。

注記

クエリフェデレーションは、 Oracle 、 MySQL 、 PostgreSQL 、 SQL Server 、 Snowflakeなど、多くの一般的なデータベースをサポートしています。データベースがサポートされている場合、Databricks では JDBC 接続ではなくクエリフェデレーションを使用することをお勧めします。サポートされているデータベースの完全なリストについては、レイクハウスフェデレーションを参照してください。

ただし、次のシナリオでは、 JDBC Unity Catalog接続を使用することを選択します。

データベースはクエリフェデレーションではサポートされていません。
特定の JDBC ドライバーを使用したい。
Sparkを使用してデータソースに書き込む必要があります (クエリフェデレーションは書き込みをサポートしていません)。
SparkデータソースAPIオプションを使用して、さらなる柔軟性、パフォーマンス、および並列化制御が必要です。
Spark queryオプションを使用してSQLクエリをプッシュダウンしたい。

PySparkソースではなくJDBCを使用する理由は何ですか?

PySparkデータソースは、 JDBC Sparkデータソースの代替です。

JDBC 接続を使用します。

組み込みの Spark JDBC サポートを使用する場合。
すでに存在するすぐに使用可能な JDBC ドライバーを使用する場合。
接続レベルでの Unity Catalog ガバナンスが必要な場合。
Unity Catalogコンピュートから接続する場合は、「サーバレス」、「標準」、「専用」、 SQL APIと入力します。
Python 、 Scala 、 SQL APIsとの接続を使用する場合。

PySparkデータソースを使用します。

Pythonを使用してSparkデータソースまたはデータシンクを柔軟に開発および設計したい場合。
ノートブックまたは PySpark ワークロードでのみ使用する場合。
カスタムパーティションロジックを実装する場合。

JDBCもPySparkデータソースも、操作の順序の選択に役立つ統計をクエリオプティマイザーに公開しません。

仕組み

JDBC接続を使用してデータソースに接続するには、 SparkコンピュートにJDBCドライバーをインストールします。この接続により、 Sparkコンピュートからアクセスできる分離されたサンドボックスにJDBCドライバーを指定してインストールでき、 SparkセキュリティとUnity Catalogガバナンスを確保できます。サンドボックスの詳細については、 Databricksユーザー分離をどのように強制しますか?」を参照してください。。

始める前に

サーバレスおよび標準クラスターでSparkデータソースAPIとのJDBC接続を使用するには、まず次の要件を満たす必要があります。

ワークスペースの要件：

Unity Catalog に対応した Databricks ワークスペース

コンピュートの要件：

コンピュートリソースからターゲットデータベースシステムへのネットワーク接続。「ネットワーク接続」を参照してください。
Databricksコンピュートは、標準モードまたは専用アクセスモードでサーバレス、またはDatabricks Runtime 17.3 LTS以降を使用する必要があります。
SQLはプロまたはサーバレスであり、2025.35 以降を使用する必要があります。

必要な権限：

接続を作成するには、ワークスペースにアタッチされたメタストアに対するCREATE CONNECTION権限が必要です。
CREATE または、接続作成者によるUnity CatalogボリュームへのMANAGEアクセス。
接続を照会するユーザーによるボリュームアクセス。
追加の権限は、後続の各タスクベースのセクションで指定されます。

認証方法

固定されている認証情報

静的資格情報認証では、資格情報を接続に直接保存します。—たとえば、ユーザー名とパスワード、API キー、またはターゲット JDBC ドライバーで受け入れられる他の資格情報フィールドなどです。接続の使用時に、資格情報はそのままJDBCドライバーに渡されます。

OAuthによるマシン間通信

備考

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

OAuth マシン間 (M2M) 認証は、2つのシステムまたはアプリケーションが直接ユーザーの関与なしに通信する場合に利用されます。独自の資格情報を使用して認証する登録済みマシンクライアントに、トークンが発行されます。この認証方法は、ユーザーコンテキストを必要としないサービス間の通信、マイクロサービス、自動化タスクに最適です。

JDBC接続でOAuth M2Mを使用する場合、Unity Catalogは、構成されたトークンエンドポイントでクライアント資格情報を交換し、ドライバーのトークンパラメーターを使用して、結果として得られる有効期間の短いアクセストークンのみをJDBCドライバーに渡します。

ステップ 1: ボリュームを作成し、 JDBC JARをインストールします

JDBC接続はUnity CatalogボリュームからJDBCドライバーJAR読み取ってインストールします。

既存のボリュームへの書き込みおよび読み取りアクセス権がない場合は、新しいボリュームを作成します。
SQL
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
JDBC ドライバー JAR をボリュームにアップロードします。
接続を照会するユーザーにボリュームの読み取りアクセス権を付与します。
SQL
```
GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
```

ステップ 2: JDBC接続を作成する

JDBC接続はUnity Catalogのセキュリティ保護可能なオブジェクトです。JDBCドライバー、URLパス、外部データベースシステムにアクセスするための認証情報、およびクエリを実行するユーザーが指定できる許可されたオプションを指定します。接続を作成するには、カタログエクスプローラーを使用するか、DatabricksノートブックまたはDatabricks SQLクエリエディターで CREATE CONNECTION SQLコマンドを使用できます。サポートされている認証方法については、認証方法をご覧ください。

注記

Databricks REST API または Databricks CLI を使用して接続を作成することもできます。 POST /api/2.1/unity-catalog/connections および Unity Catalog コマンドを参照してください。

必要な権限： メタストア管理者またはCREATE CONNECTION権限を持つユーザー。

接続を作成する前に、以下の点にご注意ください。

URL と認証情報が唯一の必須オプションです。資格情報をURLに埋め込まないでください、ログやエラーによって公開される可能性があります。選択した認証方法には、専用の認証情報オプションをご利用ください。
externalOptionsAllowList使用すると、クエリ実行時にユーザーが指定できる Spark データソースのオプションを制御できます。指定がない場合、デフォルト値は'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'です。空の文字列に設定すると、ユーザーが接続で定義されたオプションのみを使用できるようになります。ユーザーはurlまたはhostを指定することはできません。

Catalog Explorer
SQL

Databricks ワークスペースで、 カタログ をクリックします。
接続をクリックし、その後、 Connections をクリックします。
接続の作成 をクリックします。
接続のセットアップ ウィザードの 「接続の基本」 ページで、ユーザーフレンドリな 接続名 を入力します。
接続タイプ には、 JDBC を選択します。
（オプション）コメントを追加します。
次へをクリックします。
接続の詳細 ページで、次の接続プロパティを入力します。

属性	説明
URL	データベースのJDBC URL。形式は`jdbc:subprotocol:subname`です（例: `jdbc:oracle:thin:@<host>:<port>:<SID>`）。
Javaの依存関係	Unity CatalogボリュームからのJDBCドライバーJARファイル。各JAR（例: ）を追加するには、[JAR依存関係を追加] `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar` をクリックします。
外部オプション許可リスト	クエリー時にユーザーが指定できる、Spark データソースオプションのカンマ区切りリスト。デフォルトは`dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions`です。空の値に設定すると、ユーザーは接続で定義されたオプションのみに制限されます。
追加オプション	任意のJDBCドライバーオプションがキーと値のペアとしてドライバーに渡されます。このセクションを使用して、データベース資格情報（例：キー`user`とキー`password`）およびその他のドライバー固有のプロパティを設定します。必要に応じて、 UI 入力モードと JSON 入力モードを切り替えます。

接続の作成 をクリックします。

OAuthマシン間 (Beta)

備考

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

jdbc_oauth_m2m_connectorワークスペースでプレビューが有効になっている場合、**接続の基本**ページに**静的認証情報**および**OAuthによるマシン間通信**オプションとともに**認証タイプ**フィールドが表示されます。 OAuth M2M JDBC 接続を作成するには：

接続の基本 ページで、 認証タイプ を OAuth Machine to Machine に設定してください。
次へをクリックします。
接続の詳細 ページで、 URL および Javaの依存関係 に加えて、次のプロパティを入力します。

属性	説明
クライアントID	アプリケーションに発行されたOAuthクライアントIDです。
クライアントのシークレット	アプリケーションに発行された OAuth クライアントシークレット。
OAuthスコープ	トークン交換中にリクエストするスコープ。大文字と小文字を区別するスペース区切りの文字列のリストとして表現されます。
トークンのエンドポイント	クライアント資格情報をアクセストークンと交換するために使用されるOAuth 2.0トークンエンドポイントです。通常は`https://authorization-server.com/oauth/token`の形式です。
OAuth認証情報の交換方法	クライアント資格情報がトークンエンドポイントに渡される方法： header_and_body ：認証情報は`Authorization`ヘッダーとリクエスト本文の両方で送信されます（デフォルト）。 body_only — 資格情報はリクエスト本文のみで送信されます。 header_only ：資格情報は`Authorization`ヘッダーでのみ送信されます。
JDBCトークンパラメーター名	ターゲットJDBCドライバーがOAuthアクセストークンを受け入れるために必要なプロパティ KEY 。Databricksは、生成された有効なOAuthアクセストークンをこのパラメーター VALUE に動的に設定します。一般的なKEY： `access_token`、`oauthToken` 、または`password` です。正しいパラメーター KEY 名については、JDBC ドライバーのドキュメントを参照してください。

接続の作成 をクリックします。

CREATE CONNECTION SQL コマンドをノートブックまたはDatabricks SQL クエリエディターで実行します。

固定されている認証情報

対応するボリューム、URL、資格情報、および externalOptionsAllowList を調整して、次のコマンドを実行します。

SQL
DROP CONNECTION IF EXISTS <JDBC-connection-name>;

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<Schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

DESCRIBE CONNECTION <JDBC-connection-name>;

例: Oracle JDBC接続

次の例では、Oracle シンドライバーを使用して Oracle データベースへの JDBC 接続を作成します。このコマンドを実行する前に、 Oracle JDBCダウンロードページから Oracle JDBCドライバーJAR (たとえば、 ojdbc11.jar ) をダウンロードし、 Unity Catalogボリュームにアップロードしてください。

SQL
CREATE CONNECTION oracle_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/ojdbc11.jar"]'
)
OPTIONS (
  url 'jdbc:oracle:thin:@<host>:<port>:<SID>',
  user '<oracle_user>',
  password '<oracle_password>',
  externalOptionsAllowList 'dbtable,query'
);

OAuthによるマシン間通信

対応するボリューム、URL、資格情報、および externalOptionsAllowList を調整して、次のコマンドを実行します。

SQL
CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint '<https://authorization-server.com/oauth/token>',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '<driver-token-parameter-name>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

例: PostgreSQL JDBC接続 (OAuth M2M)

以下の例は、OAuthマシン間認証を使用してPostgreSQLデータベースへのJDBC接続を作成します。PostgreSQL JDBCダウンロードページからPostgreSQL JDBCドライバーJAR（たとえば、postgresql-42.7.3.jar）をダウンロードし、Unity Catalogボリュームにアップロードしてから、このコマンドを実行してください。パスワードフィールドでOAuthアクセストークンを受け入れるように構成されているPostgreSQLデプロイメントの場合は、jdbc_token_parameter_nameをpasswordに設定します。

SQL
CREATE CONNECTION postgres_oauth_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/postgresql-42.7.3.jar"]'
)
OPTIONS (
  url 'jdbc:postgresql://<host>:<port>/<database>?sslmode=require',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint 'https://authorization-server.com/oauth/token',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name 'password',
  externalOptionsAllowList 'dbtable,query'
);

接続の所有者または管理者は、JDBCドライバがサポートする追加オプションを接続に追加できます。セキュリティ上の理由から、接続時に定義されたオプションはクエリ実行時に上書きできません。

ステップ 3: `USE`権限を付与します

接続に対するUSE権限をユーザーに付与します:

SQL
GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-name>;

既存の接続の管理については、「レイクハウスフェデレーションの接続の管理」を参照してください。

ステップ 4: データソースをクエリする

USE CONNECTION権限を持つユーザーは、 Spark経由のJDBC接続またはリモートクエリSQL APIを使用して、データソースをクエリできます。ユーザーは、 JDBCドライバーでサポートされ、 JDBC接続のexternalOptionsAllowListで指定されている任意のSparkデータソースオプションを追加できます (この場合は'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions' )。許可されるオプションを表示するには、次のクエリを実行します。

SQL
DESCRIBE CONNECTION <JDBC-connection-name>;

Python
SQL

Python
df = (
  spark.read.format('jdbc')
  .option('databricks.connection', '<JDBC-connection-name>')
  .option('query', 'select * from <table_name>') # query in source SQL language - Option specified by querying user
  .load()
)

df.display()

SQL
SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in source SQL language - Option specified by querying user

移住

既存のSparkデータソースAPIワークロードから移行するには、 Databricks次のことを行うことをお勧めします。

SparkデータソースAPIのオプションから URL と認証情報を削除します。
SparkデータソースAPIのオプションにdatabricks.connectionを追加します。
対応する URL と資格情報を使用して JDBC 接続を作成します。
接続では、静的である必要があり、クエリユーザーによって指定されるべきではないオプションを指定します。
接続のexternalOptionsAllowListで、クエリ時にユーザーがSparkデータソースAPIコードで調整または変更する必要があるデータソースオプションを指定します (例: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions' )。

制限事項

Spark データソース API

URL とホストをSparkデータソースAPIに含めることはできません。
.option("databricks.connection", "<Connection_name>") が必要です。
接続で定義されたオプションは、クエリ時にコード内のデータソースAPIで使用することはできません。
クエリを実行するユーザーは、 externalOptionsAllowListで指定されたオプションのみを使用できます。
JDBC ドライバーのメモリ制限は 400 MiB です。制限に達した場合は、より小さいfetchSizeの使用を検討してください。

サポート

Sparkデータソースはサポートされていません。
Lakeflow Spark宣言型パイプラインはサポートされていません。
作成時の接続依存関係: java_dependenciesは、JDBC ドライバー JAR のボリュームの場所のみをサポートします。
クエリでの接続依存性: 接続ユーザーには、JDBC ドライバー JAR が配置されているボリュームへのREADアクセスが必要です。
専用アクセスモード (以前のシングルユーザーアクセスモード) では、接続を使用するには、接続の所有者または管理者である必要があります。
SSL 証明書はサポートされていません。
フォーリンカタログはJDBC接続ではサポートされていません。

認証

このコネクタは静的認証情報とOAuthによるマシン間通信に対応しています。Unity Catalog の資格情報またはサービス資格情報をサポートしていません。

ネットワーキング

ターゲットデータベースシステムと Databricks ワークスペースを同じ VPC に配置することはできません。

ネットワーク接続

コンピュートリソースからターゲットデータベースシステムへのネットワーク接続が必要です。一般的なネットワークのガイダンスについては、「レイクハウスフェデレーションのネットワークに関する推奨事項」を参照してください。

Classic コンピュート: 標準および専用クラスター

Databricks VPC は、Spark クラスターのみを許可するように構成されています。別のインフラストラクチャに接続するには、ターゲットデータベースシステムを別の VPC に配置し、VPC ピアリングを使用します。VPC ピアリングが確立されたら、クラスターまたはウェアハウス上のconnectionTest UDF との接続を確認します。

Databricks ワークスペースとターゲットデータベースシステムが同じ VPC 内にある場合、Databricks では次のいずれかを推奨します。

サーバレスコンピュートを使用します。
ポート 80 および 443 経由の TCP および UDP トラフィックを許可するようにターゲットデータベースを構成し、接続でこれらのポートを指定します。

サーバレス

サーバレスコンピュートでJDBC接続を使用する場合は、安定した IP に対するサーバレスコンピュートアクセス用のファイアウォールを構成するか、プライベート接続を構成します。

接続テスト

Databricksコンピュートとデータベースシステムの間の接続をテストするには、次のUDFを使用します。

SQL
CREATE OR REPLACE TEMPORARY FUNCTION connectionTest(host string, port string) RETURNS string LANGUAGE PYTHON AS $$
import subprocess
try:
    command = ['nc', '-zv', host, str(port)]
    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    return str(result.returncode) + "|" + result.stdout.decode() + result.stderr.decode()
except Exception as e:
    return str(e)
$$;

SELECT connectionTest('<database-host>', '<database-port>');

FAQ

以下のよくある質問では、JDBC接続の述語プッシュダウンの動作について説明します。

JDBC は述語プッシュダウンをサポートしていますか？

はい。フィルターはデフォルトでリモートデータベースにプッシュダウンされます。これは、Spark Data Source API（format('jdbc')）とremote_query SQL関数の両方についてです。プッシュできる述語はJDBCドライバーと方言に依存するため、クエリーに対してEXPLAINを実行し、物理プランを検査して、どのフィルターがソースにプッシュされているかを確認してください。remote_query SQL関数では、pushdown.filters.enabledなどのオプションを使用して、特定のプッシュダウン（フィルター、制限、オフセット、集計）を制御できます。すべてデフォルトで有効になっています。

述語プッシュダウンは、テーブル統計をクエリーオプティマイザーに公開することとは異なります。JDBCおよびPySparkデータソースは、述語がプッシュダウンされるかどうかにかかわらず、操作の順序を選択するのに役立つ統計をクエリーオプティマイザーに公開しません。

JDBC接続を使用する利点​

JDBCとクエリフェデレーション​

PySparkソースではなくJDBCを使用する理由は何ですか?​

仕組み​

始める前に​

認証方法​

ステップ 1: ボリュームを作成し、 JDBC JARをインストールします​

ステップ 2: JDBC接続を作成する​

ステップ 3: USE権限を付与します​

ステップ 4: データソースをクエリする​

移住​

制限事項​

Spark データソース API​

サポート​

認証​

ネットワーキング​

ネットワーク接続​

Classic コンピュート: 標準および専用クラスター​

サーバレス​

接続テスト​

FAQ​

JDBC は述語プッシュダウンをサポートしていますか？​