JDBC 驱动程序连接参数参考¶

描述:

指定连接的用户登录名。

描述:

指定是否允许在账户名中使用下划线。JDBC 驱动程序不支持在 URLs 中（其中包含账户名）使用下划线，因为 JDBC 驱动程序会自动将下划线转换为连字符。默认值为 false。

备注

从版本 3.13.25 开始，Snowflake JDBC 驱动程序会将 allowUnderscoresInHost 参数的默认值更改为 false。此更改影响账户名包含下划线的 PrivateLink 客户。在这种情况下，必须通过将 allowUnderscoresInHost 设置为 true 来替换默认值。

描述:

指定用于验证用户登录凭据的身份验证器。您可以将此设置为以下某个值：

• snowflake，以使用内部 Snowflake 身份验证器。

• externalbrowser，使用您的 Web 浏览器 与 Okta、AD FS 或已为账户定义的其他兼容 SAML 2.0 的身份提供商 (IdP) 进行身份验证。

• :code:` https:/ (https:/)/<okta_account_name>.okta.com ` （即 Okta 账户的 URL 端点），:ref:` 通过原生 Okta 进行身份验证 <label-native-sso-okta>` （仅当 IdP 是 Okta 时才受支持）。

• oauth，使用 OAuth 进行身份验证。如果将 OAuth 指定为身份验证器，则还必须设置 token 参数来指定 OAuth 令牌（参阅下文）。

• snowflake_jwt，以使用密钥对身份验证进行身份验证。有关密钥对身份验证的更多详细信息，请参阅 使用密钥对身份验证和密钥轮换。

• username_password_mfa，使用 MFA 令牌缓存进行身份验证。有关更多详细信息，请参阅 使用多重身份验证

• oauth_authorization_code 通过 Web 浏览器和选定的身份提供商（包括作为 IdP 的 Snowflake）使用 OAuth 授权码手动进行身份验证。有关更多信息，请参阅 使用 OAuth 2.0 授权码流程。

• oauth_client_credentials 通过选定的身份提供商，使用 OAuth 客户端凭据自动进行身份验证（作为 IdP 的 Snowflake 不支持客户端凭据流程）。有关更多信息，请参阅 使用 OAuth 2.0 客户端凭据流程。

• programmatic_access_token 用于通过编程访问令牌 (PAT) 进行身份验证。有关更多信息，请参阅 使用编程访问令牌 (PAT) 进行身份验证。

• WORKLOAD_IDENTITY to authenticate with the workload identity federation (WIF) authenticator.

如果连接字符串指定了密钥对，则即使 authenticator 参数未设置或设置为“snowflake”，也将使用密钥对身份验证。

有关身份验证的更多信息，请参阅 管理/使用联合身份验证 和 客户端、驱动程序和连接器。

默认值:

snowflake

描述:

指定使用 GCP (Google Cloud Platform) 时是否使用默认凭据查询来取代外部应用程序默认凭据。

默认情况下，GCP 用户可使用多种选项在 Snowflake 以外设置 Google 应用程序默认凭据。有时，这些身份验证方法可能会干扰源自 Snowflake JDBC 驱动程序的云存储操作。在这种情况下，您可以将该值设置为 true，以强制驱动程序忽略其他来源的 GCP 凭据。

您也可以使用 net.snowflake.jdbc.disableGcsDefaultCredentials Java 属性来达到相同的效果。

默认值:

true

描述:

指定是否禁用 SAML 响应的验证检查。

默认值:

false

描述:

指定用于多重身份验证的密码。

有关多重身份验证的更多信息，请参阅 MFA（多重身份验证）。

描述:

指定了是否将多重身份验证的密码追加到密码中：

• on （或 true）表示追加密码。

• off`（或 :code:`false）或任何其他值表示不追加密码。

默认值:

off

描述:

指定指定用户的密码。

指定密码有以下两种方法：

• 第一种方法是直接将用户 ID 和密码传递给 getConnection 方法：

  String user = "<user>";          // replace "<user>" with your user name
  String password = "<password>";  // replace "<password>" with your password
  Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.cn/", user, password);
  

  Copy

• 第二种方法是创建一个 Properties 对象，用密码更新该对象，并将对象传递给 getConnection 方法：

  String user = "<user>";          // replace "<user>" with your user name
  String password = "<password>";  // replace "<password>" with your password
  Properties props = new Properties();
  props.put("user", user);
  props.put("password", password);
  Connection con = DriverManager.getConnection("jdbc:snowflake://<account>.snowflakecomputing.cn/", props);
  

  Copy

注意

我们强烈建议您 不要 在 JDBC 连接字符串中直接包含用户密码，因为使用该字符串连接到 Snowflake 的客户端应用程序可能会无意中暴露该密码。相反，请使用应用程序提供的接口来指定用户密码。

