管理 Snowflake 连接

在使用 Snowflake CLI 之前，必须定义连接，指定 Snowflake CLI 如何连接到 Snowflake。在多个位置定义连接参数时，Snowflake CLI 会使用以下优先级层次来决定使用哪个值：

  • 命令行参数

  • 环境变量会覆盖特定的 config.toml 参数，如 SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD

  • 手动或使用 snow connection add 命令在 config.toml 文件中定义连接

  • 通用环境变量，如 SNOWFLAKE_USER。

您也可以使用 --temporary-connection 选项，该选项无需在 config.toml 中定义。

小心

为提高安全性，Snowflake 强烈建议使用 SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD 或 SNOWFLAKE_PASSWORD 环境变量。

定义连接

连接定义存储在 config.toml 文件的 [connections] 部分，类似于以下内容：

[connections.myconnection]
account = "myaccount"
user = "jondoe"
password = "password"
warehouse = "my-wh"
database = "my_db"
schema = "my_schema"
Copy

连接定义支持的配置选项与 Snowflake Connector for Python 中提供的相同。此外，还可以在文件顶部的 default_connection_name 变量中指定默认连接。不能将其包含在连接定义中。例如：

default_connection_name = "myconnection"

[connections.myconnection]
account = "myaccount"
...
Copy

备注

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

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

备用配置文件

备注

对于 Snowflake CLI，Snowflake 建议您将 config.toml 文件用于配置定义。但是，如果需要，您可以使用 connections.toml 文件。

Snowflake CLI 还支持 connections.toml 配置文件。文件应该与 config.toml 文件放在同一个目录中，并且应该只包含连接。connections.toml 中的配置需要不同的部分名称，而不需要 connections。例如，[connections.myconnection] 将只是 [myconnection]。

备注

如果 config.toml 和 connections.toml 配置都包含连接，则 Snowflake CLI 仅使用来自 connections.toml 的配置。

使用 snow connection 命令管理连接或将其添加到 Snowflake

通过 snow connection 命令，您可以创建、管理和测试 Snowflake 连接。

添加连接

备注

如果您需要为 Snowflake Open Catalog 添加连接，请参阅 Open Catalog 文档中的 为 Open Catalog 创建 Snowflake CLI 连接。您可能需要为任务（例如配置 Open Catalog）添加此连接，才能使用 SSO。

要创建新连接并将其添加到 配置文件，请执行以下操作：

  1. 执行 snow connection add 命令：

    snow connection add
    Copy

  2. 出现提示时，提供所需的连接、账户和用户名参数，以及所需的其他可选参数。

    Enter connection name: <connection_name>
Enter account: <account>
Enter user: <user-name>
Enter password: <password>
Enter role: <role-name>
Enter warehouse: <warehouse-name>
Enter database: <database-name>
Enter schema: <schema-name>
Enter host: <host-name>
Enter port: <port-number>
Enter region: <region-name>
Enter authenticator: <authentication-method>
Enter private key file: <path-to-private-key-file>
Enter token file path: <path-to-mfa-token>
Do you want to configure key pair authentication? [y/N]: y
Key length [2048]: <key-length>
Output path [~/.ssh]: <path-to-output-file>
Private key passphrase: <key-description>
Wrote new connection <connection-name> to config.toml

您还可以在命令行中为特定参数添加值，如下所示：

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2
Copy

备注

如果命令结束时出现错误，例如 --private_key_file 选项引用了一个不存在的文件，则连接不会保存在 config.toml 配置文件中。

默认情况下，如果命令行未指定可选参数，snow connection add 命令会提示输入这些参数。如果想添加连接而不指定一些可选参数（如 account），并跳过交互式提示，则可以使用 --no-interactive 选项，如下所示：

snow connection add -n myconnection2 --user jdoe2 --no-interactive
Copy

添加连接后，您可以 测试连接，以确保其正常运行。

列出已定义的连接

要列出可用的连接，请输入 snow connection list 命令，如下所示：

