ODBC 配置和连接参数¶

必填的连接参数¶

<name> （数据源）

指定了 DSN 的名称。

port （端口）

指定了驱动程序侦听 Snowflake 通信的端口。

备注

无需更改默认 Port 值 443。

pwd （密码）

连接到 Snowflake 需要密码；但是，出于安全和身份验证的原因，Snowflake 强烈建议不要将密码凭据直接存储在任何 DSN 定义中。

通常情况下，尝试连接到 Snowflake 的客户端应用程序以编程方式将凭据传递给驱动程序。

备注

在 Windows 中，ODBC 驱动程序在 Data Source Administration 工具中显示一个 Password 字段；但是，驱动程序 并不 存储该字段中输入的任何值。相反，驱动程序要求在连接时提供登录凭据。

server （服务器）

使用以下格式为账户指定 主机名：

account_identifier.snowflakecomputing.cn

有关账户标识符的信息，请参阅 账户标识符。

uid （用户）

指定了要进行身份验证的 Snowflake 用户的登录名。

可选连接参数¶

BROWSER_RESPONSE_TIMEOUT

指定了在外部浏览器中等待身份验证响应的秒数。

默认值为 120。

CLIENT_OUT_OF_BAND_TELEMETRY_ENABLED=<Boolean>

指定是否启用带外遥测。

默认值为 true

CLIENT_SESSION_KEEP_ALIVE=<Boolean>

指定了一段时间不活动后，是保持当前会话处于活动状态，还是强制用户重新登录。如果值为 true，Snowflake 会无限期地保持会话处于活动状态，即使用户没有活动也是如此。如果值为 false，用户在不活动 4 小时后必须重新登录。

默认值为 false。

database （数据库）

指定了由驱动程序启动的会话所用的默认数据库。

maxHttpRetries （数据库）

指定了在返回错误之前，对 HTTP 请求失败的查询的最大 HTTP 重试次数。设置 maxHttpRetries=0 移除了重试限制，但此操作会带来驱动程序无限重试失败 HTTP 调用的风险。

默认值为 7。

role （角色）

指定了由驱动程序启动的会话所用的默认角色。指定的角色应是已分配给驱动程序指定用户的角色。如果指定的角色与分配给用户的任何角色均不匹配，则驱动程序启动的会话没有初始角色；但是，始终可以在会话中指定角色。

schema （架构）

指定了由驱动程序启动的会话所用的默认架构。

默认值为 public。

SecondaryRoles （角色）

指定了由驱动程序启动的会话所用的辅助角色。该角色必须已被授予驱动程序的指定用户。还可以使用 USE SECONDARY ROLES 命令在用户会话中激活辅助角色。

可能的值包括：

• All：已授予用户的所有角色。

• None：不允许任何角色（禁用辅助角色）。

tracing （跟踪）

要在驱动程序跟踪文件中记录的详细信息级别：

• 0 = 禁用跟踪

• 1 = 仅致命错误跟踪

• 2 = 错误跟踪

• 3 = 警告跟踪

• 4 = 信息跟踪

• 5 = 调试跟踪

• 6 = 详细跟踪

warehouse （仓库）

指定了由驱动程序启动的会话所用的默认仓库。

其他连接参数¶

allowEmptyProxy

指定是否允许 proxy 和 no_proxy 连接参数为空值，如以下部分所述：

• 使用连接参数

• 使用配置参数

• 使用环境变量

设置此值会产生以下效果：

• true：驱动程序将空代理值视为有效代理设置，并替换任何现有设置或环境变量。

• false：驱动程序忽略空代理值并使用指定的配置参数或环境变量。

默认值为 true。

application

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

也可以通过调用 SQLSetConnectAttr() 函数来设置此参数。有关更多详细信息，请参阅 :ref:` SQLSetConnectAttr 函数的 Snowflake 特定行为 <label-odbc_api_sqlsetconnectattr_specific_behavior>`。

authenticator

指定了用于验证用户登录凭据的身份验证器：

• snowflake （默认），使用内部 Snowflake 身份验证器。

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

  备注

  Snowflake ODBC 驱动程序不支持在 MacOS 中使用 Microsoft Excel 进行 externalbrowser 身份验证。

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

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

• username_password_mfa，使用 MFA 令牌缓存进行身份验证。有关更多详细信息，请参阅 ` 使用多重身份验证 `_ （本主题内容）。

默认值为 snowflake。

在 Windows 中，可以使用 ODBC 数据源管理工具 设置此参数。

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

default_binary_size、. default_varchar_size

指定了驱动程序从大小不确定的 BINARY 或 VARCHAR 列中检索和转换值时使用的默认大小（以字节为单位）。从这些类型的列中检索值时可设置此项。

