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 ワークスペースで、 カタログ をクリックします。
カタログ パネルの上部にあるアイコン を追加し 、メニューから 接続の作成を 選択します。
接続のセットアップ ウィザードの 「接続の基本」 ページで、ユーザーフレンドリな 接続名 を入力します。
JDBC の 接続タイプ を選択します。
次のオプションから 認証タイプ を選択します：
- 固定されている認証情報
- OAuthによるマシン間通信
（オプション）コメントを追加します。
次へをクリックします。
認証ページで、選択した認証方式の次の接続プロパティを入力します。

固定されている認証情報

Property	Description
JDBC URL	The JDBC connection URL for your database (for example, `jdbc:oracle:thin:@<host>:<port>:<SID>`).
User	The database username.
Password	The database password.
Java dependencies	The Unity Catalog volume path to the JDBC driver JAR (for example, `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar`).

OAuthによるマシン間通信

Property	Description
JDBC URL	The JDBC connection URL for your database.
Client ID	The OAuth client ID issued for the application.
Client secret	The OAuth client secret issued for the application.
OAuth scope	Scope to request during the token exchange. Expressed as a space-delimited list of case-sensitive strings.
Token endpoint	The OAuth 2.0 token endpoint used to exchange the client credentials for an access token. Usually in the format `https://authorization-server.com/oauth/token`.
OAuth credential exchange method	How the client credentials are passed to the token endpoint: header_and_body — credentials are sent in both the `Authorization` header and the request body (default). body_only — credentials are sent in the request body only. header_only — credentials are sent in the `Authorization` header only.
JDBC token parameter name	The property KEY required by the target JDBC driver to accept the OAuth access token. Databricks dynamically populates this parameter VALUE with a generated valid OAuth access token. For example, typical KEYs: `access_token`, `oauthToken`, or `password`. Refer to your JDBC driver's documentation for the correct parameter KEY name.
Java dependencies	The Unity Catalog volume path to the JDBC driver JAR (for example, `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar`).

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

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データソースはサポートされていません。
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>');

JDBC接続を使用する利点​

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

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

仕組み​

始める前に​

認証方法​

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

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

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

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

移住​

制限事項​

Spark データソース API​

サポート​

認証​

ネットワーキング​

ネットワーク接続​

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

サーバレス​

接続テスト​

JDBC接続を使用する利点

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

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

仕組み

始める前に

認証方法

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

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

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

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

移住

制限事項

Spark データソース API

サポート

認証

ネットワーキング

ネットワーク接続

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

サーバレス

接続テスト