配置 Snowflake CLI

Snowflake CLI 会使用名为 config.toml 的配置连接的全局配置文件和 Snowflake CLI 的日志。如果该文件不存在，则首次运行任何 snow 命令会自动创建一个空 config.toml 文件，然后您可以使用所需的连接填充该文件。有关 toml 文件格式的更多信息，请参阅 TOML （Tom 的[语义]明显、[配置]最小化的语言） (https://toml.io/en/)。Snowflake Python 库目前支持 TOML 1.0.0 版本。

config.toml 支持以下部分：

  • 用于定义和管理连接的 [connections]

  • 用于配置保存到日志文件的消息类型的 [logs]

Snowflake CLI 配置文件具有以下结构：

default_connection_name = "myconnection"

[connections]
[connections.myconnection]
account = "myorganzation-myaccount"
user = "jdoe"
...

[connections.testingconnection]
account = "myorganzation-myaccount"
user = "jdoe"
...

[cli.logs]
save_logs = true
level = "info"
path = "/home/<username>/.snowflake/logs"
Copy

.toml 配置文件的位置

默认情况下，Snowflake CLI 会查找 ~/.snowflake 目录中的 config.toml 文件，或者如果该目录不存在，则会查找系统特定位置，如下所示。您还可以使用 --config-file 标志或 SNOWFLAKE_HOME 环境变量指定应使用哪一个配置文件。

  • 如果您指定 --config-file 选项（例如 snow --config-file ./my-config-file-path）,|sf-cli| 会使用指定的配置文件。

  • 如果已设置 SNOWFLAKE_HOME 环境变量，Snowflake CLI 会使用此变量指定的位置。

  • 如果计算机中存在 ~/.snowflake 目录，则 Snowflake CLI 将使用 ~/.snowflake/config.toml 文件。

  • 否则，Snowflake CLI 将根据操作系统使用以下某个位置中的 config.toml 文件：

    • Linux：~/.config/snowflake/config.toml，但您可以使用 XDG 变量对其进行更新

    • Windows：%USERPROFILE%\AppData\Local\snowflake\config.toml

    • Mac：~/Library/Application Support/snowflake/config.toml

备注

对于 MacOS 和 Linux 系统，Snowflake CLI 要求 config.toml 文件将其文件权限限制为仅限文件所有者读写。要设置文件所需的文件权限，请执行以下命令：

chown $USER config.toml
chmod 0600 config.toml
Copy

选择不同的配置文件

在某些情况下，例如持续集成、持续部署 (CI/CD) 环境，您可能更喜欢为测试和部署管道创建专用配置文件，而不是在单个 Snowflake 默认配置文件中定义所有可能的配置。

要使用不同的配置文件而不是默认文件，可以使用 snow 命令的 --config-file 选项，如下所示：

snow --config-file="my_config.toml" connection test
Copy

支持系统环境变量

Snowflake CLI 支持使用系统环境变量替换 config.toml 文件中使用以下格式定义的参数值：

SNOWFLAKE_<config-section>_<variable>=<value>
Copy

其中：

  • <config_section> 是配置文件中带有句点的部分替换为下划线 (_) 的名称 (.)，例如 CLI_LOGS。

  • 变量是该部分中定义的变量的名称，例如 path。

一些例子包括：

  • 替换 config.toml 文件中 [cli.logs] 部分中的 path 参数：

    export SNOWFLAKE_CLI_LOGS_PATH="/Users/jondoe/snowcli_logs"
    Copy

  • 设置 myconnection 连接的密码：

    export SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD="*******"
    Copy

  • 设置默认连接名称：

    export SNOWFLAKE_DEFAULT_CONNECTION_NAME="myconnection"
    Copy

添加仅限制访问 Snowflake CLI 的身份验证策略

用户可以创建 身份验证策略，用于限制对驱动程序以及 Snowflake CLI 的访问权限。如果希望仅允许访问 |sf-cli|（而不允许访问驱动程序），可以执行以下操作：

  • 创建新的身份验证策略，严格限制对 Snowflake CLI 的访问权限。

  • 在 config.toml 文件中启用策略。

创建仅限于 Snowflake CLI 的身份验证策略

要创建仅用于 Snowflake CLI 的新身份验证策略，请按照以下步骤操作：

  1. 执行 CREATE AUTHENTICATION POLICY SQL 命令，将 CLIENT_TYPES 参数设置为包含 'SNOWFLAKE_CLI'。

CREATE AUTHENTICATION POLICY snowflake_cli_only
  CLIENT_TYPES = ('SNOWFLAKE_CLI');
Copy

  1. 为用户添加策略，如图所示：

ALTER USER user1
  SET AUTHENTICATION POLICY snowflake_cli_only;
Copy

在 Snowflake CLI 配置中启用策略

通过 enable_separate_authentication_policy_id 配置参数，您可以通过驱动程序分别访问 Snowflake CLI。启用此访问权限后，指定用户可以访问 Snowflake CLI，但不能访问其他 Snowflake 驱动程序。

警告

如果已有仅允许访问驱动程序的身份验证策略，而没有仅允许访问 Snowflake CLI 的身份验证策略，那么如果不先创建新策略，启用 enable_separate_authentication_policy_id 参数将导致用户失去对 Snowflake CLI 的访问权限。在启用配置参数之前，请确保将 SNOWFLAKE_CLI 添加到身份验证策略中。

要启用 SNOWFLAKE_CLI 策略，请在 config.toml 文件的 [cli.features] 部分添加 enable_separate_authentication_policy_id 参数，如下所示：

[cli.features]
enable_separate_authentication_policy_id = true
Copy

备注

启用此参数会影响 Snowflake CLI 建立的所有连接。

使用代理服务器

要使用代理服务器，请配置以下环境变量：

  • HTTP_PROXY

  • HTTPS_PROXY

  • NO_PROXY

例如：

Linux 或 macOS:
export HTTP_PROXY='http://username:password@proxyserver.company.com:80'
export HTTPS_PROXY='http://username:password@proxyserver.company.com:80'
Copy
Windows:
set HTTP_PROXY=http://username:password@proxyserver.company.com:80
set HTTPS_PROXY=http://username:password@proxyserver.company.com:80
Copy

小技巧

Snowflake 的安全模型不允许安全套接层 (SSL) 代理（使用 HTTPS 证书）。代理服务器必须使用公开可用的证书颁发机构 (CA)，从而降低潜在的安全风险，例如通过受感染的代理发起的 MITM（中间人）攻击。

如果 必须 使用 SSL 代理，我们强烈建议更新服务器策略以通过 Snowflake 证书，这样证书就不会在通信过程中被更改。

（可选）可以使用 NO_PROXY 绕过代理进行特定通信。例如，通过指定 NO_PROXY=".amazonaws.com"，可以绕过代理服务器访问 Amazon S3。

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

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

    • .amazonaws.com

    • myorganization-myaccount.snowflakecomputing.cn

  • IP 地址，例如：

    • 192.196.1.15

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

localhost,.my_company.com,.snowflakecomputing.cn,192.168.1.15,192.168.1.16
Copy

配置日志记录

默认情况下，Snowflake CLI 自动将 INFO、WARNING 和 ERROR 级别消息保存到日志文件中。要禁用或自定义日志记录，请在 config.toml 文件中创建 [cli.logs] 部分：

[cli.logs]
save_logs = true
level = "info"
path = "/home/<username>/.snowflake/logs"
Copy

其中：

  • save_logs 指示是否将日志保存到文件中。默认：true。

  • level 指定要保存到日志文件的消息级别。 从以下级别中进行选择，其中包括所选级别以下的所有级别：

    • debug

      警告

      切换到 debug 日志记录级别可能会暴露敏感信息，例如已执行 SQL 查询。启用此级别时要小心。

    • info

    • warning

    • error

    默认：info

  • path 指定保存日志文件的绝对路径。路径的格式因操作系统而异，如下所示：

    • Linux：path = "/home/<your_username>/.config/snowflake/logs"

    • MacOS：path = "/Users/<your_username>/Library/Application Support/snowflake/logs"

    • Windows：path = "C:\\Users\\<your_username>\\AppData\\Local\\snowflake\\logs"

    如果未指定，该命令将在默认 config.toml 文件位置中创建 logs 目录

如果您的 config.toml 是自动创建的，则 config.toml 文件包含填充有默认值的 |cli.logs| 部分。

一天的日志将追加到文件 snowflake-cli.log 中，后续重命名为 snowflake-cli.log.YYYY-MM-DD，如图所示。

ls logs/
Copy
snowflake-cli.log            snowflake-cli.log.2024-10-22
语言: 中文