管理 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 = "hunter2"
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 connections.toml
chmod 0600 connections.toml

Copy

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 连接。

添加连接¶

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

执行 snow connection add 命令：

snow connection add

Copy

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

Name for this connection: <connection-name>
Snowflake account name: <account-name>
Snowflake username: <user-name>
Snowflake password [optional]: <password-value>
Role for the connection [optional]: <role-name>
Warehouse for the connection [optional]: <warehouse-name>
Database for the connection [optional]: <database-name>
Schema for the connection [optional]: <schema-name>
Connection host [optional]: <host-name>
Connection port [optional]: <port-value>
Snowflake region [optional]: <region-name>
Authentication method [optional]: <authentication-method>
Path to private key file [optional]: <path-to-private-key>
Path to token file [optional]: <path-to-mfa-token>
Wrote new connection myconnection2 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                        |
+--------------------------------------------------+

设置默认连接¶

您可以使用 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_SESSION_TOKEN
SNOWFLAKE_MASTER_TOKEN

向 `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 环境变量。

使用临时连接¶

您还可以使用 --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 的连接进行身份验证：

使用私钥文件进行身份验证
使用 OAuth 身份验证
使用多重身份验证 (MFA)
使用 SSO（单点登录）

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

要使用私钥文件进行身份验证，连接配置需要将 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，请执行以下步骤：

在 Snowflake 中设置多重身份验证，并将 authenticator 参数设置为 ``snowflake``（这是默认值）。
如果您想使用 Duo 生成的密码来代替推送机制，可以使用 --mfa-passcode <passcode> 选项，或者在 config.toml 文件中设置 passcode_in_password = true，并在密码中包含通过代码，如在 Python 中使用 MFA 中所述。
备注

如果要使用密码中的通过代码进行身份验证，在执行第一条 snow 命令后，只要令牌有效，就无法再提供通过代码。您必须执行以下操作：
- 从密码中移除通过代码。
- 删除 config.toml 文件中的 passcode_in_password = true 或向其添加注释。

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

为您的账户设置 ALLOW_CLIENT_MFA_CACHING = true。
在 config.toml 文件中，将 authenticator = username_password_mfa 添加到连接中。

使用 SSO（单点登录）¶

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

管理 Snowflake 连接¶

定义连接¶

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

添加连接¶

列出已定义的连接¶

测试连接¶

设置默认连接¶

为 Snowflake 凭据使用环境变量¶

向 snow 命令传递连接参数¶

使用临时连接¶

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

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

使用 OAuth 身份验证¶

使用多重身份验证 (MFA)¶

使用 SSO（单点登录）¶

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

向 `snow` 命令传递连接参数¶