snow connection list
Copy
+-------------------------------------------------------------------------------------------------+
| connection_name | parameters                                                       | is_default |
|-----------------+------------------------------------------------------------------+------------|
| myconnection    | {'account': 'myaccount', 'user': 'jondoe', 'password': '****',   | False      |
|                 | 'database': 'my_db', 'schema': 'my_schema', 'warehouse':         |            |
|                 | 'my-wh'}                                                         |            |
| myconnection2   | {'account': 'myaccount2', 'user': 'jdoe2'}                       | False      |
+-------------------------------------------------------------------------------------------------+

测试和诊断连接

要测试连接是否能成功连接到 Snowflake，请输入 snow connection test 命令，类似于以下内容：

snow connection test -c myconnection2
Copy
+--------------------------------------------------+
| key             | value                          |
|-----------------+--------------------------------|
| Connection name | myconnection2                  |
| Status          | OK                             |
| Host            | example.snowflakecomputing.cn |
| Account         | myaccount2                     |
| User            | jdoe2                          |
| Role            | ACCOUNTADMIN                   |
| Database        | not set                        |
| Warehouse       | not set                        |
+--------------------------------------------------+

如果遇到连接问题，您可以直接在 Snowflake CLI 内运行诊断。Snowflake 支持部门也可能要求您提供此信息以帮助您解决连接问题。

诊断集合使用以下 snow connection test 命令选项：

  • --enable-diag，用于生成诊断报告。

  • --diag-log-path，用于指定生成的报告的绝对路径。

  • --diag-allowlist-path，用于指定包含 SYSTEM$ALLOWLIST() 或 SYSTEM$ALLOWLIST_PRIVATELINK() SQL 命令输出的 JSON 文件的绝对路径。只有在连接中定义的用户没有权限运行系统允许列表功能或连接账户 URL 失败时，才需要此选项。

以下示例为 myconnection2 连接生成诊断报告，并存储在 ~/report/SnowflakeConnectionTestReport.txt 文件中：

snow connection test -c myconnection2 --enable-diag --diag-log-path $(HOME)/report
Copy
+----------------------------------------------------------------------------+
| key                  | value                                               |
|----------------------+-----------------------------------------------------|
| Connection name      | myconnection2                                       |
| Status               | OK                                                  |
| Host                 | example.snowflakecomputing.cn                      |
| Account              | myaccount2                                          |
| User                 | jdoe2                                               |
| Role                 | ACCOUNTADMIN                                        |
| Database             | not set                                             |
| Warehouse            | not set                                             |
| Diag Report Location | /Users/<username>/SnowflakeConnectionTestReport.txt |
+----------------------------------------------------------------------------+

您可以查看报告以了解所有连接问题，并与网络团队讨论这些问题。您还可以向 Snowflake 支持部门提供报告以获得其他帮助。

设置默认连接

您可以使用 snow connection set-default 命令指定应使用哪个配置 Snowflake CLI 作为默认配置，如果已设置，则覆盖 default_connection_name 配置文件和 SNOWFLAKE_DEFAULT_CONNECTION_NAME 变量。

以下示例会将默认连接设置为 myconnection2:

snow connection set-default myconnection2
Copy
Default connection set to: myconnection2

备注

如果同时存在 connections.toml 和 config.toml 文件，Snowflake CLI 只会使用 connections.toml 中定义的连接。

为 Snowflake 凭据使用环境变量

您可以在系统环境变量而不是配置文件中指定 Snowflake 凭据。只能使用以下通用环境变量指定连接参数：

  • SNOWFLAKE_ACCOUNT

  • SNOWFLAKE_USER

  • SNOWFLAKE_PASSWORD

  • SNOWFLAKE_DATABASE

  • SNOWFLAKE_SCHEMA

  • SNOWFLAKE_ROLE

  • SNOWFLAKE_WAREHOUSE

  • SNOWFLAKE_AUTHENTICATOR

  • SNOWFLAKE_PRIVATE_KEY_PATH

  • SNOWFLAKE_PRIVATE_KEY_RAW

  • SNOWFLAKE_SESSION_TOKEN

  • SNOWFLAKE_MASTER_TOKEN

  • SNOWFLAKE_TOKEN_FILE_PATH

向 snow 命令传递连接参数

您可以在需要连接的每条 snow 命令中直接传递连接参数。有关连接配置参数的完整列表，请执行 snow sql --help 命令，如下所示。请注意，输出结果只会显示连接配置选项部分。

