Databricks JDBC 驅動程式 (OSS)

發行項
01/21/2025

重要

此驅動程式位於公開預覽版中，且會在正式推出時以開放原始碼的形式提供。

Databricks JDBC （OSS）是最新版本的驅動程式，可讓您透過 Java 資料庫連線能力（JDBC）將 DataGrip、DBeaver、SQL Workbench/J 連線至 Azure Databricks 等工具，這是存取資料庫管理系統的業界標準規格。

此驅動程式已實作 JDBC API，並提供核心功能，包括 OAuth、雲端擷取，以及 Unity 目錄磁碟區擷取等功能。它執行原生查詢模式，支援原生參數化查詢，並且可以使用陳述式執行 API (提供有用的查詢結果保留功能) 或 Thrift 來執行。

本文提供安裝和使用 Databricks JDBC 驅動程式 (OSS) 的相關資訊。如需非 OSS Databricks JDBC 驅動程式的相關資訊，請參閱 Databricks JDBC 驅動程式。

需求

若要使用 Databricks JDBC 驅動程式 (OSS)，必須符合下列需求：

Java Runtime Environment (JRE) 11.0 或更新版本。 JRE 11、17 和 21 支援 CI 測試。

注意

由於 JDK 16 發生與 JDBC 驅動程式所使用之 Apache Arrow 連結庫相容性問題的變更，使用 JDBC 驅動程式與 JDK 16 或更新版本時，可能會發生運行時錯誤。若要避免這些錯誤，請使用下列 JVM 命令選項重新啟動您的應用程式或驅動程式：

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

安裝驅動程式

Databricks JDBC 驅動程式 (OSS) 發佈在 Maven 存放庫中。

若要安裝驅動程式，您可以執行下列任何操作：

針對 Maven 專案，將下列相依性新增至專案的 pom.xml 檔案，以指示 Maven 自動下載指定版本的 JDBC 驅動程式：

<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>

針對 Gradle 專案，將下列相依性新增至專案的組建檔案，以指示 Gradle 自動下載指定版本的 JDBC 驅動程式：
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

若要檢視其他項目類型的相依性語法，以及取得 Databricks JDBC Driver （OSS）的最新版本號碼，請參閱 Maven 存放庫。

設定連線 URL

若要使用 JDBC 驅動程式連線到 Azure Databricks 工作區，您必須指定 JDBC 連線 URL，其中包含各種連線設定，例如 Azure Databricks 工作區的伺服器主機名、計算資源設定，以及連線到工作區的驗證認證。

您可以在 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 元素。如需其他屬性的相關資訊，包括驗證屬性，請參閱以下各節。 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：

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

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

登入至您的 Azure Databricks 工作區。
在側邊欄中，按一下 [SQL 倉儲]，然後按一下目標倉儲的名稱。
按一下 [連線詳細資料] 索引標籤。
複製 JDBC URL 作為 JDBC 連線 URL，或從 Server 主機名、埠和 HTTP 路徑 字段中的值建構 URL。

驗證驅動程式

您可以使用下列其中一種驗證機制來驗證 JDBC 驅動程式的連線：

OAuth 使用者對機器 (U2M) 驗證 (建議)
OAuth 機器對機器 (M2M) 驗證
Azure Databricks 個人存取權杖

OAuth 使用者對機器 (U2M) 驗證

JDBC 驅動程式支援 OAuth 使用者對機器 (U2M) 驗證，以便使用者即時登入並同意驗證目標 Databricks 使用者帳戶。這也稱為瀏覽器型 OAuth 驗證。

Azure Databricks 已為客戶建立 OAuth 用戶端識別碼 databricks-sql-jdbc。這也是 JDBC 驅動程式中使用的預設 OAuth 用戶端識別碼。若要設定 OAuth U2M 驗證，只需將下列屬性新增至現有的 JDBC 連線 URL 或 java.util.Properties 物件：

屬性	值
`AuthMech`	`11`
`Auth_Flow`	`2`

OAuth 機器對機器 (M2M) 驗證

JDBC 驅動程式支援使用 Azure Databricks 服務主體進行 OAuth 機器對機器 (M2M) 驗證。這也稱為 OAuth 2.0 客戶端認證 驗證。請參閱，使用 OAuth，以服務主體授權 Azure Databricks 資源的無人值守存取權。

若要設定 OAuth M2M 或 OAuth 2.0 用戶端認證驗證：

建立 Microsoft Entra ID 受控服務主體，然後將其指派給 Azure Databricks 帳戶和工作區。如需詳細資訊，請參閱管理服務主體。

重要

