使用 Databricks JDBC 驱动程序配置与 Databricks 的连接

本页演示如何使用 Databricks JDBC 驱动程序版本 3 及更高版本配置与 Databricks 的连接。

配置连接

若要使用 JDBC 驱动程序连接到Azure Databricks工作区，需要指定连接设置，包括工作区的服务器主机名、计算资源设置和身份验证凭据。

注释

JDBC 驱动程序不支持连接到作业计算环境。

在 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 元素或属性	DESCRIPTION
`<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。

配置查询标记

将键值标记附加到 SQL 查询以进行跟踪和分析。标记显示在 system.query.history 表中用于查询标识和分析。

若要将查询标记添加到连接，请在 query_tags JDBC URL 中包含该属性：

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。

手动配置代理设置：

设置 UseProxy=1。
设置ProxyHost、ProxyPort和ProxyIgnoreList。
若要使用代理服务器进行身份验证，请选择一种方法：
- 基本：设置 ProxyAuth=1、ProxyUID 和 ProxyPWD。
- SPNEGO （Kerberos 环境）：在系统级别对 Kerberos 主体进行身份验证，然后设置 ProxyAuth=2。

为 Cloud Fetch 配置代理

Cloud Fetch 需要独立于主驱动程序连接的代理配置。使用 UseCFProxy、CFProxyHost、CFProxyPort、CFProxyAuth、CFProxyUID 和 CFProxyPwd 连接属性，通过代理服务器路由 Cloud Fetch 流量。请参阅支持的连接属性。

如果网络是专用的，则允许 *.blob.core.chinacloudapi.cn 和 *.store.core.chinacloudapi.cn，并将所需的证书下载和吊销添加到允许列表。

故障排除

如果无法解决代理问题，请设置为 EnableQueryResultDownload=0 禁用 Cloud Fetch 并回退到直接下载。

若要诊断性能问题，请将 LogLevel=4 设置为启用 INFO 级别的日志记录。驱动程序记录每个区块的下载速度，因此大型结果集生成多个日志行：

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

当下载速度低于大约 1 MB/秒时，驱动程序会记录警告。日志组件为 com.databricks.client.spark.jdbc.ResultFileDownloadHandler. 如果下载速度缓慢或已停止，请增加 CloudFetchThreadPoolSize 以并行下载更多文件区块。

配置 SSL

如果要连接到启用了 SSL 的 Databricks 工作区，请将连接器配置为连接到已启用 SSL 的套接字。连接器使用单向身份验证来验证服务器的标识。

单向身份验证需要签名的受信任 SSL 证书。配置连接器以访问特定的 TrustStore。如果未指定 TrustStore，连接器将使用默认Java TrustStore（jssecacerts），或者如果 jssecacerts 不可用，则使用 cacerts。

配置 SSL：

设置 SSL=1。
如果未使用默认 Java 信任库，请配置自定义信任库：
- 创建包含已签名的受信任服务器证书的 TrustStore。
- 将 SSLTrustStore 设置为 TrustStore 的完整路径。
- 请将 SSLTrustStorePwd 设置为 TrustStore 密码。
- 如果 TrustStore 不是 JKS TrustStore，则将其设置为 SSLTrustStoreType (BouncyCastle FIPS 密钥存储) 或 BCFKS。

若要更改证书吊销策略，请设置以下属性：

CheckCertRevocation：设置为 0 接受已吊销的证书。默认值为 1。
AcceptUndeterminedRevocation：将其设置为 1 以接受撤销状态不确定的证书（例如，当 CRLDP 无法访问或超时时）。默认值为 0。

对驱动程序进行身份验证

有关为 JDBC 驱动程序配置身份验证的信息，请参阅 Databricks JDBC 驱动程序的身份验证设置。

上次更新时间为 2026-10-23