配置 SnowSQL

本文介绍如何使用连接参数、配置选项和变量配置 SnowSQL。

关于 SnowSQL config 文件

SnowSQL 支持多个配置文件，允许组织定义连接参数、默认设置和变量的基本值，同时允许个人用户在自己的 <HOME_DIR>/.snowsql/config 文件中自定义其个人设置。当 SnowSQL 启动时，它会按顺序从以下配置文件位置加载配置参数值，覆盖之前加载的文件中的值：

  • /etc/snowsql.cnf

  • /etc/snowflake/snowsql.cnf

  • /usr/local/etc/snowsql.cnf

  • <HOME_DIR>/.snowsql.cnf （仅支持向后兼容）

  • <HOME_DIR>/.snowsql/config

例如，如果 /etc/snowsql.cnf 配置文件将 log_level 参数设置为 info，您可以通过在 <HOME_DIR>/.snowsql/config 文件中将参数设置为 debug 来替换此设置。

首次执行 snowsql 命令时，该命令会生成类似于以下内容的配置文件。

[connections]
# *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*
#
# The Snowflake user password is stored in plain text in this file.
# Pay special attention to the management of this file.
# Thank you.
#
# *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*

#If a connection doesn't specify a value, it will default to these
#
#accountname = defaultaccount
#region = defaultregion
#username = defaultuser
#password = defaultpassword
#dbname = defaultdbname
#schemaname = defaultschema
#warehousename = defaultwarehouse
#rolename = defaultrolename
#proxy_host = defaultproxyhost
#proxy_port = defaultproxyport

[connections.example]
#Can be used in SnowSql as #connect example

accountname = my_organization-my_account
username = username
password = password1234

[variables]
# SnowSQL defines the variables in this section on startup.
# You can use these variables in SQL statements. For details, see
# https://docs.snowflake.com/en/user-guide/snowsql-use.html#using-variables

# example_variable=27

[options]
# If set to false auto-completion will not occur interactive mode.
auto_completion = True

# main log file location. The file includes the log from SnowSQL main
# executable.
log_file = ~/.snowsql/log

# bootstrap log file location. The file includes the log from SnowSQL bootstrap
# executable.
# log_bootstrap_file = ~/.snowsql/log_bootstrap

# Default log level. Possible values: "CRITICAL", "ERROR", "WARNING", "INFO"
# and "DEBUG".
log_level = INFO

# Timing of sql statements and table rendering.
timing = True

# Table format. Possible values: psql, plain, simple, grid, fancy_grid, pipe,
# orgtbl, rst, mediawiki, html, latex, latex_booktabs, tsv.
# Recommended: psql, fancy_grid and grid.
output_format = psql

# Keybindings: Possible values: emacs, vi.
# Emacs mode: Ctrl-A is home, Ctrl-E is end. All emacs keybindings are available in the REPL.
# When Vi mode is enabled you can use modal editing features offered by Vi in the REPL.
key_bindings = emacs

# OCSP Fail Open Mode.
# The only OCSP scenario which will lead to connection failure would be OCSP response with a
# revoked status. Any other errors or in the OCSP module will not raise an error.
# ocsp_fail_open = True

# Enable temporary credential file for Linux users
# For Linux users, since there are no OS-key-store, an unsecure temporary credential for SSO can be enabled by this option. The default value for this option is False.
# client_store_temporary_credential = True

# Select statement split method (default is to use the sql_split method in snowsql, which does not support 'sql_delimiter')
# sql_split = snowflake.connector.util_text # to use connector's statement_split which has legacy support to 'sql_delimiter'.

# Force the result data to be decoded in utf-8. By default the value is set to false for compatibility with legacy data. It is recommended to set the value to true.
# json_result_force_utf8_decoding = False

您应该使用 UTF-8 编码创建这些配置文件。

修改 SnowSQL 配置文件

