Databricks JDBC 驱动程序 (OSS)

项目
11/16/2024

重要

此驱动程序目前以公共预览版提供，尚未提供开源版本。

Databricks 提供了一个开源软件 (OSS) JDBC 驱动程序，可用于通过 Java Database Connectivity (JDBC) 将 DataGrip、DBeaver 和 SQL Workbench/J 等工具连接到 Azure Databricks，这是用于访问数据库管理系统的行业标准规范。

此驱动程序已实现 JDBC API，并提供核心功能，包括 OAuth、Cloud Fetch 以及 Unity Catalog 卷引入等功能。它运行本机查询模式并支持本机参数化查询，并且可以使用语句执行 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 存储库中发布。最新版本为 0.9.6-oss。

若要安装驱动程序，可以执行以下任一操作：

对于 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 驱动程序 (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) 身份验证，使用实时人工登录和同意对目标 Azure Databricks 用户帐户进行身份验证。这也称为基于浏览器的 OAuth 身份验证。

Azure Databricks 已为客户了创建 OAuth 客户端 ID databricks-sql-jdbc。这也是 JDBC 驱动程序中使用的默认 OAuth 客户端 ID。若要配置 OAuth U2M 身份验证，只需将以下属性添加到现有的 JDBC 连接 URL 或 java.util.Properties 对象：

属性	Value
`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 对象：

属性	Value
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	服务主体的“应用程序（客户端）ID”值。
`OAuth2Secret`	服务主体的 Azure Databricks OAuth 机密。（OAuth M2M 或 OAuth 2.0 客户端凭据身份验证不支持 Microsoft Entra ID 机密。）

Azure Databricks 个人访问令牌

若要使用 Azure Databricks 个人访问令牌对 JDBC 驱动程序连接进行身份验证，请将以下属性添加到你的 JDBC 连接 URL 或 java.util.Properties 对象：

属性	Value
`AuthMech`	`3`
`user`	值 `token`，字符串形式。
`PWD` 或 `password`	你的 Azure Databricks 个人访问令牌值，字符串形式。

连接属性

JDBC 驱动程序支持以下额外的连接属性。属性不区分大小写。

properties	默认值	说明
`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`，驱动程序将使用代理身份验证用户和密码，由 `ProxyUID` 和 `ProxyPwd` 表示。
`ProxyHost`	`null`	一个字符串，表示当 `UseProxy` 也设置为 `1` 时要使用的代理主机的名称。
`ProxyPort`	`null`	一个整数，表示当 `UseProxy` 也设置为 `1` 时要使用的代理端口的数目。
`ProxyUID`	`null`	一个字符串，表示当 `ProxyAuth` 和 `UseProxy` 也设置为 `1` 时用于代理身份验证的用户名。
`ProxyPwd`	`null`	一个字符串，表示当 `ProxyAuth` 和 `UseProxy` 也设置为 `1` 时用于代理身份验证的密码。
`UseProxy`	`0`	如果设置为 `1`，驱动程序将使用提供的代理设置（例如：`ProxyAuth`、`ProxyHost`、`ProxyPort`、`ProxyPwd`、`ProxyUID`）。
`UseSystemProxy`	`0`	如果设置为 `1`，驱动程序将使用已在系统级别设置的代理设置。如果在连接 URL 中设置了任何其他代理属性，则这些额外的代理属性将替代已在系统级别设置的属性。
`UseCFProxy`	`0`	如果设置为 `1`，则驱动程序将使用云提取代理设置（如果已提供这些设置），否则将使用常规代理。
`CFProxyAuth`	`0`	如果设置为 `1`，驱动程序将使用代理身份验证用户和密码，由 `CFProxyUID` 和 `CFProxyPwd` 表示。
`CFProxyHost`	`null`	一个字符串，表示当 `UseCFProxy` 也设置为 `1` 时要使用的代理主机的名称。
`CFProxyPort`	`null`	一个整数，表示当 `UseCFProxy` 也设置为 `1` 时要使用的代理端口的数目。
`CFProxyUID`	`null`	一个字符串，表示当 `CFProxyAuth` 和 `UseCFProxy` 也设置为 `1` 时用于代理身份验证的用户名。
`CFProxyPwd`	`null`	一个字符串，表示当 `CFProxyAuth` 和 `UseCFProxy` 也设置为 `1` 时用于代理身份验证的密码。
`AsyncExecPollInterval`	`200`	每次轮询异步查询执行状态之间的时间（以毫秒为单位）。异步是指用于对 Spark 执行查询的 RPC 调用是异步的。这并不意味着支持 JDBC 异步操作。
`UserAgentEntry`	`browser`	要包含在 HTTP 请求中的 User-Agent 条目。此值采用以下格式：`[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	JDBC 驱动程序是否应该使用 Thrift 客户端连接到通用群集。默认值适用于 SQL 仓库。

SQL 配置属性

JDBC 驱动程序支持以下 SQL 配置属性。配置参数中也介绍了这些参数。属性不区分大小写。

properties	默认值	说明
`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`	设置本地时区。区域 ID 格式为 `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 驱动程序支持以下日志记录属性。属性不区分大小写。

properties	默认值	说明
`LogLevel`	`OFF`	日志记录级别，值为 0 到 6： - 0：禁用所有日志记录。 - 1：在 FATAL 级别启用日志记录，这会记录导致连接器中止的非常严重的错误事件。 - 2：在 ERROR 级别启用日志记录，这会记录可能仍允许连接器继续运行的错误事件。 - 3：在 WARNING 级别启用日志记录，这会记录在未执行操作时可能导致错误的事件。 - 4：在 INFO 级别启用日志记录，这会记录描述连接器进度的常规信息。 - 5：在 DEBUG 级别启用日志记录，这会记录对调试连接器有用的详细信息。 - 6：在 TRACE 级别启用日志记录，这会记录所有连接器活动。使用此属性在连接器中启用或禁用日志记录，并指定日志文件中包含的详细信息量。
`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 并提供 SLF4J 绑定实现（与 SLF4J 版本 2.0.13 及更高版本兼容）以及类路径中的相应配置文件。
- 对于 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();
        }
    }
}

通过