通过 SnowSQL 进行连接¶

本主题介绍如何通过手动输入连接参数来连接 Snowflake。本主题还介绍如何配置便于使用的默认连接，以及如何配置一个或多个“命名连接”，以使用备选连接设置或创建多个并发会话。

连接语法

$ snowsql <connection_parameters>

Where <connection_parameters> are one or more of the following. For detailed descriptions of each parameter, see 连接参数参考 (in this topic).

连接时指定密码

密码无法通过连接参数传递。必须通过以下方式之一指定密码：

• Entered via interactive prompt in SnowSQL (applies to passwords only).
• Defined in the SnowSQL configuration file using the password option. For details, see Configuring Default Connection Settings (in this topic).
• Specified using the SNOWSQL_PWD environment variables. For details, see Using Environment Variables (in this topic).

使用环境变量

Currently, environment variables can only be used to pre-specify some command-line parameter values such as password, host, and database. Environment variables are not available to use in SnowSQL variable substitution unless they are explicitly specified on the command line when starting SnowSQL, using either the -D or --variable connection parameter. For example:

Linux/macOS:

Copy codeExpand code block

$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=$DB_KEY

Show lessSee more

Scroll to top

Windows:

Copy codeExpand code block

$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=%DB_KEY%

Show lessSee more

Scroll to top

In the above example, --variable sets a Snowflake variable named db_key to the DB_KEY environment variable.

配置默认连接设置

建议配置默认连接参数，以简化连接过程。此后，当连接到 Snowflake 时，可以省略 Snowflake 账户标识符、用户名和已配置为默认值的其他参数。

要配置默认设置，请执行以下步骤：

1. In the [connections] section, configure the default connection parameters by removing the comment symbol from any of the following parameters and specifying the correct values. For information on these settings, see Configuring a client, driver, library, or third-party application to connect to Snowflake.

   Copy codeExpand code block

   [connections]
   #accountname = <string>   # Account identifier to connect to Snowflake (for example, myorganization-myaccount).
   #username = <string>      # User name in the account. Optional.
   #password = <string>      # User password. Optional.
   #dbname = <string>        # Default database. Optional.
   #schemaname = <string>    # Default schema. Optional.
   #warehousename = <string> # Default warehouse. Optional.
   #rolename = <string>      # Default role. Optional.
   #authenticator = <string> # Authenticator: 'snowflake', 'externalbrowser' (to use any IdP and a web browser),  https://<okta_account_name>.okta.com (to use Okta natively), 'oauth' to authenticate using OAuth.

   Show lessSee more

   Scroll to top

   Attention

   • The password is stored in plain text in the config file. You must explicitly secure the file to restrict access. For example, in Linux or macOS, you can set the read permissions to you alone by running chmod:

     Copy codeExpand code block

     $ chmod 700 ~/.snowsql/config

     Show lessSee more

     Scroll to top

   • 如果密码包含特殊字符，则必须将密码括在单引号或双引号内。

使用 SnowCD 验证与 Snowflake 的网络连接¶

After configuration, you can evaluate and troubleshoot your network connectivity to Snowflake using SnowCD.

可以在初始配置过程中使用 SnowCD，也可以根据需要随时使用，以评估与 Snowflake 的网络连接并进行故障排除。

使用命名连接

要同时建立与 Snowflake 的多个连接，或者只是想存储多组不同的连接配置，您可以定义一个或多个 命名 连接。

在配置文件中定义命名连接

1. Open the config configuration file in a text editor. By default, the file is located in:

   Linux/macOS:

   ~/.snowsql/

   Windows:

   %USERPROFILE%\.snowsql\

2. Add a separate [connections] section with a unique name for each named connection.

   For example, the following illustrates a connection named my_example_connection for a Snowflake account with the account identifier myorganization-myaccount:

   Copy codeExpand code block

   [connections.my_example_connection]
   accountname = myorganization-myaccount
   username = jsmith
   password = xxxxxxxxxxxxxxxxxxxx
   dbname = mydb
   schemaname = public
   warehousename = mywh

   Show lessSee more

   Scroll to top

