JDBC 連結

Azure Databricks 支援使用 JDBC 連接外部資料庫。 你可以使用 JDBC Unity 目錄連線，透過 Spark Data Source API 或 Azure Databricks 遠端查詢 SQL API 讀寫資料來源。 JDBC 連線是 Unity 目錄中一個可保護的物件，指定 JDBC 驅動程式、URL 路徑及存取外部資料庫的憑證。 JDBC 連線支援多個 Unity 目錄運算類型，包括無伺服器叢集、標準叢集、專用叢集及 Databricks SQL。

使用 JDBC 連線的好處

• 使用 JDBC 搭配 Spark Data Source API 對資料來源進行讀取與寫入。
• 使用 JDBC 使用 Remote Query SQL API 從資料來源讀取資料。
• 使用 Unity Catalog 連線來管控資料來源的存取。
• 建立一次連線，然後在任何 Unity Catalog 運算中重複使用。
• Spark 和運算升級都很穩定。
• 對查詢使用者隱藏連線認證憑據。

JDBC 與查詢聯盟

JDBC 是 查詢整合的互補技術。 Databricks 建議選擇查詢聯盟，原因如下：

• 查詢聯盟利用外部目錄，在資料表層級提供細緻的存取控制與治理。 JDBC Unity 目錄連線僅在連線層級提供治理。
• 查詢聯邦將 Spark 查詢下推以實現最佳查詢效能。

然而，在以下情境下，請選擇使用 JDBC Unity 目錄連線：

• 你的資料庫沒有被查詢聯盟支援。
• 你要用特定的 JDBC 驅動程式。
• 你需要用 Spark 寫入資料來源（查詢聯盟不支援寫入）。
• 你需要透過 Spark Data Source API 選項提供更多彈性、效能與平行化控制。
• 您想使用 Spark query 選項下推來源 SQL 查詢。

為什麼要用 JDBC 而不是 PySpark 資料來源？

PySpark 資料來源 是 JDBC Spark 資料來源的替代方案。

使用JDBC連線：

• 如果你想使用內建的 Spark JDBC 支援，
• 如果你想使用現成的 JDBC 驅動程式，
• 如果你需要在連線層級的 Unity Catalog 管理。
• 如果你想從任何 Unity Catalog 的運算類型連線：無伺服器、標準、專用、SQL API。
• 如果你想用你的連線來支援 Python、Scala 和 SQL API，

使用 PySpark 資料來源：

• 如果你想有彈性，能用 Python 開發和設計你的 Spark 資料來源或資料匯，
• 如果你只在筆記本或 PySpark 工作負載中使用它。
• 如果你想實作自訂分割邏輯，

JDBC 和 PySpark 的資料來源都不會將統計數據暴露給查詢優化器來幫助選擇操作順序。

運作方式

若要使用 JDBC 連線連接資料來源，請在 Spark 運算中安裝 JDBC 驅動程式。 此連線讓你能在 Spark 運算可存取的隔離沙盒中指定並安裝 JDBC 驅動程式，以確保 Spark 安全性與 Unity 目錄治理。 欲了解更多沙盒資訊，請參閱 Databricks 如何強制使用者隔離？

要求

要在無伺服器及標準叢集上使用 JDBC 連線與 Spark Data Source API 連接，您必須先符合以下要求：

工作空間需求：

• Azure Databricks 工作空間支援 Unity Catalog

計算需求：

• 從你的計算資源到目標資料庫系統的網路連線。 請參見 網路連線。
• Azure Databricks 運算必須使用無伺服器模式，或在標準模式或專用存取模式下使用 Databricks Runtime 17.3 LTS 或以上版本。 JDBC 連線通常可在 Databricks Runtime 19 及以上版本中取得，並在 Databricks Runtime 17.3 LTS 到 Databricks Runtime 18 LTS 期間處於 公開預覽。 Databricks 建議公開預覽版使用者遷移至 Databricks Runtime 19 或更高版本。
• SQL 倉庫必須是專業版或無伺服器型，且必須使用 2025.40 或更高版本。
• 對於無伺服器 SQL 倉庫，必須啟用 在 Serverless SQL Warehouses 中為隔離工作負載啟用網路功能 預覽。 請參閱 管理預覽設定。

所需的權限：

• 要建立連線，你必須擁有 CREATE CONNECTION 連接到工作區的 metastore 權限。
• CREATE 或 MANAGE 由連線建立者存取 Unity Catalog 磁區。
• 使用者在查詢連線時的磁碟區存取權限。

驗證方法

步驟 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 路徑、存取外部資料庫系統的憑證，以及查詢使用者可指定的允許清單選項。 要建立連線，請使用 Catalog Explorer 或 CREATE CONNECTION Azure Databricks 筆記本中的 SQL 指令，或 Databricks SQL 查詢編輯器。 請參閱 認證方法以 了解支援的認證方法。

在建立連結前，請注意以下事項：

• Metastore 管理員或建立連線的使用者必須擁有該 CREATE CONNECTION 權限。
• 網址和憑證是唯一必要的選項。 不要在網址中嵌入憑證，因為日誌或錯誤可能會暴露憑證。 請使用你選擇的 認證方式專用憑證選項。
• 用來 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. 在 連接細節 頁面輸入以下連接屬性：

   屬性	描述
   Url	你的資料庫 JDBC 網址，格式為 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。 設為空值，限制使用者只能使用連線上定義的選項。
   使用者提供的伺服器憑證	Optional. 這是 JDBC 驅動程式在 TLS 握手時驗證資料庫伺服器時所信任的 PEM 編碼憑證。 參見 （可選）新增 SSL 憑證。
   其他選項	任意的 JDBC 驅動選項以鍵值對傳遞給驅動程式。 使用此區塊設定資料庫憑證（例如金鑰 user 與金鑰 password）及其他驅動程式專屬屬性。 需要時可以切換 UI 和 JSON 輸入模式。

