JDBC 接続

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

JDBC 接続を使用する利点

• Spark データ ソース API で JDBC を使用してデータ ソースに対する読み取りと書き込みを行います。
• リモート クエリ SQL API を使用して JDBC を使用してデータ ソースから読み取る。
• Unity カタログ接続を使用してデータ ソースへのアクセスを管理しました。
• 接続を 1 回作成し、任意の Unity カタログ コンピューティングで再利用します。
• Spark とコンピューティングのアップグレードに対して安定しています。
• 接続資格情報は、クエリを実行するユーザーには表示されません。

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

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

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

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

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

JDBC データ ソースと PySpark データ ソースを使用する理由

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

JDBC 接続を使用します。

• 組み込みの Spark JDBC サポートを使用する場合。
• 既存の即使用可能な JDBC ドライバーを使用する場合。
• 接続レベルで Unity カタログ ガバナンスが必要な場合。
• Unity カタログのコンピューティングの種類 (サーバーレス、標準、専用、SQL API) から接続する場合。
• Python、Scala、および SQL API との接続を使用する場合。

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

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

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

動作方法

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

Requirements

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

ワークスペースの要件:

• Unity カタログに対して有効になっている Azure Databricks ワークスペース

コンピューティング要件:

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

必要なアクセス許可:

• 接続を作成するには、ワークスペースにアタッチされているメタストアに対する CREATE CONNECTION 特権が必要です。
• 接続の作成者による Unity Catalog ボリュームへのアクセス権の CREATE または MANAGE。
• 接続を照会するユーザーによるボリューム アクセス。

認証方法

手順 1: ボリュームを作成して JDBC JAR をインストールする

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

1. 既存のボリュームへの書き込みと読み取りアクセス権がない場合は、 新しいボリュームを作成します。

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. ボリュームに JDBC ドライバー JAR をアップロード します。

3. 接続を照会するユーザーに、ボリュームに対する読み取りアクセス権を付与します。

   GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
   

手順 2: JDBC 接続を作成する

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

接続を作成する前に、次の点に注意してください。

• 接続を作成するメタストア管理者またはユーザーが CREATE CONNECTION 権限を持つ必要があります。
• URL と資格情報のみが必要なオプションです。 ログやエラーで公開される可能性があるため、URL に資格情報を埋め込む必要はありません。 選択した 認証方法に専用の資格情報オプションを使用します。
• externalOptionsAllowListを使用して、ユーザーがクエリ時に指定できる Spark データ ソース オプションを制御します。 指定しない場合、既定値は 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'です。 接続で定義されているオプションのみにユーザーを制限するには、空の文字列に設定します。 ユーザーは、 url や hostを指定することはできません。
• もしターゲットのデータベースがクエリ時にデータベースを選択する必要がある場合(例えば、SQL Serverのように接続URLでピン留めされていない場合)、externalOptionsAllowListにdatabaseを含めて、クエリユーザーがパスできるようにしましょう。 database はデフォルトの許可リストに含まれていません。

カタログ エクスプローラー

1. Azure Databricks ワークスペースで、[ カタログ。

2. [ [接続] をクリックし、[ 接続] をクリックします。

3. [接続の作成] をクリックします。

4. 接続 のセットアップ ウィザードの [接続の基本] ページで、わかりやすい 接続名入力します。

5. [ 接続の種類] で、[ JDBC] を選択します。

6. (省略可能)コメントを追加します。

7. [次へ] をクリックします。

8. [ 接続の詳細 ] ページで、次の接続プロパティを入力します。

   プロパティ	Description
   Url	jdbc:subprotocol:subname形式のデータベースの JDBC URL (たとえば、jdbc:oracle:thin:@<host>:<port>:<SID>)。
   Javaの依存関係	Unity カタログ ボリュームの JDBC ドライバー JAR ファイル。 [ JAR 依存関係の追加] をクリックして各 JAR を追加します (例: /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar)。
   外部オプションの許可リスト	ユーザーにクエリを実行する際に指定できる Spark データ ソース オプション のコンマ区切りの一覧。 既定値は dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions です。 接続で定義されているオプションのみにユーザーを制限するには、空の値に設定します。
   その他のオプション	キーと値のペアとしてドライバーに渡される任意の JDBC ドライバー オプション。 このセクションでは、データベース資格情報 (キー user やキー passwordなど) とその他のドライバー固有のプロパティを設定します。 必要に応じて 、UI と JSON の入力モードを切り替えます。

9. [接続の作成] をクリックします。

SQL

ノートブックまたは Databricks SQL クエリ エディターで CREATE CONNECTION 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>;

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'
);

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'
);

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 特権を付与します。

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

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

手順 4: データ ソースのクエリを実行する

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

DESCRIBE CONNECTION <JDBC-connection-name>;

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

クエリ時にターゲットデータベースを選択する必要があるデータベースの場合は、 database オプションをパスしてください。 以下のSQL Server例は、特殊文字や保留語を処理するために、スキーマ名とテーブル名を括弧付き([...])で引用しています。

SELECT * FROM remote_query(
  '<JDBC-connection-name>',
  database => 'test-db',
  query => 'SELECT TOP 100 * FROM [dbo].[FactFinance]'
);

Migration

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

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

制限事項

Spark データ ソース API

• URL とホストを Spark データ ソース API に含めることはできません。
• .option("databricks.connection", "<Connection_name>") は必須です。
• 接続で定義されているオプションは、クエリ時にコード内のデータ ソース API では使用できません。
• ユーザーにクエリを実行すると、 externalOptionsAllowList で指定されたオプションのみを使用できます。
• JDBC ドライバーのメモリ制限は 400 MiB です。 制限に達した場合は、より小さな fetchSize を使用することを検討してください。
• Spark JDBC データ ソースは、外部データベースに対する任意の DML ステートメント ( UPDATE や DELETEなど) をサポートしていません。 行レベルの変更ではなく、データの読み取りとテーブル全体の追加または上書きをサポートします。

Support

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

Authentication

• このコネクタは、静的資格情報と OAuth マシン間をサポートします。 Unity カタログの資格情報またはサービス資格情報はサポートされていません。

ネットワーク

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

ネットワーク接続

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

クラシック コンピューティング: 標準クラスターと専用クラスター

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

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

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

Serverless

サーバーレス コンピューティングで JDBC 接続を使用する場合は、許可リストに送信 IP を追加することで、ターゲット データベース システムへの サーバーレス コンピューティング アクセス用のファイアウォールを構成 できます。 または、 プライベート接続を構成することもできます。

接続テスト

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

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 は述語プッシュダウンをサポートしていますか?

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

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