使用命名连接来连接到 Snowflake¶

Use the -c <string> (or --connection <string>) connection parameter to specify a named connection, where <string> is the name of a connection defined in the configuration file.

For example, connect using the my_example_connection connection you created in Defining Named Connections in the Configuration File (in this topic):

Copy codeExpand code block

$ snowsql -c my_example_connection

Show lessSee more

Scroll to top

使用密钥对身份验证和密钥对轮换

SnowSQL 支持密钥对身份验证和密钥轮换。您可以使用未加密或已加密的密钥对。

以下过程假定您使用推荐的加密密钥对身份验证：

1. To start, follow the instructions to configure Key-pair authentication and key-pair rotation.
2. 在配置文件或命令行中指定私钥文件的路径：

• 在配置文件中：

  • Add the private_key_path connection parameter to your connection settings and specify the local path to the private key file you created. The syntax is not OS-specific:

    Supported OS:

    Copy codeExpand code block

    private_key_path = <path>/rsa_key.p8

    Show lessSee more

    Scroll to top

  • Use the SNOWSQL_PRIVATE_KEY_PASSPHRASE environment variable to set the passphrase for decrypting the private key file. Note that you do not enclose the passphrase in quotes for Linux or MacOS but must use single or double quotes for Windows:

    Linux/macOS:

    Copy codeExpand code block

    export SNOWSQL_PRIVATE_KEY_PASSPHRASE=<passphrase>

    Show lessSee more

    Scroll to top

    Windows:

    Copy codeExpand code block

    set SNOWSQL_PRIVATE_KEY_PASSPHRASE=<passphrase>

    Show lessSee more

    Scroll to top

• 在命令行上：

  Include the private-key-path connection parameter and specify the path to your encrypted private key file:

  Copy codeExpand code block

  $ snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8

  Show lessSee more

  Scroll to top

  SnowSQL prompts you for the passphrase. Alternatively, use the SNOWSQL_PRIVATE_KEY_PASSPHRASE environment variable to set the passphrase for decrypting the private key file (as described above).

使用 OAuth 2.0 授权码流程¶

OAuth 2.0 授权码流程是一种安全的方法，客户端应用程序可以使用该流程，在不泄露用户凭据的情况下代表用户从授权服务器获取访问令牌。

以下示例配置文件显示了如何使用此流程：

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
username = "user"
accountname = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

使用 OAuth 2.0 客户端凭据流程¶

OAuth 2.0 客户端凭据流程为机器对机器 (M2M) 身份验证提供了一种安全的方式，例如连接后端服务的 Snowflake Connector for Python。与 OAuth 2.0 授权码流程不同，此方法不依赖于任何用户特定的数据。

以下示例配置文件显示了如何使用此流程：

[connections.oauth]
authenticator = "OAUTH_CLIENT_CREDENTIALS"
username = "user"
accountname = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_token_request_url = "http://identity.provider.com/token"
oauth_scope = "session:role:PUBLIC"

使用代理服务器

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

• HTTP_PROXY
• HTTPS_PROXY
• NO_PROXY

例如：

Linux/macOS:

Copy codeExpand code block

export HTTP_PROXY='http://username:password@proxyserver.example.com:80'
export HTTPS_PROXY='http://username:password@proxyserver.example.com:80'

Show lessSee more

Scroll to top

Windows:

Copy codeExpand code block

set HTTP_PROXY=http://username:password@proxyserver.example.com:80
set HTTPS_PROXY=http://username:password@proxyserver.example.com:80

Show lessSee more

Scroll to top

使用 Web 浏览器进行联合身份验证/SSO¶

To use browser-based SSO authentication for SnowSQL, add --authenticator externalbrowser to your SnowSQL connection parameters:

例如：

Copy codeExpand code block

$ snowsql -a <account_identifier> -u <username> --authenticator externalbrowser

Show lessSee more