描述:

指定指定用户的私钥。请参阅 使用密钥对身份验证和密钥轮换。

描述:

为指定用户指定 base64 编码私钥。请参阅 使用密钥对身份验证和密钥轮换。

描述:

指定指定用户的私钥文件的路径。请参阅 使用密钥对身份验证和密钥轮换。

描述:

（已弃用）请改用 private_key_pwd。

描述:

指定用于解密指定用户的私钥文件或 base64 编码私钥的密码。请参阅 使用密钥对身份验证和密钥轮换。

描述:

指定要用于身份验证的 OAuth 令牌，其中 <string> 为令牌。此参数仅在将 authenticator 参数设置为 oauth 时才是必需的，但下文所述情况除外。

备注

从版本 3.13.24 开始，Snowflake JDBC 驱动程序允许您在连接密码中发送 OAuth 令牌，并将其包含在 token 配置参数中。如果未指定 token 配置参数，则 Driver.connect() 方法会将令牌存储在连接密码中。

此功能主要支持在连接池中使用 OAuth 身份验证，允许您根据需要传递刷新的令牌，而不是受 token 配置参数中指定的过期令牌的限制。

例如，您可以在 getConnection() 方法属性中传递令牌作为密码，而不是设置 token 配置参数，类似于以下内容：

Properties props = new Properties();
props.put("user", "myusername");
props.put("authenticator", "oauth");
props.put("role", "myrole");
props.put("password", "xxxxxxxxxxxxx"); // where xxxxxxxxxxxxx is the token string
Connection myconnection = DriverManager.getConnection(url, props);

Copy

默认值:

无

描述:

身份提供商为 Snowflake 集成提供的 client id 的值（Snowflake 安全集成元数据）。

描述:

身份提供商为 Snowflake 集成提供的 client secret 的值（Snowflake 安全集成元数据）。

描述:

向驱动程序提供授权码的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。

描述:

向驱动程序提供访问令牌的身份提供商端点。当使用 Snowflake 作为身份提供商时，此值源自 server 或 account 参数。

描述:

身份提供商授权请求中请求的范围。默认情况下，它源自角色。当需要多个作用域时，该值应为以空格分隔的多个作用域列表。

描述:

URI to use for authorization code redirection (Snowflake security integration metadata). Default: http://127.0.0.1:{randomAvailablePort}.

描述:

Platform of the workload identity provider. Possible values include: AWS, AZURE, GCP, and OIDC.

描述:

String containing a list of identities separated with commas that provide an identity chain to use when connecting to Snowflake. Elements are either a full service account address or a service account's unique ID.

Impersonation works by following each entry in order to obtain a token that allows authorization of the next service account. Each account in the identity chain needs permissions to impersonate the next account only. The final account in the list obtains your Snowflake connection token and uses it to connect to Snowflake.

描述:

指定连接后要使用的默认数据库，或指定空字符串。指定的数据库应该是指定的默认角色对其具有权限的现有数据库。

如果连接后需要使用其他数据库，请执行 USE DATABASE 命令。

描述:

指定要在驱动程序启动的 Snowflake 会话中使用的默认访问控制角色。指定的角色应是已为驱动程序指定用户分配的现有角色。如果指定的角色尚未分配给用户，则在驱动程序启动会话时不会使用该角色。

如果连接后需要使用其他角色，请执行 USE ROLE 命令。

有关角色和访问控制的更多信息，请参阅 访问控制概述。

描述:

指定连接后用于指定数据库的默认架构，或指定空字符串。指定的架构应是指定的默认角色对其具有权限的现有架构。

如果连接后需要使用其他架构，请执行 USE SCHEMA 命令。

描述:

指定连接后要使用的虚拟仓库，或指定空字符串。指定的仓库应是指定的默认角色对其具有权限的现有仓库。

如果连接后需要使用其他仓库，可执行 USE WAREHOUSE 命令为会话设置不同的仓库。

描述:

指定驱动程序是否应忽略在 Java 系统选项中指定的 SOCKS 代理配置：

• on （或 true）指定忽略代理。

• off （或 false）或指定使用代理的任何其他值。

备注

设置此连接参数会改变同一 JVM （Java 虚拟机）上所有 连接 的行为。

默认值:

off

描述:

指定驱动程序应绕过代理服务器直接连接的主机列表。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

描述:

指定要使用的代理服务器的主机名。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

描述:

指定用于对代理服务器进行身份验证的密码。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

描述:

指定要使用的代理服务器的端口号。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

描述:

指定用于连接代理服务器的协议。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

默认值:

http

描述:

指定用于向代理服务器进行身份验证的用户名。有关详细信息，请参阅 在 JDBC 连接字符串中指定代理服务器。