要修改配置文件，请执行以下操作：

  1. 在文本编辑器中，打开 SnowSQL 配置文件（名为 config）。该文件的默认位置是：

    Linux/macOS:

    ~/.snowsql/

    Windows:

    %USERPROFILE%\.snowsql\

    备注

    启动 SnowSQL 时，可以指定 --config path 命令行标志来更改默认位置。

  2. 修改以下部分中的设置：

注意

  • 密码以明文形式存储在 config 文件中。您必须显式保护该文件，以限制访问。例如，在 Linux 或 macOS 中，可以运行 chmod，以设定只有您具有读取权限：

    $ chmod 700 ~/.snowsql/config

备注

  • 如果值包含特殊字符（单引号或双引号除外），则必须将其括在单引号或双引号中，例如：

    password = "my$^pwd"

  • 如果值 除了 其他特殊字符外还包含引号字符，请使用反斜杠 (\) 字符转义这些引号，例如：

    password = "my$^\"\'pwd"

    请注意，在未封闭的值（即不包含其他特殊字符的值）中，转义引号字符是可选的。

  • 多行值必须用三个单引号或双引号（''' 或 """）括起来，例如：

    prompt_format='''[#FFFF00][user]@[account]
[#00FF00]> '''

“连接参数”部分

在 config 文件的 [connections] 部分中，可以选择设置 SnowSQL 的默认连接参数，例如账户标识符、用户登录凭据以及默认数据库和仓库。您还可以定义 命名 连接，以便同时建立与 Snowflake 的多个连接或存储多组不同的连接配置。

有关更多信息，请参阅 通过 SnowSQL 进行连接。

“配置选项”部分

通过在 config 文件的 [options] 部分添加设置来配置 SnowSQL 的行为：

[options]
<option_name> = <option_value>

其中：

  • <option_name> 是选项的名称（不区分大小写）。如果指定了无效的名称， SnowSQL 则显示错误。

  • <option_value> 指定选项支持的值（不区分大小写），如下所述。

+----------------------------+---------------------+------------------------------------------------------------------------------------+
| Name                       | Value               | Help                                                                               |
+----------------------------+---------------------+------------------------------------------------------------------------------------+
| auto_completion            | True                | Displays auto-completion suggestions for commands and Snowflake objects.           |
| client_session_keep_alive  | False               | Keeps the session active indefinitely, even if there is no activity from the user. |
| echo                       | False               | Outputs the SQL command to the terminal when it is executed.                       |
| editor                     | vim                 | Changes the editor to use for the !edit command.                                   |
| empty_for_null_in_tsv      | False               | Outputs an empty string for NULL values in TSV format.                             |
| environment_variables      | ['PATH']            | Specifies the environment variables that can be referenced as SnowSQL variables.   |
|                            |                     | The variable names should be comma separated.                                      |
| execution_only             | False               | Executes queries only.                                                             |
| exit_on_error              | False               | Quits when SnowSQL encounters an error.                                            |
| fix_parameter_precedence   | True                | Controls the precedence of the environment variable and the config file entries    |
|                            |                     | for password, proxy password, and private key phrase.                              |
| force_put_overwrite        | False               | Force PUT command to stage data files without checking whether already exists.     |
| friendly                   | True                | Shows the splash text and goodbye messages.                                        |
| header                     | True                | Outputs the header in query results.                                               |
| insecure_mode              | False               | Turns off OCSP certificate checks.                                                 |
| key_bindings               | emacs               | Changes keybindings for navigating the prompt to emacs or vi.                      |
| log_bootstrap_file         | ~/.snowsql/log_...  | SnowSQL bootstrap log file location.                                               |
| log_file                   | ~/.snowsql/log      | SnowSQL main log file location.                                                    |
| log_level                  | CRITICAL            | Changes the log level (critical, debug, info, error, warning).                     |
| login_timeout              | 120                 | Login timeout in seconds.                                                          |
| noup                       | False               | Turns off auto upgrading SnowSQL.                                                  |
| output_file                | None                | Writes output to the specified file in addition to the terminal.                   |
| output_format              | psql                | Sets the output format for query results.                                          |
| paging                     | False               | Enables paging to pause output per screen height.                                  |
| progress_bar               | True                | Shows progress bar while transferring data.                                        |
| prompt_format              | [user]#[warehou...] | Sets the prompt format. Experimental feature, currently not documented.            |
| sfqid                      | False               | Turns on/off Snowflake query id in the summary.                                    |
| sfqid_in_error             | False               | Turns on/off Snowflake query id in the error message.                              |
| quiet                      | False               | Hides all output.                                                                  |
| remove_comments            | False               | Removes comments before sending query to Snowflake.                                |
| remove_trailing_semicolons | True                | Removes trailing semicolons from SQL text before sending queries to Snowflake.     |
| results                    | True                | If set to off, queries will be sent asynchronously, but no results will be fetched.|
|                            |                     | Use !queries to check the status.                                                  |
| rowset_size                | 1000                | Sets the size of rowsets to fetch from the server.                                 |
|                            |                     | Set the option low for smooth output, high for fast output.                        |
| stop_on_error              | False               | Stops all queries yet to run when SnowSQL encounters an error.                     |
| syntax_style               | default             | Sets the colors for the text of SnowSQL.                                           |
| timing                     | True                | Turns on/off timing for each query.                                                |
| timing_in_output_file      | False               | Includes timing in the output file.                                                |
| variable_substitution      | False               | Substitutes variables (starting with '&') with values.                             |
| version                    | 1.1.70              | Returns SnowSQL version.                                                           |
| wrap                       | True                | Truncates lines at the width of the terminal screen.                               |
+----------------------------+---------------------+------------------------------------------------------------------------------------+

有关所有有效选项的说明，请参阅 SnowSQL 配置选项参考 （本主题内容）。

备注

除了在 config 文件中设置配置选项外，还可以使用以下任一方法设置选项：

  • 连接到 Snowflake 时，可以使用 -o 或 --option 连接参数来设置这些选项。有关更多信息，请参阅 连接参数参考。

  • 连接到 Snowflake 后，您可以使用 !set 命令为会话设置这些选项。有关更多信息，请参阅 命令参考。

“变量”部分

在 config 文件的 [variables] 部分中，可以将值存储为变量以供重用。此功能使您能够在查询中使用用户定义值和数据库值。

有关更多信息，请参阅 使用变量。

SnowSQL 配置选项参考

选项修改默认 SnowSQL 行为。您可以使用以下任一方法设置这些选项：

  • 在 配置文件 中（如本主题中所述）。

  • 连接到 Snowflake 时，使用 -o 或 --option 参数。

  • 连接到 Snowflake 后，使用 !set 命令。

备注

选项名称和值不区分大小写。

auto_completion

类型:

布尔

描述:

启用上下文相关自动补全。如果启用，存储在 SnowSQL 中的函数、表名和变量在交互模式下自动补全。

默认值:

auto_completion=True

client_session_keep_alive

类型:

布尔

描述:

指示是否强制用户在 JDBC 或 ODBC 会话处于非活动状态一段时间后再次登录。设置为 True 时，Snowflake 会无限期地保持会话处于活动状态，即使用户没有活动也是如此。设置为 False 时，用户必须在闲置 4 小时后重新登录。

默认值:

client_session_keep_alive=False

echo

类型:

布尔

描述:

回显本地输入。当设置为 True 时，会回显到 stdout 和输出文件。

默认值:

echo=False

editor

类型:

字符串（常量）

描述:

指定在 SnowSQL 中发出 !edit 命令时要调用的编辑器。支持的值：

  • emacs

  • vi

  • vim

默认值:

editor=vim

empty_for_null_in_tsv

类型:

布尔

描述:

如果启用，当 output_format 设置为 TSV 时， SnowSQL 会为每个 NULL 值输出一个空字符串。

示例:

empty_for_null_in_tsv=True

environment_variables

类型:

列表

描述:

指定要在 SnowSQL 变量中设置的环境变量。

示例:

environment_variables=PATH,USER,AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY

execution_only

类型:

布尔

描述:

如果启用， SnowSQL 将执行查询而不提取数据。当您只想测量执行时间时，此选项非常有用。请注意，返回的值包括任何网络延迟，而不是纯粹的服务器端执行时间。

示例:

execution_only=True

exit_on_error

类型:

布尔

描述:

如果启用， SnowSQL 将在发生错误时退出。此行为对于在遇到错误时停止运行查询非常有用。

示例:

exit_on_error=True

fix_parameter_precedence

类型:

布尔

描述:

控制密码、代理密码和私钥短语参数的可能来源之间的优先级。

如果值为 True，则优先级（从最高到最低）为：

  • 环境变量或 SnowSQL 命令行参数。

  • 特定于连接的连接参数，即配置文件的命名连接部分中的参数，例如 [connections.myconnection] 部分。

  • 默认连接参数，即配置文件的 [connections] 部分中的参数。

如果值为 False，则优先级（从最高到最低）为：

  • 特定于连接的连接参数，即配置文件的命名连接部分中的参数，例如 [connections.myconnection] 部分。

  • 环境变量或 SnowSQL 命令行参数。

  • 默认连接参数，即配置文件的 [connections] 部分中的参数。

默认值:

True

force_put_overwrite

类型:

布尔

描述:

如果启用， SnowSQL 会强制 PUT 命令将数据文件从客户端计算机上的本地目录/文件夹上传（即暂存）到指定的内部（即 Snowflake）暂存区，而不检查暂存区中是否已存在文件。如果文件已存在于目标暂存区，则 PUT 命令将覆盖现有文件。

默认值:

force_put_overwrite=False

friendly

类型:

布尔

描述:

如果禁用， SnowSQL 会禁止显示启动和退出消息。

默认值:

friendly=True

insecure_mode

类型:

布尔

描述:

使用联机证书状态协议 (OCSP) 跳过证书吊销检查。此选项可用于无法访问 OCSP 服务的紧急情况。Snowflake 强烈建议您 不要 启用此选项，除非有 Snowflake 支持人员的指示。

默认值:

insecure_mode=False

key_bindings

类型:

字符串（常量）

描述:

要使用的键绑定。可能的值如下：

  • emacs：CTRL + a 是 home，CTRL + e 是 end。REPL 环境的所有 Emacs 键绑定均可用。

  • vi：您可以在 REPL 环境中使用 vi 提供的所有模式编辑功能。

备注:

在 SnowSQL 会话期间无法通过 !set 命令更改该值。相反，在连接到 Snowflake 时，请在配置文件或命令行中设置值。

默认值:

key_bindings=vi

log_bootstrap_file

类型:

字符串（路径）

描述:

引导日志文件位置。如果未指定，则使用 log_file 作为基本名称，后跟 _bootstrap。例如，默认情况下，日志文件名为 log_bootstrap。

默认值:

log_bootstrap_file=~/.snowsql/bootlog

log_file

类型:

字符串（路径）

描述:

log_file 位置。

备注

您必须有权写入日志文件的父目录或修改日志文件的位置。

默认值:

log_file=~/.snowsql/log

log_level

类型:

字符串（常量）

描述:

默认日志级别。可能的值： CRITICAL、 ERROR、 WARNING、 INFO、 DEBUG。

login_timeout

类型:

数字

描述:

登录超时（以秒为单位）。

默认值:

login_timeout=120

noup

类型:

布尔

描述:

如果为 True，则阻止 SnowSQL 下载和安装新版本。默认情况下，如果未指定版本， SnowSQL 会自动升级到最新版本。

默认值:

noup=True

output_file

类型:

字符串（路径和文件名）

描述:

除终端输出外，还将输出写入指定文件。

默认值:

无

output_format

类型:

字符串（常量）

描述:

指定终端中显示的结果的格式。可能的值如下：

  • csv

  • expanded

  • fancy_grid

  • grid

  • html

  • json

  • latex

  • latex_booktabs

  • mediawiki

  • orgtbl

  • pipe

  • plain

  • psql

  • rst

  • simple

  • tsv

表格结果的建议值：psql、grid 或 fancy_grid

仅数据结果的建议值（与 header、timing 结合使用并将 friendly 设置为 False）：plain、csv 或 tsv

默认值:

output_format=psql

paging

类型:

布尔

描述:

启用后，按屏幕高度暂停输出。此功能对于浏览大型结果集非常有用。要向下滚动，请按 [ENTER]/[RETURN] 键。

默认值:

paging=False

progress_bar

类型:

布尔

描述:

传输数据时显示进度条。

默认值:

progress_bar=True

prompt_format

类型:

字符串

描述:

更改 SnowSQL 提示格式。

默认情况下， SnowSQL 提示会动态显示当前用户、仓库、数据库和架构。动态令牌写为 [<token>]，例如 [user] 或 [warehouse]。您可以更改 Snowflake 对象顺序、分隔符和颜色。通过在括号中定义 pygments 标记来更改对象颜色。

例如，将对象顺序更改为用户、数据库和架构，然后是仓库。将分隔符更改为句点。将 [user] 对象名称更改为红色，将 [database] 和 [schema] 名称更改为绿色，将 [warehouse] 名称更改为蓝色：

prompt_format="[#FF0000][user]@[#00FF00][database][schema][#0000FF][warehouse]"

在值两边加上引号，以防止“#”字符被解释为注释的开头。

默认值:

None

quiet

类型:

布尔

描述:

从终端中删除所有输出数据，但继续显示错误消息和诊断数据。

默认值:

quiet=True

remove_comments

类型:

布尔

描述:

从输出中删除注释。

默认值:

remove_comments=False

remove_trailing_semicolons

类型:

布尔

描述:

在向 Snowflake 发送查询之前，从 SQL 文本中删除尾随分号。请注意，在启用 USE_CACHED_RESULT 会话参数时，删除分号可以防止 Snowflake 使用来自不同客户端的缓存结果。

默认值:

remove_trailing_semicolons=True

results

类型:

布尔

描述:

返回查询结果。如果为 False，则异步执行查询，不返回任何结果（包括任何错误消息）。

默认值:

results=True

rowset_size

类型:

数字

描述:

在交互模式下一次提取的行数。然后，一次提取一个行集的输出结果。

默认值:

rowset_size=1000

sfqid

类型:

布尔

描述:

在结果摘要中包括 Snowflake 查询 ID。

注意：您还必须设置 timing_in_output_file=True，以将 sqfid 添加到假脱机文件中。

默认值:

sfqid=False

sfqid_in_error

类型:

布尔

描述:

在错误消息中包括 Snowflake 查询 ID。

默认值:

sfqid_in_error=False

stop_on_error

类型:

布尔

描述:

遇到错误时，将停止查询执行，但不会退出。

默认值:

stop_on_error=False

syntax_style

类型:

字符串（常量）

描述:

设置 SnowSQL 的文本颜色。目前，唯一支持的值是 default。

默认值:

syntax_style=default

timing

类型:

布尔

描述:

指定是否显示已执行的 SQL 语句生成的行数和运行时间。此信息在 SnowSQL 呈现的结果表下显示为一行文本。如果设置为 False，则不显示结果表下的文本行。

可以与 header 和 output_format 结合使用来生成纯数据输出。

默认值:

timing=True

timing_in_output_file

类型:

布尔

描述:

如果配置了 output_file 选项，则指定是否在输出文件中包含执行时间详细信息。还需要将 timing 选项设置为 True。

如果设置为 False，则输出文件中不包括结果表下的文本行。

默认值:

timing_in_output_file=False

variable_substitution

类型:

布尔

描述:

将变量替换为值。请参阅 使用变量。

默认值:

variable_substitution=False

wrap

类型:

布尔

描述:

按端子宽度包装输出。如果为 False，则输出被截断。

默认值:

wrap=True