Scroll to top

For more information about federated authentication/SSO, see Managing/Using federated authentication.

验证 OCSP 连接器或驱动程序版本¶

Snowflake uses OCSP to evaluate the certificate chain when making a connection to Snowflake. The driver or connector version and its configuration both determine the OCSP behavior. For more information about the driver or connector version, their configuration, and OCSP behavior, see OCSP Configuration.

OCSP 响应缓存服务器¶

连接错误处理

Cannot open self /usr/bin/snowsql or archive /usr/bin/snowsql.pkg (Linux Only)

Due to a limitation in pyinstaller (the program that packages SnowSQL into a stand-alone executable from Python source code), prelink mistakenly strips parts of the snowsql executable and causes this error.

To avoid this issue, the SnowSQL installer attempts to update the prelink configuration file in /etc/prelink.conf.d/snowsql.conf for the snowsql executable such that prelink does not alter the file. Unfortunately, this configuration update cannot be made by the SnowSQL auto-upgrade process.

请与系统管理员合作，在您的工作站上运行以下命令：

Copy codeExpand code block

$ sudo bash -c "echo '-b snowsql' > /etc/prelink.conf.d/snowsql.conf"

Show lessSee more

Scroll to top

连接参数参考

-a , --accountname¶

Description:

Required

Specifies your account identifier. Specify the account identifier in this form: organization_name-account_name (for example, myorganization-myaccount).

For instructions on finding the account identifier, see Configuring a client, driver, library, or third-party application to connect to Snowflake.

This connection parameter can also be set in the configuration file.

Value:

字符串

值也可以是环境变量：

Linux/macOS:

$SNOWSQL_ACCOUNT

Windows:

%SNOWSQL_ACCOUNT%

例如，在 Linux 或 macOS 中：

Copy codeExpand code block

$ export SNOWSQL_ACCOUNT=myorganization-myaccount

$ snowsql -a $SNOWSQL_ACCOUNT

Show lessSee more

Scroll to top

Default:

无

-u , --username¶

Description:

指定用于连接到指定账户的用户的登录名。

This connection parameter can also be set in the configuration file.

Value:

字符串

值可以是环境变量：

Linux/macOS:

$SNOWSQL_USER

Windows:

%SNOWSQL_USER%

例如，在 Linux 或 macOS 中：

Copy codeExpand code block

$ export SNOWSQL_USER=jdoe

$ snowsql -u $SNOWSQL_USER

Show lessSee more

Scroll to top

Default:

无

-d , --dbname¶

Description:

指定客户端会话中默认使用的数据库（登录后可以更改）。

Value:

字符串

值可以是环境变量：

Linux/macOS:

$SNOWSQL_DATABASE

Windows:

%SNOWSQL_DATABASE%

This connection parameter can also be set in the configuration file.

Default:

无

-s , --schemaname¶

Description:

指定客户端会话中默认使用的数据库架构（登录后可以更改）。

Value:

字符串

值可以是环境变量：

Linux/macOS:

$SNOWSQL_SCHEMA

Windows:

%SNOWSQL_SCHEMA%

This connection parameter can also be set in the configuration file.

Default:

无

-r , --rolename¶

Description:

指定客户端会话中默认用于访问 Snowflake 对象的角色（登录后可以更改）。

This connection parameter can also be set in the configuration file.

Value:

字符串

值可以是环境变量：

Linux/macOS:

$SNOWSQL_ROLE

Windows:

%SNOWSQL_ROLE%

Default:

无

-w , --warehouse¶

Description:

指定客户端会话中默认用于查询、加载等操作的虚拟仓库（登录后可以更改）。

This connection parameter can also be set in the configuration file.

Value:

字符串

值可以是环境变量：

Linux/macOS:

$SNOWSQL_WAREHOUSE

Windows:

%SNOWSQL_WAREHOUSE%

Default:

无

-h , --host — Deprecated¶

Description:

Provided for backward compatibility/internal use

