支持的连接属性

2025-06-13

本文介绍了 Databricks JDBC 驱动程序 (OSS) 支持的连接属性。

身份验证和代理属性

Databricks JDBC 驱动程序（OSS）支持以下身份验证和代理属性。属性不区分大小写。

资产	默认值	DESCRIPTION
`AsyncExecPollInterval`	`200`	每次轮询异步查询执行状态之间的时间(以毫秒为单位)。异步是指用于对 Spark 执行查询的 RPC 调用是异步的。这并不意味着支持 JDBC 异步操作。
`Auth_Flow`	`0`	驱动程序连接的 OAuth2 身份验证流。如果 `AuthMech` 为 `11`，则此属性是必需项。
`Auth_JWT_Key_File`	`null`	用于 JWT 身份验证的私钥文件（PEM 格式）的路径。
`Auth_JWT_Alg`	`RS256`	私钥 JWT 身份验证的算法。支持的算法包括：RSA 算法：RS256、RS384、RS512、PS256、PS384、PS512；以及 EC 算法：ES256、ES384、ES512
`Auth_JWT_Key_Passphrase`	`null`	用于解密加密私钥的密码。
`Auth_KID`	`null`	JWT 身份验证所需的密钥 ID (KID)。使用私钥 JWT 时，此属性为必需项。
`AuthMech`	必选	身份验证机制，其中 `3` 指定机制为 Azure Databricks 个人访问令牌，`11` 则指定机制为 OAuth 2.0 令牌。每个机制都需要额外属性。请参阅对驱动程序进行身份验证。
`CFProxyAuth`	`0`	如果设置为 `1`，驱动程序将使用代理身份验证用户和密码，由 `CFProxyUID` 和 `CFProxyPwd` 表示。
`CFProxyHost`	`null`	一个字符串，表示当 `UseCFProxy` 也设置为 `1` 时要使用的代理主机的名称。
`CFProxyPort`	`null`	一个整数，表示当 `UseCFProxy` 也设置为 `1` 时要使用的代理端口的数目。
`CFProxyUID`	`null`	一个字符串，表示在 `CFProxyAuth` 和 `UseCFProxy` 也设置为 `1` 时用于代理身份验证的用户名。
`CFProxyPwd`	`null`	一个字符串，表示在 `CFProxyAuth` 和 `UseCFProxy` 设置为 `1` 时用于代理身份验证的密码。
`ConnCatalog` 或 `catalog`	`SPARK`	要使用的默认目录的名称。
`ConnSchema` 或 `schema`	`default`	要使用的默认架构的名称。可以通过将 URL 中的 `<schema>` 替换为要使用的架构的名称或将 `ConnSchema` 属性设置为要使用的架构的名称来指定它。
`GoogleServiceAccount`	`null`	使用 Google 服务帐户启用身份验证。
`GoogleCredentialsFile`	`null`	用于 Google 服务帐户身份验证的 JSON 密钥文件的路径。
`EnableOIDCDiscovery`	`1`	如果设置为 `1`，则使用 OpenID Connect 发现 URL。
`OIDCDiscoveryEndpoint`	`null`	用于检索 OIDC 配置的 OpenID Connect 发现 URL。
`Auth_RefreshToken`	`null`	用于获取新的访问令牌的 OAuth2 刷新令牌。
`OAuth2ConnAuthAuthorizeEndpoint`	`null`	OAuth2 流中使用的授权终结点 URL。
`OAuth2ConnAuthTokenEndpoint`	`null`	OAuth2 流的令牌终结点 URL。
`ProxyAuth`	`0`	如果设置为 `1`，驱动程序将使用代理身份验证用户和密码，由 `ProxyUID` 和 `ProxyPwd` 表示。
`ProxyHost`	`null`	一个字符串，表示当 `UseProxy` 也设置为 `1` 时要使用的代理主机的名称。
`ProxyPort`	`null`	一个整数，表示当 `UseProxy` 也设置为 `1` 时要使用的代理端口的数目。
`ProxyPwd`	`null`	一个字符串，表示在 `ProxyAuth` 和 `UseProxy` 设置为 `1` 时用于代理身份验证的密码。
`ProxyUID`	`null`	一个字符串，表示在 `ProxyAuth` 和 `UseProxy` 也设置为 `1` 时用于代理身份验证的用户名。
`UseProxy`	`0`	如果设置为 `1`，驱动程序将使用提供的代理设置（例如：`ProxyAuth`、`ProxyHost`、`ProxyPort`、`ProxyPwd`、`ProxyUID`）。
`UseSystemProxy`	`0`	如果设置为 `1`，驱动程序将使用已在系统级别设置的代理设置。如果在连接 URL 中设置了任何其他代理属性，则这些额外的代理属性将替代已在系统级别设置的属性。
`UseCFProxy`	`0`	如果设置为 `1`，则驱动程序将使用云提取代理设置（如果已提供这些设置），否则将使用常规代理。
`UseJWTAssertion`	`false`	为客户端机密身份验证受限的 M2M 用例启用私钥 JWT 身份验证。