9. 點選 「建立連線」。

SQL

在筆記本中使用 CREATE CONNECTION SQL 指令或 Databricks 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 驅動程式所支援的額外選項。 出於安全考量，連線中定義的選項在查詢時無法被覆蓋。

（可選）新增 SSL 憑證

如果你的資料庫伺服器顯示來自私人或內部憑證授權機構的憑證，且不在預設的 Java 信任儲存庫中，請使用 userProvidedServerCertificate 選項將該憑證加入連線。 每次使用連線時，Azure Databricks 會將憑證加入執行 JDBC 驅動程式之沙盒的預設 Java 信任存放區，在任何使用該連線的運算資源上。 這需要無伺服器運算或 Databricks Runtime 19 及以上版本。

在 Catalog Explorer 中，將憑證貼上到 使用者提供的伺服器憑證 欄位（位於 連線詳情 頁面）。 在 SQL 裡，設定 userProvidedServerCertificate 選項。 以下範例建立一個 Db2 連線以驗證伺服器憑證：

CREATE CONNECTION db2_ssl_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/db2-driver.jar"]'
)
OPTIONS (
  url 'jdbc:db2://<host>:<ssl-port>/<database>:sslConnection=true;',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query',
  userProvidedServerCertificate '-----BEGIN CERTIFICATE-----
<certificate-content>
-----END CERTIFICATE-----'
);

憑證只會建立信任。 它不會啟用 SSL。 在 JDBC URL 中啟用 SSL 和伺服器憑證驗證，使用驅動程式要求的參數，例如 Db2 的 sslConnection=true。 驅動程式必須根據預設的 Java 信任儲存庫驗證伺服器憑證。 使用自有信任儲存設定的驅動程式會忽略此憑證。

步驟三：授予 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 Data Source API 工作負載遷移，Databricks 建議採取以下步驟：

• 請在 Spark Data Source API 的選項中移除 URL 和憑證。
• 在 Spark Data Source API 的選項中添加 databricks.connection。
• 建立一個帶有對應 URL 和憑證的 JDBC 連線。
• 在連線中，指定哪些選項應該是靜態的，且不應由查詢使用者指定。
• 在連線的externalOptionsAllowList中，指定使用者在查詢時，應在 Spark 資料來源 API 程式碼中調整或變更的資料來源選項（例如，'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'）。

局限性

Spark 資料來源 API

• Spark 資料來源 API 中無法包含 URL 與主機。
• .option("databricks.connection", "<Connection_name>") 是必要的。
• 連線中定義的選項在查詢時不能用於程式碼中的資料來源 API。
• 只有 中 externalOptionsAllowList 指定的選項才能被查詢的使用者使用。
• JDBC 驅動程式的記憶體上限為 400 MiB。 如果達到極限，可以考慮使用較小的 fetchSize。
• Spark JDBC 資料來源不支援對外部資料庫的任意 DML 陳述，如 UPDATE 或 DELETE。 它支援讀取資料並附加或覆寫整個資料表，而非資料列層級的修改。

Support

• 不支援 Spark 資料來源。
• Lakeflow pipelines 不受支援。
• 在建立時的連線依賴：java_dependencies 僅支援 JDBC 驅動程式 JAR 的儲存卷位置。
• 查詢時的連線依賴性：連線使用者需要 READ 存取 JDBC 驅動程式 JAR 所在的磁碟區。
• 在專用存取模式（過去稱為單一使用者存取模式）中，您必須是連線的擁有者或管理者才能使用。
• JDBC 連線不支援國外目錄。

Authentication

• 此連接器支援靜態憑證與 OAuth 機器對機器。 它不支援 Unity Catalog 憑證或服務憑證。

SSL 憑證

• userProvidedServerCertificate 需要無伺服器運算或 Databricks 執行時 19 及以上版本。
• 為每個連線提供一個 PEM 編碼的憑證。 若值包含多個憑證，則僅載入第一張憑證。
• 憑證值最多可為 10 KB。

網路

• 目標資料庫系統和 Azure Databricks 工作空間不能在同一個 VNet 裡。

網路連線

需要將運算資源與目標資料庫系統之間建立網路連線。 請參閱湖屋聯盟的網路建議以獲得一般的網路指引。

經典運算：標準與專用叢集

Azure Databricks VNet 設定為只允許 Spark 叢集。 若要連接其他基礎設施，請將目標資料庫系統放在不同的 VNet，並使用 VNet 對等。 VNet 對等建立後，檢查你與 connectionTest 叢集或倉庫 UDF 的連線狀況。

如果您的 Azure Databricks 工作空間與目標資料庫系統在同一個 VNet，Databricks 建議以下其中之一：

• 使用無伺服器運算。
• 設定目標資料庫允許 TCP 和 UDP 流量透過 80 和 443 埠，並在連線中指定這些埠口。

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 是否支援條件下推（predicate pushdown）？

Yes. Spark Data Source API （format('jdbc')） remote_query 和 SQL 函式的過濾器預設會推送到遠端資料庫。 可下推的述詞取決於 JDBC 驅動程式和方言，因此請對您的查詢執行 EXPLAIN，並檢查實體計畫，以確認哪些篩選條件已下推到來源端。 對於 remote_query SQL 函式，你可以用以下選項 pushdown.filters.enabled控制特定的推下功能（篩選、限制、偏移量和聚合），這些預設都是啟用的。

謂詞下推有別於將資料表統計資訊提供給查詢優化器。 JDBC 和 PySpark 資料來源不會將統計資訊提供給查詢優化器，以協助其選擇作業順序，而不論是否下推述詞。