Databricks JDBC 驅動程式（OSS）支援適用於 OAuth M2M 或 OAuth 2.0 用戶端認證驗證的 Azure Databricks OAuth 秘密。不支援 Microsoft Entra ID 秘密。
建立服務主體的 Azure Databricks OAuth 秘密。若要這樣做，請參閱手動產生和使用 OAuth 服務主體驗證的存取權杖。
為服務主體提供叢集或倉儲的存取權。請參閱計算權限或管理 SQL 倉儲。

將下列屬性新增至現有的 JDBC 連線 URL 或 java.util.Properties 物件：

屬性	值
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	服務主體的應用程式 (用戶端) 識別碼值。
`OAuth2Secret`	服務主體的 Azure Databricks OAuth 秘密。 Microsoft Entra ID 秘密不支援 OAuth M2M 或 OAuth 2.0 用戶端憑證驗證。

Azure Databricks 個人存取權杖

若要使用 Azure Databricks 個人存取權杖驗證 JDBC 驅動程式的連線，請將下列屬性新增至您的 JDBC 連線 URL 或 java.util.Properties 物件：

屬性	值
`AuthMech`	`3`
`user`	值 `token`，以字串表示。
`PWD` 或 `password`	您的 Azure Databricks 個人存取權杖值，以字串表示。

連線內容

JDBC 驅動程式支援以下其他連線屬性。這些屬性都不區分大小寫。