指定您在 Snowflake 中连接的主机的地址。

This parameter is no longer used because the host address is determined automatically by concatenating the account identifier you specified (using either -a or --account) and the Snowflake domain (snowflakecomputing.cn).

Value:

字符串

Default:

无

-p , --port — Deprecated¶

Description:

Provided for backward compatibility/internal use

指定用于连接的端口号。

This parameter is no longer used because the port number for Snowflake is always 443.

Value:

字符串

Default:

无

--region — Deprecated¶

Description:

Provided for backward compatibility/internal use

Specifies the ID for the region where your account is located.

This parameter is no longer used. For more details, see , (in this topic).

Value:

不适用

Default:

不适用

-m , --mfa-passcode¶

Description:

指定 MFA（多重身份验证）的第二个令牌（如果您在命令行中传入密码）。

Value:

字符串

Default:

无

--mfa-passcode-in-password¶

Description:

在密码末尾追加 MFA 密码。

You can force the password prompt and type the password followed by the MFA passcode. For example if the MFA token was 123456 and the password was PASSWORD:

Copy codeExpand code block

$ snowsql ... -P ...

Password: PASSWORD123456

Show lessSee more

Scroll to top

Value:

不适用（参数不带值）

Default:

不适用

--abort-detached-query¶

Description:

如果客户端和服务器之间的连接丢失，则中止查询。

Value:

布尔

Default:

False（即，如果连接丢失，活动的查询不会中止）

--probe-connection¶

Description:

测试与 Snowflake 的连接并报告结果。请注意，这是一个试验性选项，主要用于打印出 TLS 证书链。

Value:

不适用（参数不带值）

Default:

不适用

--authenticator¶

Description:

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

Value:

字符串（常量）：

• snowflake uses the internal Snowflake authenticator.
• externalbrowser uses your web browser to authenticate with Okta, AD FS, or any other SAML 2.0-compliant identity provider (IdP) that has been defined for your account.
• https://<okta_account_name>.okta.com (i.e. the URL endpoint for Okta) authenticates through native Okta (only supported if your IdP is Okta).
• oauth authenticates using OAuth. When OAuth is specified as the authenticator, you must also set the --token parameter to specify the OAuth token (see below).

For more information, see Managing/Using federated authentication and Clients, drivers, and connectors.

Default:

snowflake

Note

The externalbrowser authenticator is only supported in terminal windows that have web browser access. For example, a terminal window on a remote machine accessed through a SSH (Secure Shell) session may require additional setup to open a web browser.