默认情况下，驱动程序在分配内存以检索大小不确定的列的值时，使用 8388608 （对于 BINARY 列）和 16777216 （对于 VARCHAR 列）作为默认大小。

若要减少为这些值分配的内存量，可以将 default_binary_size 和 default_varchar_size 设置为这些类型的列中值的最大大小。

备注

设置这些值只会更改实现行描述符 (IRD) 中的 SQL_DESC_LENGTH 字段以及从 SQLDescribeCol/SQLColAttribute/SQLColAttributes 返回的相应值。即使数据长度超过了设置值，驱动程序仍会返回整个数据。

另一方面，应用程序可以根据这些参数中指定的长度分配数据缓冲区，从而导致因缓冲区空间不足而截断数据。作为最佳实践，Snowflake 建议将默认大小设置为大于典型数据的最大大小（例如 4000 或 8000 字节），以显著减少内存使用量，使其低于原始默认值 16777216/8388608 字节，并最大程度地减少数据被截断的可能性。

请注意，您还可以使用这些设置来避免以下错误，此错误在使用 Microsoft OLE DB 提供商 (MSDASQL) 访问 Snowflake 数据库时可能发生：

Requested conversion is not supported
Cannot get the current row value of column

Copy

您可以将这些参数指定为连接 配置参数 的 simba.snowflake.ini 中）。如果被同时设置为连接参数 和 配置参数，则 DSN（或连接字符串）中的连接参数优先。

这些参数在 ODBC 驱动程序 2.23.2 版本中推出。

get_size_threshold

指定了最小文件大小（以兆字节 [MB] 为单位），以便在使用 GET 命令下载文件时将文件分解为较小的部分。对于小于此阈值的文件，下载时不会分解为多个部分。

默认值为 5 (MB)。

备注

将此值设置为连接参数会替换相应 get_size_threshold 配置参数的值。

login_timeout

指定了连接到 Snowflake 服务时，返回登录失败错误之前等待响应的时间（以秒为单位）。

默认值为 ** 300 ** （秒）。

network_timeout

指定了与 Snowflake 服务交互时，返回错误之前等待响应的时间（以秒为单位）。零 (0) 表示未设置网络超时。

默认值为 ** 0 ** （秒）。

retryTimeout

指定在 HTTP 请求失败的查询返回 HTTP 重试错误之前等待的时间（以秒为单位）。零 (0) 表示未设置重试超时。

默认值为 ** 300 ** （秒）。

no_proxy

指定了允许绕过代理服务器的主机名末尾（例如 no_proxy=.amazonaws.com 表示访问 Amazon S3 无需通过代理）。

此参数不支持通配符。指定的每个值都应为以下内容之一：

• 主机名的末尾（或完整主机名），例如：

  • .amazonaws.com

  • myorganization-myaccount.snowflakecomputing.cn

• IP 地址，例如：

  • 192.196.1.15

如果指定了多个值，则应使用逗号分隔这些值，例如：

no_proxy=localhost,.my_company.com,myorganization-myaccount.snowflakecomputing.cn,192.168.1.15,192.168.1.16

Copy

备注

此参数应用于进程。如果另一个连接共享相同的进程，则代理设置必须相同，否则行为无法预测。

odbc_use_standard_timestamp_columnsize

此布尔参数会影响为 SQL_TYPE_TIMESTAMP 返回的列大小（以字符为单位）。当此参数设置为 true 时，驱动程序将按照 ODBC 标准返回 29。当此参数设置为 false 时，驱动程序将返回 35，为时区偏移留出空间（例如“-08:00”）。

此值不仅可以通过 odbc.ini 文件（Linux 或 macOS）或 Microsoft Windows 注册表进行设置，还可以通过连接字符串进行设置。

默认值为 false。

passcode

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

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

passcodeInPassword

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

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

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

默认值为 off。

proxy

以 http://<hostname>:<port>/ 或 <hostname>:<port_number> 的格式指定了代理服务器 URL，以便 ODBC 的所有通信都使用代理服务器。

备注

此参数应用于进程。如果另一个连接共享相同的进程，则代理设置必须相同，否则行为无法预测。

put_compresslv

指定了 ODBC 驱动程序在使用 PUT 命令传输数据时所用的压缩率。此参数将替换默认的 gzip 压缩级别。如果未指定 put_compresslv，ODBC 驱动程序将使用默认压缩级别。

有效值为 -1 至 9。默认值为 -1，指定默认的 Z_DEFAULT_COMPRESSION。

值 0 至 9 指定了自定义压缩率。如果值为 0，则 ODBC 驱动程序使用较低的压缩率；如果值为 9，则使用较高的压缩率。使用较高的压缩速率会导致数据传输速度变慢。

您还可以将此参数指定为 配置参数 的 simba.snowflake.ini 中）。如果被同时设置为连接参数 和 配置参数，则 DSN（或连接字符串）中的连接参数优先。

