Databricks JDBC 驅動程式 (OSS)

文章
09/25/2024

重要

此驅動程式處於公開預覽狀態，但尚未作爲開放原始碼提供。

Databricks 提供開放原始碼軟體 (OSS) JDBC 驅動程式，可讓您透過 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 測試。

安裝驅動程式

Databricks JDBC 驅動程式 (OSS) 發佈在 Maven 存放庫中。最新版本為 0.9.1-oss。

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

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

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

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

若要檢視其他專案類型的相依性語法，並取得 Databricks JDBC 驅動程式 (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，或從 [伺服器主機名稱]、[連接埠] 和 [HTTP 路徑] 欄位中的值建構 URL。

若要取得 Databricks SQL 倉儲的 JDBC 連線 URL：

登入至您的 Azure Databricks 工作區。
在側邊欄中，按一下 [SQL 倉儲]，然後按一下目標倉儲的名稱。
按一下 [連線詳細資料] 索引標籤。
複製 JDBC URL 以作為 JDBC 連線 URL，或從 [伺服器主機名稱]、[連接埠] 和 [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 (OAuth M2M) 透過服務主體對 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 M2M 驗證的存取權杖。
為服務主體提供叢集或倉儲的存取權。請參閱計算權限或管理 SQL 倉儲。

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

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

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_photo`	`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`	`4`	記錄層級，值為 0 到 6： - 0：停用所有記錄。 - 1：在「嚴重」層級啟用記錄，即記錄會導致連接器中止的嚴重錯誤事件。 - 2：在「錯誤」層級啟用記錄，即記錄可能仍允許連接器繼續執行的錯誤事件。 - 3：在「警告」層級啟用記錄，即記錄未採取動作時可能導致錯誤的事件。 - 4：在「資訊」層級啟用記錄，即記錄描述連接器進度的一般資訊。 - 5：在「偵錯」層級啟用記錄，即記錄對連接器進行偵錯時很有用的詳細資訊。 - 6：在「追蹤」層級啟用記錄，即記錄所有連接器活動。使用此屬性來啟用或停用連接器中的記錄，並指定記錄檔中包含的詳細資料量。
`LogPath`	`logs/application.log`	啟用記錄時連接器用來儲存記錄檔的資料夾的完整路徑 (字串形式)。如果 `LogPath` 值無效，則連接器會將記錄的資訊傳送至標準輸出資料流 (System.out)。

範例：使用 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();
        }
    }
}

分享方式：