SSL 信任存储配置属性

Databricks JDBC 驱动程序（OSS）支持以下 SSL 信任存储配置属性。属性不区分大小写。

资产	默认值	DESCRIPTION
`AllowSelfSignedCerts`	`0`	如果设置为 `1`，驱动程序允许连接到具有自签名 SSL 证书的服务器。
`CheckCertificateRevocation`	`0`	如果设置为 `1`，驱动程序将检查 SSL 证书是否已吊销。
`SSL`	`1`	连接器是否通过启用 SSL 的套接字与 Spark 服务器通信。
`SSLTrustStore`	`null`	SSL 证书验证的信任存储文件的路径。
`SSLTrustStorePassword`	`null`	信任存储文件的密码（如果受密码保护）。
`SSLTrustStoreType`	`JKS`	信任存储的类型，例如 JKS 或 PKCS12。如果未指定，驱动程序默认使用 JKS 信任存储。有效类型为 `JKS`、 `PKCS12`和 `BCFKS`。
`UseSystemTrustStore`	`0`	如果设置为 `1`，驱动程序将使用系统的默认信任存储进行 SSL 证书验证。

信任存储类型

JDBC 驱动程序支持以下 SSL 模式和信任存储类型。

自签名证书模式

若要使用自签名证书模式，请设置连接属性 AllowSelfSignedCerts=1。此模式使用接受任何证书的全信任套接字工厂。

自定义信任存储

若要使用自定义信任存储，请在 SSLTrustStore 连接属性中指定自定义信任存储文件。此信任存储直接从指定的路径加载，并使用证书进行 SSL 证书验证。它可以在 JKS、PKCS12 或其他受支持的格式中。

必须指定以下附加连接属性：

SSLTrustStore：信任存储文件的路径
SSLTrustStorePassword：信任库的密码（如果需要）
SSLTrustStoreType：信任存储的类型（可选，如果未指定，则默认为 JKS）

Java 系统属性信任存储

若要使用系统属性信任存储，请设置 UseSystemTrustStore=1 并确保未指定自定义信任存储。而是使用 Java 系统属性 javax.net.ssl.trustStore指定信任存储。此属性使用 -D 标志在 JVM 级别设置，例如：

java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...

JDBC 驱动程序首先检查 Java 系统属性 javax.net.ssl.trustStore。如果已设置，则它使用此信任存储文件而不是 JDK 的默认值。如果未设置系统属性，将使用 JDK 的默认信任存储（cacerts），该存储位于 $JAVA_HOME/lib/security/cacerts 或类似路径。

JDK 默认信任存储（cacerts）

JDK 附带一个名为 cacert 的 内置信任存储，其中包含来自已知证书颁发机构的证书，允许验证这些 CA 颁发的证书。此信任存储通常位于$JAVA_HOME/lib/security/cacerts，默认密码为“changeit”或“changeme”。

若要使用 JDK 默认信任存储，请设置 UseSystemTrustStore=1 并确保未指定自定义信任存储或 Java 系统属性信任存储。如果还使用 Java 系统属性 javax.net.ssl.trustStore指定了信任存储，则会将其忽略，这可确保驱动程序仅使用默认 JDK 信任存储中的证书。

信任存储的优先顺序

驱动程序使用以下优先级顺序来确定要使用的信任存储：