此参数已在 ODBC 驱动程序 2.23.3 版本中推出。

put_fastfail

如果在 PUT 命令中使用通配符一次上传多个文件，并且希望驱动程序在发生错误时停止上传文件，可将此参数设置为 true。

默认值为 false，这意味着如果一个文件发生错误，驱动程序将继续上传其余文件。

此参数已在 ODBC 驱动程序 2.22.3 版本中推出。

自 ODBC 驱动程序 2.22.5 版本起，您还可以将此参数指定为 配置参数 的 simba.snowflake.ini 中）。如果被同时设置为连接参数 和 配置参数，则 DSN（或连接字符串）中的连接参数优先。

put_maxretries

指定了 PUT 命令失败时，驱动程序重试此命令的次数。

默认值为 5。

此参数的有效值范围为 0 至 100。如果指定的值超出此范围，驱动程序将使用默认值 5。

此参数已在 ODBC 驱动程序 2.22.3 版本中推出。

自 ODBC 驱动程序 2.22.5 版本起，您还可以将此参数指定为 配置参数 的 simba.snowflake.ini 中）。如果被同时设置为连接参数 和 配置参数，则 DSN（或连接字符串）中的连接参数优先。

put_tempdir

指定了用于 PUT 命令请求的临时目录。驱动程序使用此临时目录创建临时压缩文件，然后再将这些文件上传到 Snowflake。

如果未设置此参数，驱动程序将创建并使用临时目录 /tmp/snowflakeTmp_username，其中 username 是操作系统中当前用户的用户名。

您还可以将此参数指定为 配置参数 的 simba.snowflake.ini 中）。如果被同时设置为连接参数 和 配置参数，则 DSN（或连接字符串）中的连接参数优先。

此参数已在 ODBC 驱动程序 2.23.1 版本中推出。

query_timeout

指定了返回错误之前等待查询完成的时间（以秒为单位）。零 (0) 表示无限期等待。

默认值为 ** 0 ** （秒）。

token=<string>

指定要用于身份验证的 OAuth 令牌，其中 <string> 为令牌。仅当设置了 authenticator=oauth 参数时，才需要此参数。

默认为无。

validateSessionParam

指定了当以下任意 会话连接参数 无效时如何响应：

• database
• schema
• warehouse

可能的值包括：

• false （默认）：连接成功，但将 database 和 schema 参数的值设置为空字符串，并将 warehouse 参数设置为其默认值。有关仓库的更多信息，请参阅 会话中的仓库使用情况。

• true：拒绝连接并引发错误。

使用连接参数¶

要通过代理服务器进行连接，请将以下连接参数添加到 DSN：

• proxy

• no_proxy

例如：

[connection]
Description = SnowflakeDB
Driver      = SnowflakeDSIIDriver
Locale      = en-US
server      = myorganization-myaccount.snowflakecomputing.cn
proxy       = http://proxyserver.company:80
no_proxy    = .amazonaws.com

Copy

请参阅 连接参数，了解有关参数说明。

使用配置参数¶

要通过代理服务器进行连接，请添加以下配置参数：

• Proxy

• NoProxy

请参阅 配置参数，了解有关参数说明。

使用环境变量¶

要通过代理服务器进行连接，请配置以下环境变量：

• http_proxy

• https_proxy

• no_proxy

例如：

• Linux 或 macOS：

  export http_proxy=http://proxyserver.company.com:80
  export https_proxy=http://proxyserver.company.com:80
  

  Copy

  如果代理服务器需要用户名和密码，请包含凭据，例如：

  export https_proxy=http://username:password@proxyserver.company.com:80
  

  Copy

• Windows：

  set http_proxy=http://proxyserver.company.com:80
  set https_proxy=http://proxyserver.company.com:80
  

  Copy

  如果代理服务器需要用户名和密码，请包含凭据，例如：

  set https_proxy=http://username:password@proxyserver.company.com:80
  

  Copy

或者，您可以设置 no_proxy 以绕过代理进行特定通信（例如 no_proxy=.amazonaws.com 可绕过 Amazon S3 访问）。

日志记录配置文件¶

或者，您也可以在 sf_client_config.json 配置文件中轻松指定日志级别和保存日志文件的目录。

此配置文件使用 JSON 定义 log_level 和 log_path 日志记录参数，如下所示：

{
  "common": {
    "log_level": "DEBUG",
    "log_path": "/home/user/logs"
  }
}

驱动程序会按以下顺序查找配置文件的位置：

• client_config_file 包含配置文件的完整路径。

• SF_CLIENT_CONFIG_FILE 环境变量，包含配置文件的完整路径。

• ODBC 驱动程序安装目录，其中文件名必须为 sf_client_config.json。

• 用户的主目录，其文件名必须为 sf_client_config.json。