snow sql --help
Copy
╭─ Connection configuration ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --connection,--environment             -c      TEXT     Name of the connection, as defined in your config.toml. Default: default.            │
│ --host                                         TEXT     Host address for the connection. Overrides the value specified for the connection.   │
│ --port                                         INTEGER  Port for the connection. Overrides the value specified for the connection.           │
│ --account,--accountname                        TEXT     Name assigned to your Snowflake account. Overrides the value specified for the       │
│                                                         connection.                                                                          │
│ --user,--username                              TEXT     Username to connect to Snowflake. Overrides the value specified for the connection.  │
│ --password                                     TEXT     Snowflake password. Overrides the value specified for the connection.                │
│ --authenticator                                TEXT     Snowflake authenticator. Overrides the value specified for the connection.           │
│ --private-key-file,--private-key-path          TEXT     Snowflake private key file path. Overrides the value specified for the connection.   │
│ --token-file-path                              TEXT     Path to file with an OAuth token that should be used when connecting to Snowflake    │
│ --database,--dbname                            TEXT     Database to use. Overrides the value specified for the connection.                   │
│ --schema,--schemaname                          TEXT     Database schema to use. Overrides the value specified for the connection.            │
│ --role,--rolename                              TEXT     Role to use. Overrides the value specified for the connection.                       │
│ --warehouse                                    TEXT     Warehouse to use. Overrides the value specified for the connection.                  │
│ --temporary-connection                 -x               Uses connection defined with command line parameters, instead of one defined in      │
│                                                         config                                                                               │
│ --mfa-passcode                                 TEXT     Token to use for multi-factor authentication (MFA)                                   │
│ --enable-diag                                           Run python connector diagnostic test                                                 │
│ --diag-log-path                                TEXT     Diagnostic report path                                                               │
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

小心

为提高安全性，Snowflake 强烈建议使用 SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD 或 SNOWFLAKE_PASSWORD 环境变量。

从 SnowSQL 导入连接

如果在 SnowSQL 中定义了现有连接，可以使用 snow helpers import-snowsql-connections 命令将其导入到 Snowflake CLI config.toml 配置文件中。

要导入 SnowSQL 连接，请输入 snow helpers import-snowsql-connections 命令，如下所示：

snow helpers import-snowsql-connections
Copy

以下示例从标准配置文件位置导入 SnowSQL 连接：

snow helpers import-snowsql-connections
Copy

该命令在处理 SnowSQL 配置文件时，会显示进度，并在 Snowflake CLI config.toml 文件中已经定义了同名连接时提示确认：

SnowSQL config file [/etc/snowsql.cnf] does not exist. Skipping.
SnowSQL config file [/etc/snowflake/snowsql.cnf] does not exist. Skipping.
SnowSQL config file [/usr/local/etc/snowsql.cnf] does not exist. Skipping.
Trying to read connections from [/Users/<user>/.snowsql.cnf].
Reading SnowSQL's connection configuration [connections.connection1] from [/Users/<user>/.snowsql.cnf]
Trying to read connections from [/Users/<user>/.snowsql/config].
Reading SnowSQL's default connection configuration from [/Users/<user>/.snowsql/config]
Reading SnowSQL's connection configuration [connections.connection1] from [/Users/<user>/.snowsql/config]
Reading SnowSQL's connection configuration [connections.connection2] from [/Users/<user>/.snowsql/config]
Connection 'connection1' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: Y
Connection 'connection2' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: n
Connection 'default' already exists in Snowflake CLI, do you want to use SnowSQL definition and override existing connection in Snowflake CLI? [y/N]: n
Saving [connection1] connection in Snowflake CLI's config.
Connections successfully imported from SnowSQL to Snowflake CLI.

有关更多信息，请参阅 snow helpers import-snowsql-connections 命令参考。

使用临时连接

您还可以使用 --temporary-connection [-x] 选项从命令行指定连接参数。它会忽略 config.toml 中的所有定义，而是使用命令行选项指定的定义。如果您不想使用配置文件，这种方法对 CI/CD 用例很有帮助。使用临时连接时，Snowflake CLI 会忽略 config.toml 文件中定义的所有连接变量，但仍会使用您设置的 环境变量，例如 SNOWFLAKE_ACCOUNT。