描述:

指定驱动程序是否应使用代理：

• on （或 true）指定驱动程序应使用代理。

• off （或 false）或任何其他值指定驱动程序不应使用代理。如果存在 JVM 代理实参，则此设置无效。

请参阅 在 JDBC 连接字符串中指定代理服务器。

默认值:

off

描述:

指定连接到 Snowflake 服务时，返回登录失败错误之前等待响应的秒数。

默认值:

60

描述:

指定与 Snowflake 服务交互时，返回错误之前等待响应的毫秒数。0 （零）指定不设置网络超时。

默认值:

0

描述:

指定等待与远程主机完全建立新连接（包括 TLS 协商）的最长时间，以毫秒为单位。

您还可以使用 ${HTTP_CLIENT_CONNECTION_TIMEOUT} 在连接字符串中设置此项。

默认值:

:code:`60000`（1 分钟）

描述:

指定成功建立连接后等待数据的最长时间（在两个数据包之间处于非活动状态的时间），以毫秒为单位。

您还可以使用 ${HTTP_CLIENT_SOCKET_TIMEOUT} 在连接字符串中设置此项。

默认值:

300000 （5 分钟）

描述:

指定在返回错误之前等待查询完成的秒数。0 （零）指定驱动程序应无限期等待。

默认值:

0

描述:

How to treat certificate revocation. Note that certificate revocation checks with CRLs are resource-heavy tasks, both for memory and CPU. The following values are supported:

• ENABLED: Enables CRLs. Connections are terminated if there are errors related to obtaining and parsing the CRL.

• ADVISORY: Enables CRLs. Errors are logged but do not block the connection; revocation status is not enforced.

• DISABLED: Disables CRLs. Certificates can only be revoked manually.

默认值:

DISABLED

描述:

Whether certificates without an associated CRL are accepted. If false, certificates lacking a CRL distribution point cause the connection to fail. Applies only when CERT_REVOCATION_CHECK_MODE is not DISABLED.

默认值:

false

描述:

Whether to enable in-memory caching of CRLs. If enabled, the driver caches CRLs in memory to improve performance. Applies only when CERT_REVOCATION_CHECK_MODE is not DISABLED.

默认值:

true

描述:

Whether to enable disk caching of CRLs. If enabled, the driver caches CRLs on disk to improve performance. Applies only when CERT_REVOCATION_CHECK_MODE is not DISABLED.

默认值:

true

描述:

Specifies the time, in seconds, that a CRL is considered valid. After this time, the CRL is refreshed from the source.

默认值:

86400 (1 day)

描述:

Specifies the directory where the CRL response cache is stored.

默认值:

• Windows: %USERPROFILE%AppDataLocalSnowflakeCachescrls

• Linux: $HOME/.cache/snowflake/crls

• macOS: $HOME/Library/Caches/Snowflake/crls

描述:

Specifies the time, in seconds, to delay removing the on-disk cache.

默认值:

604800 (1 week)

描述:

仅限 Snowflake 合作伙伴使用：指定要通过 JDBC 连接的合作伙伴应用程序的名称。

描述:

指定是否仅在批处理更新成功时清除批处理条目。

• true：仅在批处理更新成功时清除批处理条目。

• false：Statement.executeBatch 和 Statement.executeLargeBatch 在执行后从不清除批处理条目，而 PreparedStatement.executeBatch 和 PreparedStatement.executeLargeBatch 在执行后总是清除批处理条目。

此参数可用于向后兼容。

默认值:

false

描述:

指定 日志记录配置文件 的路径，您可以使用该配置文件定义日志记录级别和保存日志文件的目录。 .. :默认值：sf_client_config.json

描述:

Specifies whether to send in-band telemetry data to Snowflake.

默认值:

true.

描述:

指定是否应将时间值作为字面量挂钟时间进行处理，从而避免参数为 false 时因时区敏感纪元转换而导致的潜在差异。

:默认值：false。

描述:

包含 SYSTEM$ALLOWLIST 或 SYSTEM$ALLOWLIST_PRIVATELINK 函数输出的 JSON 文件的完整路径和文件名。

如果 ENABLE_DIAGNOSTICS 是 true，您必须提供此参数。

描述:

如果为 true，驱动程序不执行任何 OCSP 检查

默认值:

false

描述:

当 true 和调用应用程序调用 DriverManager 或 DataSource getConnection() 方法时，驱动程序运行几项连接测试，并将结果写入预配置的日志文件。驱动程序还返回以下异常：

net.snowflake.client.jdbc.SnowflakeSQLException: A connection was not created because the driver is running in diagnostics mode. If this is unintended then disable diagnostics check by removing the ENABLE_DIAGNOSTICS connection parameter

