配置 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 = accountname
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 statments 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 配置文件¶
要修改配置文件，请执行以下操作：
在文本编辑器中，打开 SnowSQL 配置文件（名为
config）。该文件的默认位置是：- Linux/macOS:
~/.snowsql/- Windows:
%USERPROFILE%\.snowsql\
备注
启动 SnowSQL 时，可以指定
--config path命令行标志来更改默认位置。修改以下部分中的设置：
注意
密码以明文形式存储在
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 文件的 [variables] 部分中，可以将值存储为变量以供重用。此功能使您能够在查询中使用用户定义值和数据库值。
有关更多信息，请参阅 使用变量。
SnowSQL 配置选项参考¶
选项修改默认 SnowSQL 行为。您可以使用以下任一方法设置这些选项：
备注
选项名称和值不区分大小写。
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
header¶
- 类型:
布尔
- 描述:
显示 SnowSQL 呈现的结果表中的标题。当您希望在结果中仅检索数据时，禁用此选项非常有用。
可以与
output_format和timing结合使用来生成纯数据输出。- 默认值:
header=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=False
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