在连接属性中指定的 SSLTrustStore 自定义信任库
Java 系统属性 javax.net.ssl.trustStore 中指定的信任存储（UseSystemTrustStore=1 时）
JDK 的默认信任库（cacerts）

安全建议

为了保护连接安全，Databricks 建议执行以下作：

对于生产环境：
- 请勿使用自签名证书模式（AllowSelfSignedCerts=1）。
- 使用官方 CA 签名证书。
- 请使用UseSystemTrustStore=1，除非您需要自定义信任存储。
对于自定义信任证书库：
- 在连接到证书不在默认信任存储中的服务器时使用。
- 确保信任存储包含完整的证书链。
- 使用适当的权限保护信任存储文件。

SQL 配置属性

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

资产	默认值	DESCRIPTION
`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` 的时区 ID，例如 America/Los_Angeles，或者格式为 (+\|-) HH、(+\|-) HH:mm 或 (+\|-) HH:mm:ss 的时区偏移量，例如 -08、+01:00 或 -13:33:33。此外，支持使用 `UTC` 作为 +00:00 的别名
`use_cached_result`	`true`	Databricks SQL 是否缓存并尽可能重复使用结果。

日志记录属性

Databricks JDBC 驱动程序 (OSS) 支持以下日志记录属性。属性不区分大小写。

资产	默认值	DESCRIPTION
`LogLevel`	`OFF`	日志记录级别，值为 0 到 6： 0：禁用所有日志记录。 1：启用 FATAL 级别的日志记录，将记录导致连接器中止的非常严重的错误事件。 2：在 ERROR 级别启用日志记录，这会记录可能仍允许连接器继续运行的错误事件。 3：在 WARNING 级别启用日志记录，这会记录如果未执行操作可能导致错误的事件。 4：在 INFO 级别启用日志记录，这会记录描述连接器进度的常规信息。 5：在 DEBUG 级别启用日志记录，这会记录对调试连接器有用的详细信息。 6：在跟踪级别启用日志记录，将记录所有连接器活动。使用此属性在连接器中启用或禁用日志记录，并指定日志文件中包含的详细信息量。
`LogPath`	为确定日志的默认路径，驱动程序按以下优先级顺序使用为这些系统属性设置的值： `user.dir` `java.io.tmpdir` 当前目录，即 `.`	启用日志记录时连接器保存日志文件的文件夹的完整路径，字符串格式。若要确保连接 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 应用程序并重新连接到服务器以应用这些设置。

其他功能属性

以下属性可在 Databricks JDBC 驱动程序 (OSS) 中启用相关功能。属性不区分大小写。

资产	默认值	DESCRIPTION
`EnableComplexDatatypeSupport`	`0`	如果设置为 `1`，则启用对复杂数据类型（数组、结构体、映射）的支持，使其作为原生 Java 对象而非字符串。
`EnableTelemetry`	`0`	如果设置为 `1`，则会启用遥测功能。请参阅遥测。
`UserAgentEntry`	`browser`	要包含在 HTTP 请求中的 User-Agent 条目。此值采用以下格式：`[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`1`	JDBC 驱动程序应使用 Thrift 客户端还是语句执行 API。
`VolumeOperationAllowedLocalPaths`	``	用于下载和上传 UC 卷引入文件的允许的本地路径的逗号分隔列表。这些路径也包括子目录。请参阅通过卷来管理文件。
`VolumeOperationRetryableHttpCode`	`408,502,503,504`	用于 Unity Catalog 卷引入的可重试 HTTP 代码的逗号分隔列表。
`VolumeOperationRetryTimeout`	`15`	Unity Catalog 卷引入 HTTP 请求的重试超时（以分钟为单位）。

遥测收集

遥测功能使 Databricks 能够通过收集以下信息来简化调试并及时进行故障排除：

客户端环境详细信息（驱动程序版本、运行时、操作系统详细信息）
JDBC 连接配置（不包括任何 PII 数据）
操作延迟测量
执行结果格式（内联 JSON、Arrow 等）
操作类型（执行查询、元数据查询、卷操作）
错误分类数据
重试次数

注释

Databricks 严格遵守隐私标准，确保不会收集查询内容、结果或个人身份信息 (PII)。

通过