如果启用此参数，您必须为 DIAGNOSTICS_ALLOWLIST_FILE 参数提供一个值。

默认值:

false

描述:

在某些 DatabaseMetaData 方法中启用或禁用精确架构搜索。

默认值:

``false``（适用于向后兼容）

描述:

启用或禁用不应将其参数用作模式的 getCrossReference、getExportedKeys、getImportedKeys 和 getPrimaryKeys 元数据操作的模式搜索。

默认值:

true

描述:

在创建 SQL 查询时，启用或禁用在某些 :codenowrap:` DatabaseMetaData` 方法中将通配符视为字面量的功能。当客户端无法转义标识符中的通配符时，此设置可能很有用。

默认值:

true

描述:

指定是否允许 PUT 和 GET 命令访问本地文件系统。将该值设置为 false 会禁用 PUT 和 GET 命令执行。

默认值:

true

描述:

指定是否在发送到 Snowflake 的查询中发送超时。

• true：除了客户端超时外，调用 Statement.setQueryTimeout 还会设置发送到 Snowflake 的查询的超时。

• false：调用 Statement.setQueryTimeout 仅设置客户端超时。

默认值:

false

描述:

已弃用。请参阅 disableOCSPChecks。

描述:

指定是否将日志消息写入标准输出（而不是标准错误）。

默认值:

false

描述:

指定要写入标准输出的最大日志消息级别。将更高的日志级别写入标准错误。仅在 JAVA_LOGGING_CONSOLE_STD_OUT 为 true 时有效。可能的值包括：

• OFF

• SEVERE

• WARNING

• INFO

• CONFIG

• FINE

• FINER

• FINEST

• ALL

默认值:

none，相当于将值设置为：OFF 或 SEVERE。

描述:

指定是否将 getObject 调用获得的 Arrow 结果集中的所有数字作为整型返回。如果此值和 JDBC_TREAT_DECIMAL_AS_INT 参数值都是 false，则 getObject 调用获得的 Arrow 返回集中的所有整型数都将作为 BigDecimal 类型返回。

默认值:

true

描述:

指定是否使用以前硬编码的格式化程序值（对于向后兼容）。

默认值:

true

描述:

指定是否使用先前的空时区值用于 getDate 方法（适用于向后兼容性）。

默认值:

true

描述:

Specifies which result format to use while fetching or processing the results of a query sent to Snowflake. Possible values include:

• Arrow

• JSON

默认值:

Arrow

描述:

指定在返回错误之前重试失败 HTTP 请求的最大次数。

默认值:

7

描述:

指定连接池中可用的最大连接总数。

默认值:

300

描述:

指定单个端口或 URL 允许的最大连接数。值不能超过 net.snowflake.jdbc.max_connections 值。

默认值:

300

描述:

指定字符串的最大字节数。如果您收到类似于以下内容的错误消息，可以增加此 Java 属性的值来为 Snowflake 响应反序列化设置更大的缓冲区：

com.fasterxml.jackson.core.exc.StreamConstraintsException: String length (XXXXXXX) exceeds the maximum length (180000000)

默认值:

180000000

描述:

指定在无法访问 OCSP 服务器以验证证书时，驱动程序应“故障打开”。请参阅 OCSP。

描述:

在为暂存区文件创建的目录上设置仅限所有者的权限 (0600)。

默认值:

false

描述:

指定存储客户端重试 PUT/GET 异常的最大次数。

默认值:

25

描述:

如果此参数设置为 true，则当 DatabaseMetaData.getColumns() 和 DatabaseMetaData.getProcedureColumns() 在列 COLUMN_DEF 中返回类型为 String 的值时，该值将嵌入在单引号内。（如果该值的数据类型不是 String，则该值不被引用，无论该参数的设置如何。）

• true 指定字符串值应嵌入单引号（引号是字符串的一部分，而不是分隔符）。这符合 JDBC 标准。

• false 指定字符串值不嵌入在单引号内。

默认值:

false

描述:

Specifies the maximum SSL/TLS version to use when initiating a TLS handshake. Valid values include:

• TLSv1.2

• TLSv1.3

Snowflake recommends leaving this setting at its default when you don't have a specific need to change it.

默认值:

TLSv1.3

描述:

Specifies the minimum SSL/TLS version to use when initiating a TLS handshake. Valid values include:

• TLSv1.2

• TLSv1.3

Snowflake recommends leaving this setting at its default when you don't have a specific need to change it.

默认值:

TLSv1.2

描述:

指定驱动程序的日志级别。驱动程序使用标准 Java 日志实用程序。您可以将此参数设置为以下日志级别之一：

• OFF

• SEVERE

• WARNING

• INFO

• CONFIG

• FINE

• FINER

• FINEST

• ALL

默认值:

INFO