If you don’t have access to a web browser, but your IdP is Okta, you can use native Okta (i.e. set the authenticator to https://<okta_account_name>.okta.com).

--token¶

Description:

Specifies the OAuth token to use for authentication. This parameter is required only when you specify --authenticator=oauth.

Value:

字符串

Default:

无

-v , --version¶

Description:

使用指定的 SnowSQL 版本，或者，如果未指定版本，则显示已安装的最新 SnowSQL 版本。

Value:

字符串

Default:

无

--versions¶

Description:

Lists all available versions of SnowSQL that can be installed and run. To install an earlier SnowSQL version from the list, use the -v option and specify the version you want to install.

Value:

不适用（参数不带值）

Default:

不适用

--noup¶

Description:

本次运行禁止自动升级。如果未包含此选项，并且有更新的版本可用， SnowSQL 会自动下载并安装新版本。下次运行 SnowSQL 时会使用新版本。

Value:

不适用（参数不带值）

Default:

不适用

-D , --variable¶

Description:

在命令行上定义 SnowSQL 变量。此选项可用于设置要在 Snowflake 中使用的特定变量。

Value:

字符串

例如：

Copy codeExpand code block

$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=$DB_KEY ...

Show lessSee more

Scroll to top

Default:

无

-o , --option¶

Description:

Defines SnowSQL configuration options on the command line. These options override any options that have been set in the SnowSQL configuration file. For descriptions of the options you can set/override, see SnowSQL configuration options reference.

Value:

字符串

Default:

无

-f , --filename¶

Description:

指定要以批处理模式执行的 SQL 文件。

值可以是文件名（如果需要，包含目录路径）或文件的 URL。

Value:

字符串

Default:

无

-q , --query¶

Description:

指定要执行的 SQL 查询。

The value can be a single SQL query or a semicolon-separated list of queries to execute (e.g. 'select current_user(); select current_role()').

You can also specify multiple queries to run asynchronously by separating the queries with ;>. The following example starts SnowSQL and runs all four queries asynchronously:

snowsql -o log_level=DEBUG -q "select * from SNOWSQLTABLE;> insert into table table1 values(2);> select 5;>select count(*) from testtable;"

Value:

字符串

Default:

无

--query_tag¶

Description:

指定运行查询时使用的标签。

值可以是单个标签，或是以分号分隔的标签列表。

Value:

字符串

Default:

Value of the SNOWSQL_QUERY_TAG environment variable.

--config¶

Description:

指定 SnowSQL 配置文件的位置（即目录路径）。如果要从默认位置移动或复制配置文件，请包含此连接器参数。

Value:

字符串

Default:

特定于 OS：

Linux/macOS:

~/.snowsql/

Windows:

%USERPROFILE%\.snowsql\

-P , --prompt¶

Description:

强制显示交互式密码提示。

默认情况下，SnowSQL 使用存储在 $SNOWSQL_PWD 环境变量中的密码。使用此选项允许您替换在 $SNOWSQL_PWD 中定义的密码。

Value:

不适用（参数不带值）

Default:

不适用

-M, --mfa-prompt¶

Description:

Forces a prompt for the second token for MFA. Alternatively use --mfa-passcode <string> if you want to pass in to the command line.

Value:

不适用（参数不带值）

Default:

不适用

-c , --connection¶

Description:

Specifies a connection to use, where the specified string is the name of a connection defined in the SnowSQL configuration file. For more details, see 使用命名连接 (in this topic).

Value:

字符串

Default:

无

--single-transaction¶

Description:

Combined with --filename, --query, or standard input commands, this option wraps BEGIN/COMMIT around the statements to ensure all commands complete successfully or no change is applied.

Value:

不适用（参数不带值）

Default:

不适用

Note

请注意，如果输入命令使用 BEGIN、COMMIT 或者 ROLLBACK，此选项将无法正常工作。此外，如果任何命令无法在事务块内执行，此选项将导致命令失败。

--private-key-path¶

Description:

私钥文件的路径。

Caution

虽然支持未加密的私钥，但 Snowflake 强烈建议在连接到 Snowflake 时使用加密的私钥。

For more information, see Using Key Pair Authentication & Key Pair Rotation.

This connection parameter can also be set in the configuration file.

Value:

字符串

Default:

无

--disable-request-pooling¶

Description:

默认情况下，SnowSQL 使用连接池。连接池通常可减少建立连接的滞后时间。但是，如果出现 DNS 问题，连接池可能会减慢将客户端故障转移到备选 DNS 的速度。该参数允许您关闭连接池。

This parameter applies only to customers who have replication enabled.

Value:

不适用（参数不带值）

Default:

不适用

-U , --upgrade¶

Description:

如果本地目录中未下载最新版本，则强制将 SnowSQL 升级到最新版本。

Value:

不适用（参数不带值）

Default:

不适用

Note

需要 SnowSQL 1.1.63 或更新版本的引导程序可执行文件。可通过 UI 下载它。

-K , --client-session-keep-alive¶

Description:

即使用户没有进行任何活动，也让会话无限期地处于活动状态。

Value:

不适用（参数不带值）

Default:

不适用

--include_connector_version¶

Description:

显示以 SnowSQL 二进制打包的 Snowflake Connector for Python 软件的版本。

Value:

不适用（参数不带值）

Default:

不适用

-? , --help¶

Description:

显示命令行快速使用指南。

Value:

不适用（参数不带值）

Default:

不适用