snow sql -q "select 42;" --temporary-connection \
                           --account myaccount \
                           --user jdoe
Copy
select 42;
+----+
| 42 |
|----|
| 42 |
+----+

小心

为提高安全性，Snowflake 强烈建议使用 SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD 或 SNOWFLAKE_PASSWORD 环境变量。

对连接进行身份验证的其他方法

您还可以使用以下方法对您与 Snowflake 的连接进行身份验证：

使用私钥文件进行身份验证

要使用私钥文件进行身份验证，连接配置需要将 authenticator 参数设置为 SNOWFLAKE_JWT，并提供包含私钥的文件路径，类似于以下内容：

  • 在 snow connection add 命令中指定 --private_key-file 选项，如下所示：

    snow connection add \
   --connection-name jwt \
   --authenticator SNOWFLAKE_JWT \
   --private-key-file ~/.ssh/sf_private_key.p8
    Copy

  • 使用配置文件：

    [connections.jwt]
account = "my_account"
user = "jdoe"
authenticator = "SNOWFLAKE_JWT"
private_key_file = "~/sf_private_key.p8"
    Copy

有关配置密钥对身份验证的详细信息，请参阅 密钥对身份验证和密钥对轮换。

备注

如果私钥受加密短语保护，请将 PRIVATE_KEY_PASSPHRASE 环境变量设置为该加密短语。

使用 OAuth 身份验证

要使用 OATH 进行连接，您可以执行以下任一操作：

  • 在 snow connection add 命令中指定 --token-file-path 选项，如下所示：

    snow connection add --token-file-path "my-token.txt"
    Copy

  • 在 config.toml 文件中，设置 authenticator = "oauth"，并在连接定义中添加 token_file_path 参数，如下所示：

    [connections.oauth]
account = "my_account"
user = "jdoe"
authenticator = "oauth"
token_file_path = "my-token.txt"
    Copy

使用多重身份验证 (MFA)

要使用 MFA，请执行以下步骤：

  1. 在 Snowflake 中设置 多重身份验证，并将 authenticator 参数设置为 ``snowflake``（这是默认值）。

  2. 如果您想使用 Duo 生成的密码来代替推送机制，可以使用 --mfa-passcode <passcode> 选项，或者在 config.toml 文件中设置 passcode_in_password = true，并在密码中包含通过代码，如 在 Python 中使用 MFA 中所述。

    备注

    如果要使用密码中的通过代码进行身份验证，在执行第一条 snow 命令后，只要令牌有效，就无法再提供通过代码。您必须执行以下操作：

    • 从密码中移除通过代码。

    • 删除 config.toml 文件中的 passcode_in_password = true 或向其添加注释。

要启用 MFA 缓存，请执行以下操作：

  1. 为您的账户设置 ALLOW_CLIENT_MFA_CACHING = true。

  2. 在 config.toml 文件中，将 authenticator = "username_password_mfa" 添加到连接中。

使用 SSO（单点登录）

如果 已将 Snowflake 配置为使用单点登录 (SSO)，则可将客户端应用程序配置为使用 SSO 进行身份验证。有关详细信息，请参阅 与连接到 Snowflake 的客户端应用程序结合使用 SSO，并使用 Python 的说明配置连接。

使用外部浏览器

您可以使用您的浏览器，通过任何符合 SAML 2.0 的身份提供商 (IdP)（例如 Okta 或 Active Directory 联合身份验证服务）对您的 Snowflake CLI 连接进行身份验证。

备注

externalbrowser 身份验证器仅在具有 Web 浏览器访问权限的终端窗口中受支持。例如，通过 SSH (Secure Shell) 会话访问的远程计算机上的终端窗口可能需要额外的设置才能打开 Web 浏览器。

如果您无权访问 Web 浏览器，但您的 IdP 是 Okta，则可以将身份验证器设置为 https://<okta_account_name>.okta.com，以使用原生 Okta。

要使用外部浏览器身份验证，请使用以下方法之一：

  • 使用 snow connection add --authenticator 命令选项：

    snow connection add --authenticator externalbrowser
    Copy

  • 在 config.toml 文件中，将 authenticator 设置为 externalbrowser：

    [connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "externalbrowser"
    Copy
语言: 中文