使用 Databricks JDBC 驅動程式設定與 Databricks 的連線

本頁說明如何使用 Databricks JDBC 驅動程式 3 版及以上設定與 Databricks 的連線。

設定連線

要使用 JDBC 驅動程式連接 Azure Databricks 工作區,你需要指定連線設定,包括工作區的伺服器主機名稱、運算資源設定和認證憑證。

備註

JDBC 驅動程式無法連接到 jobs 計算平台。

在 JDBC 連線 URL 上設定這些屬性,傳給 DriverManager.getConnection 方法,或兩者結合使用。 請參閱提供者的檔,以瞭解如何使用您的特定應用程式、用戶端、SDK、API 或 SQL 工具進行連線。

JDBC 連線 URL 的格式必須如下。 屬性不區分大小寫。

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

或者,使用 java.util.Properties 類別或組合來指定設定:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);
String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

下表說明連線 URL 元素。

如需其他屬性的相關信息,包括驗證屬性、SQL 組態屬性和記錄屬性,請參閱 支援的連線屬性。

備註

URL 元素和屬性不區分大小寫。

URL 元素或屬性 說明
<server-hostname> Azure Databricks 計算資源的伺服器主機名值。
<port> Azure Databricks 計算資源的埠值。 預設值是 443。
<schema> 架構的名稱。 或者,設定屬性 ConnSchema 。 請參閱 支援的連線屬性。
httpPath Azure Databricks 計算資源的 HTTP 路徑值。 連接器會將 httpPath 值附加至連線 URL 中指定的主機和埠,以形成要連接的 HTTP 位址。 例如,若要連線到 HTTP 位址 http://localhost:10002/cliservice,您可以使用下列連線 URL:jdbc:databricks://localhost:10002;httpPath=cliservice

若要取得 Azure Databricks 叢集的 JDBC 連線 URL:

  1. 登入您的 Azure Databricks 工作區。
  2. 在側邊欄中,點擊 [計算],然後點擊目標叢集的名稱。
  3. 在 [設定] 索引標籤上,展開 [進階選項]。
  4. 按一下JDBC/ODBC 標籤。
  5. 複製 JDBC URL 作為 JDBC 連線 URL,或從 Server 主機名、埠和 HTTP 路徑 字段中的值建構 URL。

若要取得 Databricks SQL 倉庫的 JDBC 連接 URL:

  1. 登入您的 Azure Databricks 工作區。
  2. 在側邊欄中,點擊SQL 倉儲,然後點擊目標倉儲的名稱。
  3. 單擊 連線詳細資訊 索引標籤。
  4. 複製 JDBC URL 作為 JDBC 連線 URL,或從 Server 主機名、埠和 HTTP 路徑 字段中的值建構 URL。

設定查詢標籤

將鍵值標籤附加於 SQL 查詢,以便追蹤和分析。 標籤會在 system.query.history 表格中出現,以便進行查詢的識別與分析。

若要將查詢標籤新增至連線,請在 JDBC URL 中包含屬性 query_tags :

jdbc:databricks://<server-hostname>:<port>/<schema>;query_tags=key1:value1,key2:value2

查詢標籤使用逗號分隔的索引鍵:值組格式:

  • query_tags=key:value (單標籤)
  • query_tags=key1:value1,key2:value2,key3:value3 (多個標籤)

設定代理連線

設定連接器透過代理伺服器連接,而不是直接連接到 Databricks。 連接器支援透過代理伺服器連接時的基本與 SPNEGO 認證。 請參閱 支援的連線屬性。

要使用系統層級代理設定,請設定 UseProxy=1 和 UseSystemProxy=1。

手動設定代理設定:

  1. 設定 UseProxy=1。
  2. 設定 ProxyHost、 ProxyPort、 ProxyIgnoreList和 。
  3. 要與代理伺服器進行認證,請選擇以下一種方法:
    • 基本:集合 ProxyAuth=1、 ProxyUID和 ProxyPWD。
    • SPNEGO (Kerberos 環境):在系統層級驗證你的 Kerberos 主體,然後設定 ProxyAuth=2。

為 Cloud Fetch 設定代理

Cloud Fetch 需要與主驅動連線分開的代理設定。 使用 UseCFProxy、CFProxyHost、CFProxyPort、CFProxyAuth、CFProxyUID、CFProxyPwd 和連接屬性來將 Cloud Fetch 流量通過代理伺服器。 請參閱 支援的連線屬性。

如果你的網路是私人網路,允許*.blob.core.windows.net*.store.core.windows.net並新增所需的憑證下載和撤銷權限到你的允許清單。

Troubleshooting

如果無法解決代理問題,請設定 EnableQueryResultDownload=0 關閉 Cloud Fetch,並退回直接下載。

要診斷效能問題,請設定 LogLevel=4 以啟用 INFO 層級的記錄。 驅動程式會記錄每區塊的下載速度,因此大型結果集會產生多條日誌行:

CloudFetch download speed: 21.24 MB/s
CloudFetch download speed: 20.60 MB/s

當下載速度低於約 1 MB/s 時,驅動程式會記錄警告。 對數分量為 com.databricks.client.spark.jdbc.ResultFileDownloadHandler。 如果下載緩慢或停滯,可以增加 CloudFetchThreadPoolSize 並行下載更多檔案區塊。

設定 SSL

若要連接到支援 SSL 的 Databricks 工作區,請設定連接器連接到支援 SSL 的插座。 連接器使用單向認證來驗證伺服器身份。

單向驗證需要簽署且受信任的 SSL 憑證。 設定連接器以存取特定的 TrustStore。 如果你沒有指定 TrustStore,連接器會使用預設的 Java TrustStore(jssecacerts),如果沒有 jssecacerts 則使用 cacerts。

若要設定 SSL:

  1. 設定 SSL=1。
  2. 如果你沒有使用預設的 Java TrustStore,請設定一個自訂的:
    • 建立一個包含你簽署且受信任的伺服器憑證的 TrustStore。
    • 設定 SSLTrustStore 為 TrustStore 的完整路徑。
    • 設定 SSLTrustStorePwd 為 TrustStore 密碼。
    • 如果 TrustStore 不是 JKS TrustStore,則設定 SSLTrustStoreType 為 BCFKS (BouncyCastle FIPS Keystore)或 PKCS12。

要更改憑證撤銷策略,請設定以下屬性:

  • CheckCertRevocation: 設定為 0 接受被撤銷的證書。 預設值為 1。
  • AcceptUndeterminedRevocation:設定 1 為接受撤銷狀態不明的憑證(例如當CRLDP無法連通或逾時時)。 預設值為 0。

驗證驅動程式

有關設定 JDBC 驅動程式認證的資訊,請參閱 Databricks JDBC 驅動程式的認證設定。