屬性	預設值	描述
`AuthMech`	必要	驗證機制，其中 `3` 指定機制是 Azure Databricks 個人存取令牌，`11` 指定機制為 OAuth 2.0 令牌。每種機制都需要其他屬性。請參閱驗證驅動程式。
`Auth_Flow`	`0`	驅動程式連線的 OAuth2 驗證流程。如果 `AuthMech` 為 `11`，則此屬性是必要項。
`SSL`	`1`	連接器是否透過啟用 SSL 的通訊端與 Spark 伺服器通訊。
`ConnCatalog` 或 `catalog`	`SPARK`	要使用的預設目錄名稱。
`ConnSchema` 或 `schema`	`default`	要使用的預設架構名稱。您可以藉由將 URL 中的 `<schema>` 取代為要使用的架構名稱，或將 `ConnSchema` 屬性設定為要使用的架構名稱來指定。
`ProxyAuth`	`0`	如果設定為 `1`，驅動程式會使用 proxy 驗證使用者和密碼，由 `ProxyUID` 和 `ProxyPwd`表示。
`ProxyHost`	`null`	字串，表示當 `UseProxy` 也設定為 `1`時要使用的 Proxy 主機名稱。
`ProxyPort`	`null`	整數，表示當 `UseProxy` 也設定為 `1`時要使用的 Proxy 埠數目。
`ProxyUID`	`null`	字串，表示當 `ProxyAuth` 和 `UseProxy` 也設定為 `1`時，要用於 Proxy 驗證的用戶名稱。
`ProxyPwd`	`null`	字串，表示當 `ProxyAuth` 和 `UseProxy` 也設定為 `1`時，要用於 Proxy 驗證的密碼。
`UseProxy`	`0`	如果設定為 `1`，驅動程式會使用提供的 Proxy 設定（例如：`ProxyAuth`、`ProxyHost`、`ProxyPort`、`ProxyPwd`和 `ProxyUID`）。
`UseSystemProxy`	`0`	如果設定為 `1`，驅動程式會使用已在系統層級設定的 Proxy 設定。如果在連線 URL 中設定任何其他 Proxy 屬性，這些額外的 Proxy 屬性會覆寫已在系統層級設定的屬性。
`UseCFProxy`	`0`	如果設定為 `1`，則驅動程式會在提供時使用雲端擷取 Proxy 設定，否則請使用一般 Proxy。
`CFProxyAuth`	`0`	如果設定為 `1`，驅動程式會使用 proxy 驗證使用者和密碼，由 `CFProxyUID` 和 `CFProxyPwd`表示。
`CFProxyHost`	`null`	字串，表示當 `UseCFProxy` 也設定為 `1`時要使用的 Proxy 主機名稱。
`CFProxyPort`	`null`	整數，表示當 `UseCFProxy` 也設定為 `1`時要使用的 Proxy 埠數目。
`CFProxyUID`	`null`	字串，表示當 `CFProxyAuth` 和 `UseCFProxy` 也設定為 `1`時，要用於 Proxy 驗證的用戶名稱。
`CFProxyPwd`	`null`	字串，表示當 `CFProxyAuth` 和 `UseCFProxy` 也設定為 `1`時，要用於 Proxy 驗證的密碼。
`AsyncExecPollInterval`	`200`	每次輪詢非同步查詢執行狀態之間的時間，以毫秒為單位。非同步是指用來對 Spark 執行查詢的 RPC 呼叫是非同步的。這並不表示支援 JDBC 非同步作業。
`UserAgentEntry`	`browser`	要包含在 HTTP 要求中的使用者代理程式項目。此值的格式如下：`[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	JDBC 驅動程式是否應使用 Thrift 用戶端來連線到全用途叢集。預設值適用於 SQL 倉儲。

SQL 設定屬性

JDBC 驅動程式支援以下 SQL 設定屬性。這些也會在配置參數中說明。這些屬性都不區分大小寫。

屬性	預設值	描述
`ansi_mode`	`TRUE`	是否要針對特定函式和轉換規則啟用嚴格的 ANSI SQL 行為。
`enable_photon`	`TRUE`	是否要啟用 Photon 向量化查詢引擎。
`legacy_time_parser_policy`	`EXCEPTION`	用來剖析和格式化日期和時間戳記的方法。有效值為 `EXCEPTION`、`LEGACY`和 `CORRECTED`。
`max_file_partition_bytes`	`128m`	從檔案型來源讀取時，要裝入單一分割區的最大位元組數。此設定可以是任何正整數，或者包含量值，例如 `b` (位元組)、`k` 或 `kb` (1024 個位元組)。
`read_only_external_metastore`	`false`	控制外部中繼存放區是否被視為唯讀屬性。
`statement_timeout`	`172800`	設定介於 0 到 172800 秒之間的 SQL 陳述式逾時。
`timezone`	`UTC`	設定當地時區。格式為 `area/city` 的區域識別碼，例如 America/Los_Angeles，或採用以下格式的時區位移：(+\|-)HH、(+\|-)HH:mm 或 (+\|-)HH:mm:ss，例如 -08、+01:00 或 -13:33:33。此外，也支援 `UTC` 作為 +00:00 的別名
`use_cached_result`	`true`	Databricks SQL 是否盡可能快取並重複使用結果。

記錄屬性

JDBC 驅動程式支援下列記錄屬性。這些屬性都不區分大小寫。

屬性	預設值	描述
`LogLevel`	`OFF`	記錄層級，值為 0 到 6： - 0：停用所有記錄。 - 1：在「嚴重」層級啟用記錄，即記錄會導致連接器中止的嚴重錯誤事件。 - 2：在「錯誤」層級啟用記錄，即記錄可能仍允許連接器繼續執行的錯誤事件。 - 3：在「警告」層級啟用記錄，即記錄未採取動作時可能導致錯誤的事件。 - 4：在「資訊」層級啟用記錄，即記錄描述連接器進度的一般資訊。 - 5：在「偵錯」層級啟用記錄，即記錄對連接器進行偵錯時很有用的詳細資訊。 - 6：在「追蹤」層級啟用記錄，即記錄所有連接器活動。使用此屬性來啟用或停用連接器中的記錄，並指定記錄檔中包含的詳細資料量。
`LogPath`	若要判斷記錄的預設路徑，驅動程式會以下列優先順序使用這些系統屬性所設定的值： 1. `user.dir` 2. `java.io.tmpdir` 3. 目前目錄，換句話說 `.`	連接器在啟用記錄時將記錄檔儲存為字串的資料夾完整路徑。若要確保連線 URL 與所有 JDBC 應用程式相容，請輸入另一個反斜杠，以逸出檔案路徑中的反斜杠（`\`）。 `LogPath`如果值無效，連接器會將記錄的資訊傳送至標準輸出數據流（System.out）。
`LogFileSize`	無最大值	以 MB 指定的允許記錄檔大小上限
`LogFileCount`	無最大值	允許的記錄檔數目上限

啟用和設定記錄

JDBC 驅動程式支援適用於 Java 的簡單記錄外觀（SLF4J）和 java.util.logging （JUL）架構。驅動程式預設會使用 JUL 記錄架構。

若要啟用及設定 JDBC 驅動程式的記錄：

開啟您想要使用的記錄架構：
- 針對 SLF4J 日誌記錄，請設定系統屬性 -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER，並在 classpath 中提供與 SLF4J 2.0.13 版及更新版本相容的 SLF4J 綁定實作和對應的配置檔案。
- 對於 JUL 記錄，請將系統屬性設為 -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER。這是預設值。
將連接字串上的 LogLevel 屬性設定為要包含在記錄檔中所需的資訊層級。
將連接字串上的 LogPath 屬性設定為您要儲存記錄檔之資料夾的完整路徑。

例如，下列連線 URL 會啟用記錄層級 6，並將記錄檔儲存至 C：temp 資料夾：
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
重新啟動您的 JDBC 應用程式，然後重新連線到伺服器以套用設定。

範例：使用 JDBC 驅動程式執行查詢

下列範例示範如何使用 JDBC 驅動程式，透過 Azure Databricks 計算資源執行 Databricks SQL 查詢。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

共用方式為