JDBC Unity Catalog接続

注記

この機能は、Databricks Runtime 17.3 以降ではベータ版です。

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クエリをプッシュダウンし、最適なクエリパフォーマンスを実現します。

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

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

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アクセス
接続を照会するユーザーによるボリュームアクセス
追加の権限要件は、以下の各タスクベースのセクションに記載しています。

ステップ 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接続を作成する

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、資格情報、およびexternalOptionsAllowListを調整しながら、ノートブックまたは SQL クエリエディターで次のコマンドを実行します。

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

接続の所有者または管理者は、JDBC ドライバーでサポートされている追加オプションを接続に追加できます。

セキュリティ上の理由から、接続で定義されたオプションはクエリ時に上書きできません。ユーザーは、接続でまだ定義されていないSparkデータソースオプションのみを指定できます。

externalOptionsAllowListを使用すると、接続作成者は、ユーザーがクエリ時に指定できるSparkデータソースオプションを指定できます。この例では、ユーザーは'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'のみを使用できます。UC 接続で指定されたオプションのみが使用されるようにするには、 externalOptionsAllowList空の文字列にすることができます。URL とホストはユーザーによって指定することはできません。

接続を作成するときに必須となるオプションは URL のみです。許可リストが指定されていない場合は、 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'を含むデフォルトの許可リストが使用されます。

Databricks では、接続時に資格情報を指定することをお勧めします。

ステップ 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 Database native SQL language - Option specified by querying user
.load()

df.display()

SQL
SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in Database native 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で指定されたオプションのみを使用できます。

サポート

Sparkデータソースはサポートされていません。
Spark宣言型パイプラインはサポートされていません。
作成時の接続依存関係: java_dependenciesは、JDBC ドライバー JAR のボリュームの場所のみをサポートします。
クエリでの接続依存性: 接続ユーザーには、JDBC ドライバー JAR が配置されているボリュームへのREADアクセスが必要です。

認証

基本認証（ユーザー名とパスワード）のみがサポートされます。Unity Catalog資格情報、 OAuth 、またはサービス資格情報はサポートされていません。

ネットワーキング

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

ネットワーク接続

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

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

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

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

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

接続テスト

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 コンピュート: 標準および専用クラスター​

接続テスト​