这是本节的多页打印视图。点击此处打印.

使用 vsql

1: 安装 vsql 客户端
2: Windows 上的 vsql 用法
3: 从管理工具进行连接
4: 从命令行进行连接

4.1: 命令行选项

4.1.1: -A --no-align
4.1.2: -a --echo-all
4.1.3: -c --command
4.1.4: -d --dbname
4.1.5: -E
4.1.6: -e --echo-queries
4.1.7: -F --field-separator
4.1.8: -f --file
4.1.9: ？--help
4.1.10: -H --html
4.1.11: -h --host
4.1.12: -i -- timing
4.1.13: -l --list
4.1.14: -m --sslmode
4.1.15: -n
4.1.16: -o --output
4.1.17: -P --pset
4.1.18: -p --port
4.1.19: -q --quiet
4.1.20: -R --record-separator
4.1.21: -S --single-line
4.1.22: -s --single-step
4.1.23: -T --table-attr
4.1.24: -t --tuples-only
4.1.25: -V --version
4.1.26: -v --variable --set
4.1.27: -X --no-vsqlrc
4.1.28: -x --expanded

4.2: 从非群集主机进行连接

5: 元命令

5.1: 元命令快速参考
5.2: \connect
5.3: \d 元命令
5.4: \edit
5.5: \i
5.6: \locale
5.7: \pset
5.8: \set
5.9: \timing

6: 变量

6.1: AUTOCOMMIT
6.2: DBNAME
6.3: ECHO
6.4: ECHO_HIDDEN
6.5: ENCODING
6.6: HISTCONTROL
6.7: HISTSIZE
6.8: 主机
6.9: IGNOREEOF
6.10: ON_ERROR_STOP
6.11: PORT
6.12: PROMPT1 PROMPT2 PROMPT3
6.13: QUIET
6.14: ROWS_AT_A_TIME
6.15: SINGLELINE
6.16: SINGLESTEP
6.17: 用户
6.18: VERBOSITY
6.19: VSQL_HOME
6.20: VSQL_SSLMODE

7: 提示
8: 命令行编辑
9: vsql 环境变量
10: 区域设置
11: 使用 vsql 输入数据
12: 文件
13: 使用 vsql 导出数据
14: 使用 vsql 复制数据
15: 输出格式设置示例

vsql 是一种基于字符的交互式前端实用程序，使用它可以键入 SQL 语句并查看结果。它还提供了许多元命令及各种类似于 shell 的功能，有助于编写脚本和自动执行各种任务。

如果使用的是已安装在服务器上的 vsql 客户端，则您可以从以下位置进行连接：

您也可以为其他受支持的平台安装 vsql 客户端。

一般注释

为清晰起见，SQL 语句可以分布到多个行。
vsql 可以处理采用 UTF-8 编码的输入和输出。必须对运行 vsql 的终端模拟器进行设置，使其正确显示 UTF-8 字符。以下示例显示了 PuTTy 中的设置：

另请参阅使用区域设置的最佳实践。
通过按 Ctrl+C 取消 SQL 语句。
通过按 Ctrl+R 遍历命令历史记录。
断开用户会话的连接时，任何正在进行的事务会自动回退。
若要查看广泛的结果集，请使用 Linux less 实用程序截断较长的行。
1. 连接到数据库之前，指定您要将 less 用于查询输出：
```
$ export PAGER=less
```
2. 连接到数据库。
3. 查询宽表：
```
=> select * from wide_table;
```
4. 在 less 提示符中，键入：
```
-S
```
如果运行 vsql 的 shell 失败（崩溃或冻结），则 vsql 进程会继续运行，即使您停止数据库也是如此。在这种情况下，可使用 root 身份登录到正在运行 shell 的计算机，手动停止 vsql 进程。例如： # ps -ef | grep vertica

fred 2401 1 0 06:02 pts/1 00:00:00 /opt/vertica/bin/vsql -p 5433 -h test01_site01 quick_start_single

ill -9 2401

1 - 安装 vsql 客户端

本页介绍非 FIPS 安装。要在符合 FIPS 的系统上安装，请参阅为 ODBC 和 vsql 安装 FIPS 客户端驱动程序。

Linux 和 macOS

注意

对于 Linux：vsql 客户端自动作为 Vertica 服务器 .rpm 的一部分安装。

要在另一个系统上手动安装 vsql：

下载 vsql。
解压缩或安装 vsql：
- 如果您下载了 .tar，则创建 /opt/vertica/ 目录（如果该目录不存在），将 .tar 复制到其中，导航到它，然后解压缩 .tar：
```
$ mkdir -p /opt/vertica/
$ cp driver_name.tar.gz /opt/vertica/
$ tar vzxf driver_name.tar.gz
```
- 如果您下载了 .rpm，请使用以下命令安装它：
```
$ rpm -Uvh driver_name.rpm
```
可以选择将 vsql 目录添加到您的 PATH 中。例如：
```
$ export PATH=$PATH:\opt\vertica\bin
```
使 vsql 客户端可执行。例如，要允许所有用户运行 vsql：
```
$ chmod ugo+x /path/to/vsql
```
将 shell 区域设置设置为受 vsql 支持的区域设置（哪些？）。例如，在 .profile 中添加：
```
export LANG=end_US.UTF-8
```

Windows

要安装 vsql 客户端：

下载 Windows 客户端驱动安装程序。有关此安装程序中包含的驱动程序的详细信息，请参阅 Windows 客户端驱动程序安装程序。
运行安装程序并按照提示安装驱动程序。
重新启动系统。

安装驱动程序后，您可以选择将 vsql 目录添加到 PATH。例如，要针对当前会话使用 Windows PowerShell 将 vsql 目录附加到 PATH：

PS C:\> $Env:PATH += ";C:\Program Files\Vertica Systems\VSQL64\"

您可以通过运行 vsql -? 来验证 vsql 目录是否在您的 PATH 中：

PS C:\> vsql -?
This is vsql, the Vertica Analytic Database interactive terminal.

Usage:
  vsql [OPTIONS]... [DBNAME [USERNAME]]

有关用法的详细信息，请参阅 Windows 上的 vsql 用法

2 - Windows 上的 vsql 用法

字体

默认光栅字体无法正常与 ANSI 代码页配合工作。请将控制台字体设置为“Lucida Console”。

控制台编码

vsql 构建为“控制台应用程序”。Windows 控制台窗口使用与其他系统不同的编码，因此请谨慎在 vsql 中使用 8 位字符。如果 vsql 检测到有问题的控制台代码页，它会向您发出警告。

若要更改控制台代码页，请输入 cmd.exe /c chcp 1252 以设置代码页。

注意

1252 是一种适用于欧洲语言的代码页。请将其替换为您的首选区域设置代码页。

在 cygwin 下运行

验证 cygwin.bat 文件是否不包含“tty”标记。如果 cygwin.bat 文件包含“tty”标记，则 vsql 中会显示横幅和提示。

若要进行验证，请输入以下命令：

set CYGWIN=binmode tty ntsec

若要移除“tty”标记，请输入以下命令：

set CYGWIN=binmode ntsec

此外，在 Cygwin 下运行时，vsql 使用与 Windows 控制台约定相反的 Cygwin shell 约定。

Tab 自动补全

Tab 自动补全是 shell 的一项功能，而非 vsql 的一项功能。因此，Tab 自动补全在 Windows vsql 中的工作方式与在 Linux 版本的 vsql 中不同。

在 Windows 上，按 F7 可弹出命令的历史记录窗口，而非使用 Tab 自动补全。您也可以在键入命令的几个字母后按 F8，以在历史记录缓冲区中以相同字母开头的命令中循环。

3 - 从管理工具进行连接

可以使用管理工具从群集中的任何节点通过 vsql 连接到数据库。

以数据库管理员用户身份登录；例如 dbadmin。

注意
出于安全原因，Vertica 不允许拥有 root 权限的用户连接到数据库。
运行管理工具。
/opt/vertica/bin/admintools
从主菜单中，选择连接到数据库 (Connect to Database)。
提供数据库密码（如果要求）：
```
Password:
```
在使用 CREATE USER 命令创建新用户时，可以配置密码，也可以将其留空。如果在创建用户时配置了密码，则无法绕开密码。可以使用 ALTER USER 命令更改用户的密码。

管理工具连接到数据库，并将控制权移交给 vsql。

Welcome to vsql, the Vertica Analytic Database interactive terminal.
Type:  \h or \? for help with vsql commands
       \g or terminate with semicolon to execute query
       \q to quit

=>

注意

有关可以在通过管理工具连接到数据库时运行的各个命令，请参阅元命令。

4 - 从命令行进行连接

可以在多个客户端平台上使用 vsql 从命令行连接到数据库。

如果由于任何原因无法建立连接（例如您没有足够的权限或者服务器未在目标主机上运行），则 vsql 会返回错误并终止。

语法

/opt/vertica/bin/vsql [-h host] [ -p port ] [ option...] [ dbname [ username ] ]

参数

host

如果要连接到本地服务器，则此参数是可选的。可以提供 IPv4 或 IPv6 IP 地址，或者也可以提供主机名。

如果 Vertica 服务器同时使用 IPv4 和 IPv6 地址，并且您提供了主机名而非 IP 地址，则当 DNS 已配置为同时提供 IPv4 和 IPv6 地址时，您可以选择将 IPv4 地址与 -4 选项结合使用，还可以选择将 IPv6 地址与 -6 选项结合使用。如果您使用 IPv6 并提供 IP 地址，则必须在地址后面附加 %interface name。

port

数据库服务器端口。

默认值： 5433

选项

一个或多个 vsql 命令行选项。

如果数据库受密码保护，则您必须指定 -w 或 --password 命令行选项。

dbname

目标数据库的名称。如果未指定，vsql 会自动连接到指定的 host 和 port 上的数据库。

注意

在 12.0.1 之前的 vsql 版本中，此参数的默认值是您的系统用户名。如果您尝试使用 vsql 12.0.0 或更早版本连接到 Vertica 12.0.1+ 数据库而不指定数据库名称，vsql 将返回以下错误：

Database <span class="code-variable">system_username</span> does not exist.

要避免此问题，请指定 dbname 或升级到 vsql 12.0.1+。

username

数据库用户名，默认情况下是您的系统用户名。

退出代码

vsql 在正常终止时返回 0 给 shell。否则，它返回以下值之一：

1：发生严重错误 — 例如，内存不足或找不到文件
2：与服务器的连接不正常，并且会话未进行交互
3：脚本中发生了错误，并且设置了变量 ON_ERROR_STOP
命令行中无法识别的单词可能会解释为数据库名称或用户名。

示例

以下示例显示如何通过将 vsql 输出重定向到输出文件 retail_queries.out 来捕获错误消息：

$ vsql --echo-all < retail_queries.sql > retail_queries.out 2>&1

4.1 - 命令行选项

本节包含适用于 vsql 的命令行选项。

常规选项

‑‑command command ‑c command: 运行一个命令，然后退出。此命令在 shell 脚本中很有用。
‑‑dbname {{< codevar >}}dbname{{< /codevar >}} ‑d {{< codevar >}}dbname{{< /codevar >}}: 指定要连接到的数据库的名称。此命令的作用等于将 dbname 指定为命令行中的第一个非选项实参。
‑‑file filename ‑f filename: 使用文件 filename 作为命令的源，而不以交互方式读取命令。处理完文件之后，vsql 将终止。
‑‑help: 显示有关 vsql 命令行实参的帮助并退出。
‑‑timing ‑i: 启用 \timing 元命令。
‑‑list ‑l: 返回所有可用数据库并退出。忽略其他非连接选项。此命令类似于内部命令 \list。
‑‑set assignment ‑‑variable assignment ‑v assignment: 执行变量分配，类似于 vsql 命令 \set。
‑‑version ‑V: 输出 vsql 版本并退出。
‑‑no‑vsqlr ‑X: 禁用所有命令行编辑和历史记录功能。

连接选项

‑4: 在双堆栈环境中解析主机名时，首选 IPv4 地址。
‑6: 在双堆栈环境中解析主机名时，首选 IPv6 地址。
‑B server:port[,...]: 设置连接的备份服务器/端口。使用以逗号分隔的多个主机（默认设置：未设置）。如果使用 IPv6 地址，请用方括号（[ 和 ]）将地址括起来，并将端口放在方括号之外。例如 \B [2620:0:a13:8a4:9d9f:e0e3:1181:7f51]:5433
‑‑enable‑connection ‑load‑balance ‑C: 启用连接负载均衡（默认设置：未启用）。

注意
只能对双堆栈环境中的一个地址族使用负载均衡。例如，如果已为 IPv6 地址配置了负载均衡，则当 IPv4 客户端连接到服务器并请求执行负载均衡时，服务器不允许执行该操作。
‑‑host hostname ‑h hostname: 指定了服务器正在其上面运行的计算机的主机名。
‑k krb‑service: 提供 Kerberos 主体的服务名称部分（默认设置：vertica）。-k 的作用等于使用驱动程序的 KerberosServiceName 连接字符串。
‑K krb‑host: 提供 Kerberos 主体的实例或主机名部分。-K 的作用等于驱动程序的 KerberosHostName 连接字符串。
‑‑sslmode ‑m: 指定用于建立与服务器的 SSL 连接的策略。选项为 require、prefer、allow 和 disable。设置 VSQL_SSLMODE 变量也可以达到同样效果。如果该变量已设置，命令行选项会覆盖它。
‑‑port {{< codevar >}}port{{< /codevar >}} ‑p {{< codevar >}}port{{< /codevar >}}: 指定服务器用来侦听连接的 TCP 端口或本地套接字文件扩展名。默认使用端口 5433。
‑‑username username ‑U username: 以 username 用户身份而非默认用户身份连接到数据库。
‑w password: 指定数据库用户的密码。

注意
使用此命令行选项可以用纯文本显示数据库密码。请谨慎使用此选项，尤其是当您以数据库管理员身份进行连接时，以避免暴露敏感信息。
‑‑password ‑W: 强制 vsql 在连接到数据库之前提示输入密码。密码不会显示在屏幕上。即使使用元命令 \connect 更改数据库连接，仍会为整个会话设置此选项。

输出格式

‑‑no‑align ‑A: 切换到未对齐输出模式。（默认输出模式为对齐模式。）
‑b: 在命令完成后发出嘟声。
‑‑field‑separator separator ‑F separator: 指定未对齐输出的字段分隔符（默认分隔符："|"）(‑P fieldsep=)。（请参阅 ‑A ‑‑no‑align。）此命令的作用等于 \pset fieldsep 或 \f。
‑‑html ‑H: 打开 HTML 表格格式输出。此命令的作用等于 \pset format html 或 \H 命令。
‑‑pset {{< codevar >}}assignment{{< /codevar >}} ‑P {{< codevar >}}assignment{{< /codevar >}}: 可用于在命令行中以 \pset 样式指定输出选项。必须用等号 (=) 而非空格来分隔名称和值。因此，若要将输出格式设置为 LaTeX，您应编写 ‑P format=latex。
‑Q: 打开尾随记录分隔符。使用 \pset trailingrecordsep 可以开关尾随记录分隔符。
‑‑record‑separator {{< codevar >}}separator{{< /codevar >}} ‑R {{< codevar >}}separator{{< /codevar >}}: 使用 separator 作为记录分隔符。此命令的作用等于 \pset recordsep 命令。
‑‑tuples‑only ‑t: 禁用列名称和结果行计数表尾等的输出。它的作用等于 vsql 元命令 \t。
‑‑table‑attr {{< codevar >}}options{{< /codevar >}} ‑T {{< codevar >}}options{{< /codevar >}}: 可用于指定要放置在 HTML table 标记中的选项。有关详细信息，请参阅 \pset。
‑‑expanded ‑x: 启用扩展表格式设置模式。它的作用等于 vsql 元命令 \x。

输入选项和输出选项

‑‑echo‑all ‑a: 在读取输入行时将所有输入行输出为标准输出。在进行脚本处理时，此方法比交互模式更有用。此选项的作用等于将变量 ECHO 设置为 all。
‑‑echo‑queries ‑e: 将发送到服务器的所有 SQL 命令复制到标准输出。此命令的作用等于将变量 ECHO 设置为 queries。
‑E: 显示由内部命令生成的查询。
‑n: 禁用命令行编辑。
‑‑output {{< codevar >}}filename{{< /codevar >}} ‑o {{< codevar >}}filename{{< /codevar >}}: 将所有查询输出写入到 filename。此命令的作用等于使用 vsql 元命令 \o。
‑‑quiet ‑q: 指定 vsql 以安静模式工作（无信息输出，例如欢迎消息）。此选项可与 -c 选项结合使用。在 vsql 中，设置 QUIET 变量也可以达到相同效果。
‑‑single‑step ‑s: 在单步模式下运行以调试脚本。强制要求 vsql 在将每个语句发送到数据库之前发出提示，以便取消执行。
‑‑single‑line ‑S: 在单行模式下运行，在此模式下，换行符与分号一样会终止 SQL 命令。

注意
仅根据客户请求提供此模式。在某个行中将 SQL 和元命令一起使用时，Vertica 建议不要使用单行模式。在单行模式下，经验不足的用户可能不了解执行顺序。

4.1.1 - -A --no-align

-A 或 --no‑align 切换到未对齐输出模式。默认输出模式为对齐模式。

4.1.2 - -a --echo-all

-a 或 --echo-all 在读取输入行时将所有输入行输出为标准输出。在进行脚本处理时，此选项比交互模式更有用。此选项的作用等于将变量 ECHO 设置为 all。

4.1.3 - -c --command

-c command 或 \--command command 将运行单个命令并在运行后退出。此命令在 shell 脚本中很有用。

可以使用以下两者之一：

一个命令字符串，该命令字符串可由不包含特定于 vsql 的功能的服务器完全解析。
单个元命令

不能将 SQL 元命令和 vsql 元命令一起使用。但是，可以按如下所示将字符串传送到 vsql：

echo "\\timing\\\\select * from t" | ../Linux64/bin/vsql
                Timing is on.
                i | c | v
                ---+---+---
                (0 rows)

注意

如果在 echo中使用双引号 (")，则反斜杠的个数必须翻倍 (\)。

4.1.4 - -d --dbname

-d db‑name or \--dbname db‑name 指定要连接的数据库的名称。此选项的作用等于将 db‑name 指定为命令行中的第一个非选项实参。

4.1.5 - -E

-E 显示由内部命令生成的查询。

4.1.6 - -e --echo-queries

-e \--echo-queries 同时将发送到服务器的所有 SQL 命令复制到标准输出。此选项的作用等于将变量 ECHO 设置为 queries。

4.1.7 - -F --field-separator

-F separator or \--field-separator separator 指定未对齐输出的字段分隔符（默认分隔符："|"）(-P fieldsep=)。（请参阅 -A \--no-align。）它的作用等于 \pset fieldsep 或 \f。

若要将字段分隔符值设置为一个控制字符，请使用 shell 的控制字符转义符号。在 Bash 中，可以使用美元符号 ($) 后跟加单引号的字符串的形式在实参中指定控制字符。此字符串可以包含 C 字符串转义（例如 \t 表示制表符）或反斜线 (\)，后跟要使用的字符的八进制值。

以下示例演示了如何将分隔符字符设置为制表符 (\t)、垂直制表符 (\v) 以及垂直制表符的八进制值 (\013)。

$ vsql -At -c "SELECT * FROM testtable;"
A|1|2|3
B|4|5|6

$ vsql -F $'\t' -At -c "SELECT * FROM testtable;"
A       1       2       3
B       4       5       6

$ vsql -F $'\v' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6
$ vsql -F $'\013' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6

4.1.8 - -f --file

-f filename 或 \--file filename 使用 filename 作为命令的源，而不以交互方式读取命令。处理完文件之后，vsql 将终止。

如果 filename 是连字符 (-)，则会读取标准输入。

使用此选项与编写 vsql < filename 不同。使用 -f 可启用部分附加功能（例如，带行号的错误消息）。相反，使用 shell 的输入重定向的变体始终应生成与您在手动输入所有内容时已获取的输出完全相同的输出。

4.1.9 - ？--help

-? \--help 显示有关 vsql 命令行实参的帮助并退出。

4.1.10 - -H --html

-H \--html 打开 HTML 表格格式输出。此选项的作用等于 \pset format html 或 \H 命令。

4.1.11 - -h --host

-h hostname 或 \--host hostname 指定了服务器正在其上面运行的计算机的主机名。使用此标志远程连接到 Vertica。

具有以下要求和限制：

如果您将客户端身份验证与 gss 或 krb5 的 Kerberos 连接方法结合使用，则必须指定 -h hostname。
如果要从本地连接连接到 Vertica，但要将身份验证记录与访问方法 HOST（而不是 LOCAL）结合使用，请使用 -h 选项。

4.1.12 - -i -- timing

启用 \timing 元命令。您只能将此命令与 -c --command 和 -f --file 命令一起使用：

$VSQL -h host1 -U user1 -d VMart -p 15 -w ****** -i -f transactions.sql

您只能将 -i 与 -c（命令）和 -f（文件名）命令一起使用。有关详细信息，请参阅命令行选项。

从命令行输入 -i 选项，然后运行会话以打开计时。例如：

$VSQL -h host1 -U user1 -d VMart -p 15 -w ****** -i -f transactions.sql

$VSQL-h host1 -U user1 -d VMart -p 15 -w ****** -i -c "SELECT user_name,
ssl_state, authentication_method, client_authentication_name, client_type FROM sessions
WHERE session_id=(SELECT session_id FROM current_session);"

4.1.13 - -l --list

-l 或 --list 返回所有可用数据库并退出。忽略其他非连接选项。此命令类似于内部命令 \list。

4.1.14 - -m --sslmode

-m 或 --sslmode 指定用于建立与服务器的 SSL 连接的策略。选项为 verify_full、verify_ca require、prefer、allow 和 disable。设置 VSQL_SSLMODE 变量也可以达到同样效果。如果该变量已设置，命令行选项会覆盖它。

有关这些模式的信息，请参阅为 ODBC 客户端配置 SSL。

4.1.15 - -n

-n 禁用命令行编辑。

4.1.16 - -o --output

-o filename 或 \--output filename 将所有查询输出写入 filename。它的作用等于 vsql 元命令 \o。

4.1.17 - -P --pset

-P assignment 或 \--pset assignment 可用于在命令行中以 \pset 样式指定输出选项。请注意，必须用等号而非空格来分隔名称和值。因此，若要将输出格式设置为 LaTeX，您应编写 -P format=latex。

4.1.18 - -p --port

-p port 或 \--port port 指定服务器用来侦听连接的 TCP 端口或本地套接字文件扩展名。默认使用端口 5433。

4.1.19 - -q --quiet

-q 或 --quiet 指定 vsql 以安静模式工作。默认情况下，它会输出欢迎消息和各种信息输出。如果使用此选项，则这些信息均不显示。此选项可与 -c 选项结合使用。在 vsql 中，设置 QUIET 变量也可以达到相同效果。

4.1.20 - -R --record-separator

-R separator 或 \--record-separator separator 指定将 separator 作为记录分隔符。它的作用等于 \pset recordsep 命令。

4.1.21 - -S --single-line

-S \--single-line 在单行模式下运行，在此模式下，换行符与分号一样会终止 SQL 命令。

注意

此模式仅对迫切需要的用户提供，但您并非必须使用此模式，尤其是当您在某个行中将 SQL 和元命令一起使用时。经验不足的用户可能并不总是了解执行顺序。

4.1.22 - -s --single-step

-s \--single-step 在单步模式下运行以调试脚本。强制要求 vsql 在将每个语句发送到数据库之前发出提示，以便取消执行。

4.1.23 - -T --table-attr

-T table‑options 或 \--table-attr table‑options 允许您指定要放置在 HTML table 标记中的选项。有关详细信息，请参阅 \pset。

4.1.24 - -t --tuples-only

-t 或 --tuples-only 禁用列名称和结果行计数表尾等的输出。它的作用等于 vsql 元命令 \t。

4.1.25 - -V --version

-V 或 --version 输出 vsql 版本并退出。

4.1.26 - -v --variable --set

-v assignment、 \--variable assignment 和 \--set assignment 指定变量分配，类似于 vsql 元命令 \set。

注意

必须在命令行中使用等号 (=) 分隔名称和值（如果有）。

若要取消设置变量，请省略等号。若要设置不具有值的变量，请使用等号而省略值。请在早期启动阶段执行这些分配，以便可以在稍后覆盖预留用于内部用途的变量。

4.1.27 - -X --no-vsqlrc

-X \--no-vsqlrc 防止读取启动文件（系统范围 vsqlrc 文件或用户的 ~/.vsqlrc 文件）。

4.1.28 - -x --expanded

-x 或 --expanded 启用扩展表格式设置模式。它的作用等于 vsql 元命令 \x。

4.2 - 从非群集主机进行连接

在非群集 Linux 主机上，您可以使用 Vertica vsql 可执行映像连接到 Vertica 数据库。

在 Red Hat、CentOS 和 SUSE 系统上，您可以安装包括 vsql 可执行文件的客户端驱动程序 RPM。有关详细信息，请参阅安装 vsql 客户端。
如果非群集主机与群集主机运行的 Linux 版本相同，请将映像文件复制到远程系统。例如：
```
$ scp host01:/opt/vertica/bin/vsql .$ ./vsql
```
如果非群集主机运行的 Linux 发行版或版本与群集主机不同，则必须安装 Vertica 服务器 RPM 才能获取 vsql：
1. 通过浏览到 Vertica 网站下载相应的 RPM 包。在支持 (Support) 选项卡上，选择客户下载 (Customer Downloads)。
2. 如果您下载 RPM 所用的系统不是非群集主机，请将文件传输到非群集主机。
3. 以 root 身份登录到非群集主机，并使用以下命令安装 RPM 包：
```
# rpm -Uvh filename
```
  其中，*filename * 是所下载的包。请注意，要使用 vsql，您无需在非群集主机上运行 install_vertica 脚本。
使用与群集主机相同的命令行选项。
不能在 Cygwin bash shell (Windows) 上运行 vsql。请使用 ssh 连接到群集主机，然后再运行 vsql。

5 - 元命令

在 vsql 中输入的任何以不带引号的反斜杠开头的命令称为 vsql 元命令，这种命令由 vsql 本身进行处理。这些命令可使 vsql 更有助于进行管理或脚本编写。元命令的更常用叫法是斜杠命令或反斜杠命令。

vsql 命令的格式是反斜杠的后面依次紧跟命令动词和任何参数。参数和命令动词用任意数量的空格字符分隔，并且各个参数用任意数量的空格字符分隔。

若要在参数中包含空格，您可以用单引号将该参数括起来。若要在参数中包含单引号，请在该参数前面附加反斜杠。此外，包含在单引号中的任何内容需要进行类 C 替换，以替代 \n（换行符）、\t（制表符）、\\数字、\0数字和 \0x数字（带有给定十进制、八进制或十六进制代码的字符）。

如果不带引号的参数以冒号 (:) 开头，则该参数会被视为 vsql 变量，并且变量的值会改为用作参数。

用反引号 (```) 括起来的实参会被视为一个命令行并传递到 shell。命令的输出（移除了任何尾随换行符）会被视为参数值。以上转义序列在反引号中也适用。

有些命令使用 SQL 标识符（例如表名称）作为参数。这些实参遵循 SQL 的语法规则：不带引号的字母会强制转换为小写，而双引号 (") 可防止对字母进行大小写转换并允许在标识符中包含空格。在双引号中，成对的双引号在生成的名称中会减少为单个双引号。例如，FOO"BAR"BAZ 会解释为 fooBARbaz，而 "A weird"" name" 将变为 A weird" name。

当出现其他不带引号的反斜杠时，对参数进行的解析将停止。此不带引号的反斜杠会被视为新的元命令的开头。特殊序列 \\（两个反斜杠）标记参数的结尾，并继续解析 SQL 命令（如果有）。这样，您可以随意地在单个行中将 SQL 命令和 vsql 命令一起使用。但在任何情况下，元命令的参数都不能超过行的结尾。

5.1 - 元命令快速参考

5.2 - \connect

以指定用户 user‑name 身份建立与数据库 db 的连接。上一个连接将关闭。如果您不指定数据库名称，Vertica 将连接到当前数据库。如果您不指定用户名实参，Vertica 将假定为当前用户。

语法

\c[connect] [db [user‑name]]

错误处理

阻止执行的错误包括：指定未知用户和拒绝访问指定数据库。Vertica 以不同方式处理错误，具体取决于此命令是在 vsql 中还是在脚本中交互执行：

VSQL 处理：当前连接保持不变。
脚本：处理立即停止并显示错误。这可以防止脚本作用于错误的数据库。

5.3 - \d 元命令

Vertica 支持许多 \d 命令，这些命令返回有关不同类别的数据库对象的信息。有关完整列表，请参阅下面的 \d 参考。

语法

除非另有说明，否则 \d 命令通常遵循以下语法：

\dCommand [ [schema.]pattern ]

参数

您可以为大多数 \d 命令提供字符串模式实参，用于筛选命令返回的结果。该模式可以选择由架构名称限定。

架构

对大多数 \d 命令有效，将输出仅限制为 schema 中的数据库对象。例如，以下 \dp 命令获取包含字符串 resource 的所有 V_MONITOR 表的权限信息：

=> \dp V_MONITOR.*resource*
                Access privileges for database "dbadmin"
 Grantee | Grantor | Privileges |  Schema   |            Name
---------+---------+------------+-----------+----------------------------
 public  | dbadmin | SELECT     | v_monitor | resource_rejections
 public  | dbadmin | SELECT     | v_monitor | disk_resource_rejections
 public  | dbadmin | SELECT     | v_monitor | resource_usage
 public  | dbadmin | SELECT     | v_monitor | resource_acquisitions
 public  | dbadmin | SELECT     | v_monitor | resource_rejection_details
 public  | dbadmin | SELECT     | v_monitor | resource_pool_move
 public  | dbadmin | SELECT     | v_monitor | host_resources
 public  | dbadmin | SELECT     | v_monitor | node_resources
 public  | dbadmin | SELECT     | v_monitor | resource_queues
 public  | dbadmin | SELECT     | v_monitor | resource_pool_status
(10 rows)

模式

仅返回与指定字符串匹配的数据库对象。模式字符串可以包含以下通配符：

* （星号）：零个或多个字符。
? （问号）：任何单个字符。

例如，以下 \dt 命令返回以字符串 store 开头的表：

=> \dt store*
                     List of tables
 Schema |       Name        | Kind  |  Owner  | Comment
--------+-------------------+-------+---------+---------
 public | store_orders      | table | dbadmin |
 public | store_orders_2018 | table | dbadmin |
 public | store_overseas    | table | dbadmin |
 store  | store_dimension   | table | dbadmin |
 store  | store_orders_fact | table | dbadmin |
 store  | store_sales_fact  | table | dbadmin |
(6 rows)

\d 参考

\d

如果不由模式实参限定，则返回所有表及其架构名称、所有者和注释。如果由模式实参限定，则 \d 返回所有匹配的表和每个表中的所有列，以及每个列的详细信息，例如数据类型、大小和默认值。

\df

返回所有函数名称、函数返回数据类型和函数实参数据类型。此元命令还会返回用户可用的所有过程的过程名称和参数。

\dj

返回所有投影，并显示架构、投影名称、所有者和节点。返回的行包括超投影、实时聚合投影、Top-K 投影和带表达式的投影。

\dn

返回架构名称和架构所有者。

\dp

返回系统表 V_CATALOG.GRANTS 中所有对象的权限摘要：被授予者、授予者、权限、架构和对象名称（相当于 \z）。

\dS

如果不由模式实参限定，则返回所有 V_CATALOG 和 V_MONITOR 系统表。要仅获取一个架构的系统表，请使用架构名称限定命令，如下所示：

\dS { V_CATALOG | V_MONITOR }.*

\ds

返回序列及其参数。

\dT

返回 Vertica 支持的所有数据类型。

注意

\dT 如果使用模式实参限定，则不返回任何结果。

\dt

如果不由模式实参限定，则返回与未限定 \d 命令相同的信息。如果由模式实参限定，则 \dt 返回与未限定 \dt 命令具有相同详细级别的匹配表。

\dtv

返回表和视图。

\du

返回数据库用户以及他们是否是超级用户。

\dv

如果不由模式实参限定，则返回所有视图及其架构名称、所有者和注释。如果由模式实参限定，\dv 返回所有匹配的视图和每个视图中的列，以及每列的数据类型和大小。

5.4 - \edit

使用外部编辑器编辑查询缓冲区（或指定的文件）。当编辑器退出时，其内容会复制回查询缓冲区。如果未指定任何参数，则当前的查询缓冲区会复制到临时文件，然后以相同方式编辑该临时文件。

然后，将按照 vsql 的一般规则重新解析新的查询缓冲区，按照这些规则，包括第一个分号在内的整个缓冲区会被视为单个行。（因此，您无法使脚本以这种方式工作。请使用 \i 获取该结果。）如果没有任何分号，vsql 将等待用户输入分号（它不会执行查询缓冲区）。

提示

vsql 将按顺序搜索环境变量 VSQL_EDITOR、EDITOR 和 VISUAL，以供编辑器使用。如果这些环境变量均已取消设置，则会使用 vi（在 Linux 系统上）或 notepad.exe（在 Windows 系统上）。

语法

\e[dit] [ file ]

5.5 - \i

R从指定的文件读取并执行输入。

注意

若要在读取行的同时在屏幕上显示这些行，请将变量 ECHO 设置为 all。

语法

\i filename

示例

Linux 上的 Vertica vsql 客户端支持反引号（反撇号）扩展。例如：

将环境变量设置为包含要运行的脚本的路径：
```
$ export MYSCRIPTS=/home/dbadmin/testscripts
```
发出 vsql 命令。
```
$ vsql
```
使用反引号扩展来包含运行现有脚本的路径，例如 sample.sql。
```
=> \i `echo $MYSCRIPTS/sample.sql`
```

5.6 - \locale

显示或设置当前会话的区域设置。

注意

此命令不会更改所有数据库会话的默认区域设置。若要更改所有会话的默认区域设置，请设置 DefaultSessionLocale 配置参数。

语法

\locale [locale-identifier]

参数

locale-identifier

指定要使用的 ICU 区域设置标识符，默认设置为：

en_US@collation=binary

如果设置为空字符串，Vertica 会将区域设置设置为 en_US_POSIX。

如果省略此实参，则 \locale 返回当前区域设置。

有关标识符选项的详细信息，请参阅关于区域设置。有关区域设置标识符的完整列表，请参阅 ICU 项目。

示例

查看当前的区域设置：

=> \locale
en_US@collation=binary

更改此会话的默认区域设置：

=> \locale en_GBINFO:
INFO 2567:  Canonical locale: 'en_GBINFO:'
Standard collation: 'LEN'
English (GBINFO:)

注意

服务器区域设置仅影响服务器端查询处理的排序行为。客户端应用程序负责确保所设置的区域设置正确无误，以便正确显示字符。以下是 Vertica 推荐的最佳实践，可确保结果可预测：

应将 vsql 的终端模拟器 (POSIX) 中的区域设置设置为与服务器端 (ICU) 上设置的会话区域设置相同，以便在服务器上正确整理数据并在客户端上正确显示数据。
应在终端模拟器中使用 POSIX LANG 环境变量来设置 vsql 区域设置。有关如何设置区域设置，请参阅终端模拟器的文档。
服务器会话区域设置应使用为数据库指定默认区域设置中所述的设置进行设置。
vsql 的所有输入数据应该为 UTF-8，而所有输出数据都以 UTF-8 进行编码。
不支持非 UTF-8 编码和关联的区域设置值。

5.7 - \pset

设置一些选项来控制 Vertica 如何设置查询结果输出格式。

语法

\pset output-option

输出选项

注意

除非另有说明，否则输出选项对所有格式都有效。

format format‑option

设置输出格式，其中 format‑option 是以下项之一：

u[naligned] 将每一行的所有列数据写入一行，其中每个字段仅由当前分隔符分隔。将此输出用作其他程序的输入，例如用于 CSV 输入的逗号分隔字段。
a[ligned] （默认值）：呈现按列对齐的输出。
h[tml]：将 HTML 标记中的输出呈现为表。
l[atex]：在 LaTex 标记中呈现输出。

border int

仅当输出格式设置为 html 时有效，指定表边框，其中 int 指定边框类型。

expanded

在常规格式和扩展格式之间切换。如果启用了扩展格式，则所有输出都包含两个列，并且列名称位于左列而数据位于右列。这种模式对于宽表尤其有用。

fieldsep 'arg'

仅当输出格式设置为 unaligned 时有效，指定字段分隔符，默认分隔符为 |（竖线）。

例如，要将 Tab 指定为字段分隔符：

\pset fieldsep '\t'

footer

在是否显示默认表尾之间切换： （int 行）

null 'string'

指定此项可将列 null 值表示为 string。默认情况下，Vertica 将 null 值呈现为空字段，这可能会被误认为是空字符串。

例如：

\pset null '(null)'

pager [always]

在针对查询和 vsql 帮助输出是否使用寻呼机之间切换。如果已设置环境变量 PAGER，则输出会传送到指定的程序。否则会使用由平台决定的默认设置（例如 more）。

如果寻呼机已关闭，则不会使用寻呼机。如果寻呼机已打开，则只会在适当时使用寻呼机；也就是说，输出将传送到终端，并且不会显示在屏幕上。（vsql 无法准确评估何时应使用寻呼机。）

如果始终使用该实参进行限定，则始终使用寻呼机。

recordsep 'char'

仅当输出格式设置为 unaligned 时有效，指定用于分隔表记录（元组）的字符，默认分隔符为换行符。

tableattr html‑attribute[...]

指定要放在 HTML table 标记中的属性，例如 cellpadding 或 bgcolor。

title ['title‑str']

将位于查询结果输出之前的标题设置为 title‑str。HTML 输出呈现如下：

<caption>title-str</caption>

要移除标题，请重新发出命令，省略 title‑str 实参。

trailingrecordsep

开关要在未对齐输出模式中使用的尾随记录分隔符。

t[uples_only]

在仅显示元组和完整显示之间切换。完整显示可能会显示额外信息，例如，列标题、表标题和各个表尾。在仅显示元组模式下，只会显示实际表数据。

快捷方式

以下 \pset 命令有快捷方式：

\pset expanded

\x

\pset fieldsep 'arg'

\f

\pset format aligned

\a

\pset format html

\H

\pset tableattr html‑attribute[...]

\T html‑attribute[...]

\pset title title-str

\C ['title-str']

\pset tuples_only

\t

示例

请参阅输出格式设置示例。

5.8 - \set

S将内部变量设置为一个或多个值。如果指定了多个值，则将它们串连起来。未限定的 \set 命令将列出所有内部变量。

要取消设置变量，请使用 vsql 元命令 \unset。

语法

\set [var [value]...]

参数

var: 要设置的内部变量的名称。有效的变量名区分大小写，可以包含字符、数字和下划线。vsql 将几个变量视为特殊变量，如变量中所述。
value: 要在变量 var 中设置的值。如果未指定值，则变量设置为无值。
如果设置为空字符串，则变量设置为无值。如果省略此实参，则 \set 返回所有内部变量。

如果未提供任何实参，则 \set 返回所有内部变量。例如：

=> \set
VERSION = 'vsql'
AUTOCOMMIT = 'off'
VERBOSITY = 'default'
PROMPT1 = '%/%R%# '
PROMPT2 = '%/%R%# '
PROMPT3 = '>> '
ROWS_AT_A_TIME = '1000'
DBNAME = 'dbadmin'
USER = 'dbadmin'
PORT = '5433'
LOCALE = 'en_US@collation=binary'
HISTSIZE = '500'

5.9 - \timing

如果设置为 on，则返回每个 SQL 语句运行的时间长度（以毫秒为单位）。结果包括：

获取第一个行块所需的时间长度
直到最后一个块格式化的总时间。

未限定的 \timing 在打开和关闭计时之间切换。您可以通过分别使用选项 ON 和 OFF 限定命令来显式打开和关闭计时。

注意

您还可以使用 vsql -i 命令从命令行启用 \timing。

语法

\timing [ON | OFF]

示例

以下未限定的 \timing 命令在打开和关闭计时之间切换：

=> \timing
Timing is on
=> \timing
Timing is off

以下示例显示了一个打开计时的 SQL 命令：

=> \timing
Timing is on.
=> SELECT user_name, ssl_state, authentication_method, client_authentication_name,
     client_type FROM sessions WHERE session_id=(SELECT session_id FROM current_session);
 user_name | ssl_state | authentication_method | client_authentication_name | client_type
-----------+-----------+-----------------------+----------------------------+-------------
 dbadmin   | None      | ImpTrust              | default: Implicit Trust    | vsql
(1 row)

Time: First fetch (1 row): 73.684 ms. All rows formatted: 73.770 ms

6 - 变量

vsql 提供与常用 Linux 命令 shell 相似的变量替换功能。变量是名称/值对，其中值可以是任意长度的字符串。若要设置变量，请使用 vsql 元命令 \set：例如，以下语句将变量 fact 设置为值 dim：

=> \set fact dim

如果您对变量调用 \set 并且不提供任何值，则该变量设置为空字符串。

注意

\set 的实参需要遵守与其他命令相同的替换规则。例如，\set dim :fact 是复制变量的有效方法。

获取变量

若要检索给定变量的内容，请在名称前面附加冒号，并将此用作斜杠命令的实参：例如：

=> \echo :fact
dim

未限定的 \set 命令会返回所有当前变量及其值：

dbadmin=> \set
VERSION = 'vsql'
AUTOCOMMIT = 'off'
VERBOSITY = 'default'
PROMPT1 = '%/%R%# '
PROMPT2 = '%/%R%# '
PROMPT3 = '>> '
ROWS_AT_A_TIME = '1000'
DBNAME = 'dbadmin'
USER = 'dbadmin'
PORT = '5433'
LOCALE = 'en_US@collation=binary'
HISTSIZE = '500'

删除变量

若要取消设置（删除）变量，请使用 vsql 元命令 \unset。

变量命名约定

vsql 内部变量名称可以包含任意数量的字母、数字和下划线（而且它们可以按任何顺序出现）。vsql 会对某些内部变量进行特殊处理。这些变量指示可以在运行时通过更改变量的值来更改某些选项设置，或者表示应用程序的某种状态。虽然可以将这些变量用于任何其他用途，但建议您不要这样做。按照约定，所有特殊处理的变量均包含全大写字母（并且可能包含数字和下划线）。若要确保在将来具有最高兼容性，请避免将这些变量名称用于您自己的用途。

SQL 插值

您可以将 vsql 变量替换（“插值”）到常规 SQL 语句中。为此，可以在变量名称前加上冒号 (:)。例如，以下语句查询表 my_table：

=> \set fact 'my_table'
=> SELECT * FROM :fact;

将逐字复制变量的值，因此，变量甚至可以包含不对称的引号或包含反斜杠命令。请确保将变量放置到能够起作用的位置。不会执行到带有引号的 SQL 实体的变量插值。存在一个例外：带有反引号 (````) 的字符串的内容会传递到系统 shell，并替换为 shell 的输出。请参阅下面的“使用反引号读取系统变量”。

使用反引号读取系统变量

在 vsql 中，反引号的内容会传递到系统 shell 进行解释（此行为与许多 UNIX shell 相同）。在设置 vsql 内部变量时，此行为特别有用，因为您可能需要访问 UNIX 系统变量（例如 HOME 或 TMPDIR）而非硬编码值。

例如，要将内部变量设置为 UNIX 用户目录中某个文件的完整路径，您可以使用反引号获取 HOME 系统变量（此变量是指向用户目录的完整路径）的内容：

=> \set inputfile `echo $HOME`/myinput.txt=> \echo :inputfile
/home/dbadmin/myinput.txt

反引号之内的内容会替换为在系统 shell 解释器中运行这些内容后的结果。在此示例中，echo $HOME 命令将返回 HOME 系统变量的内容。

6.1 - AUTOCOMMIT

当 AUTOCOMMIT 设置为“on”时，每个 SQL 命令会在成功完成后自动提交；例如：

\set AUTOCOMMIT on

若要在此模式下推迟 COMMIT，请将值设置为 off。

\set AUTOCOMMIT off

如果 AUTOCOMMIT 为空或定义为 off，则 SQL 命令不会提交，除非您显式发出 COMMIT。

注意

默认情况下，AUTOCOMMIT 设置为 off。
AUTOCOMMIT 必须为大写，但其值（on 或 off）不区分大小写。
在关闭自动提交模式下，您必须通过输入 ABORT 或 ROLLBACK 来显式放弃任何失败的事务。
如果在未提交的情况下退出会话，将回退您所做的工作。
对 vsql 变量的验证在运行这些变量时进行，而不在设置这些变量时进行。
默认情况下，COPY 语句会在完成后提交，因此使用哪种 AUTOCOMMIT 模式并没什么影响，除非您发出 COPY NO COMMIT。请注意，DDL 语句会自动提交。
若要确定 AUTOCOMMIT 设置为 on 还是 off，请发出以下 set 命令：
```
$ \set...
AUTOCOMMIT = 'off'
...
```

如果 SELECT * FROM LOCKS 显示了来自刚才运行的语句的锁，则表示 AUTOCOMMIT 设置为 off。

$ \set AUTOCOMMIT off
$ \set
...
AUTOCOMMIT = 'off'
...
SELECT COUNT(*) FROM customer_dimension;
 count
-------
 50000
(1 row)
SELECT node_names, object_name, lock_mode, lock_scope
FROM LOCKS;
 node_names |      object_name         | lock_mode | lock_scope
------------+--------------------------+-----------+-------------
 site01     | Table:customer_dimension | S         | TRANSACTION
(1 row)

6.2 - DBNAME

当前已连接到的数据库的名称。每次连接到数据库（包括程序启动）时都会设置 DBNAME，但也可以取消设置它。

6.3 - ECHO

如果设置为 all，则通过键盘或脚本输入的所有行会写入到标准输出，然后再解析或运行这些行。

若要在程序启动时选择此行为，请使用 -a 开关。如果设置为 queries，则 vsql 只会按照发送到服务器的内容输出所有查询。此行为的开关是 -e。

6.4 - ECHO_HIDDEN

如果设置此变量，则当反斜杠命令查询数据库时，首先会显示查询。这样，您可以学习 Vertica 内部命令并在您自己的程序中提供相似功能。（若要在程序启动时选择此行为，请使用 -E 开关。）

如果将此变量设置为值 noexec，则只会显示查询，而实际上不会将查询发送到服务器，也不会运行查询。

6.5 - ENCODING

当前的客户端字符集编码。

6.6 - HISTCONTROL

如果此变量设置为 ignorespace，则以空格开头的行不会输入到历史记录列表中。如果此变量设置为值 ignoredups，则不会输入与上一个历史记录行匹配的行。值 ignoreboth 结合了两个选项。如果取消设置此变量，或者将此变量设置为前述值以外的任何其他值，则在交互模式下读取的所有行都会保存到历史记录列表中。

来源： Bash。

6.7 - HISTSIZE

设置用于存储命令历史记录的空间量。该值大致近似于 vsql 在其命令历史记录缓冲区中存储的命令数。此值仅影响当前 vsql 会话存储的行数。它不影响 .vsql_history 文件中存储的历史记录。

默认值为 500。

注意

vsql 将 HISTSIZE 值乘以 50 字节（SQL 语句平均长度的近似值），得出为命令历史记录留出的内存量。根据 SQL 语句的实际长度，vsql 可能能够存储比您在 HISTSIZE 中设置的值更多或更少的命令。

来源： Bash。

6.8 - 主机

当前连接到的数据库服务器主机。每次连接到数据库（包括程序启动）时都会设置它，但也可以取消该设置。

6.9 - IGNOREEOF

如果取消设置此变量，则向 vsql 的交互会话发送 EOF 字符（通常是按 Ctrl+D）会终止应用程序。如果将此变量设置为数值，则应用程序在终止之前会忽略许多 EOF 字符。如果设置了此变量但未提供任何数值，则默认值为 10。

来源： Bash。

6.10 - ON_ERROR_STOP

默认情况下，如果脚本命令生成错误（例如，由于命令格式不正确或数据格式无效），处理将继续进行。如果在脚本中将 ON_ERROR_STOP 设置为 ON，并且在处理期间发生错误，脚本将立即终止。

例如：

=> \set ON_ERROR_STOP ON

注意

如果在 Linux 上使用 vsql -f 调用脚本，则 vsql 会返回错误代码 3，指示脚本中出现错误。

6.11 - PORT

当前连接到的数据库服务器端口。每次连接到数据库（包括程序启动）时都会设置此变量，但也可以取消设置此变量。

6.12 - PROMPT1 PROMPT2 PROMPT3

这些变量指定 vsql 所发出的提示的内容。有关详细信息，请参阅提示。

6.13 - QUIET

此变量相当于命令行选项 -q。此变量在交互模式下可能不太有用。

6.14 - ROWS_AT_A_TIME

ROWS_AT_A_TIME 默认设置为 1000，并将结果检索为具有该大小的行块。第一个块的列格式设置用于所有块，因此在稍后的块中，有些条目可能会溢出。

设置结果的格式时，Vertica 会将 ROWS_AT_A_TIME 行缓冲到内存中，以计算最大列宽。如果任何字段值的长度超过前几个 ROWS_AT_A_TIME 行中出现的字段值，则初始提取之后的行可能未正确对齐。 ROWS_AT_A_TIME 可以使用 vsql 元命令 \unset 取消设置以保证正确对齐。不过，这要求将整个结果集重新缓冲到内存中，可能会在结果集太大时导致 vsql 失败。

6.15 - SINGLELINE

此变量相当于命令行选项 -S。

6.16 - SINGLESTEP

此变量相当于命令行选项 -s。

6.17 - 用户

当前用来进行连接的数据库用户。每次连接到数据库（包括程序启动）时都会设置它，但也可以取消该设置。

6.18 - VERBOSITY

此变量可以设置为值 default、verbose 或 terse，以控制错误报告的详细程度。

6.19 - VSQL_HOME

默认情况下，vsql 程序从用户的主目录读取配置文件。如果这么做不合适，可以通过设置 VSQL_HOME 环境变量来覆盖配置文件位置，而且设置 VSQL_HOME 环境变量时可以不需要修改共享资源。

在以下示例中，vsql 从 /tmp/jsmith 而非 ~ 读取配置信息。

# Make an alternate configuration file in /tmp/jsmith
mkdir -p /tmp/jsmith
echo "\\echo Using VSQLRC in tmp/jsmith" > /tmp/jsmith/.vsqlrc
# Note that nothing is echoed when invoked normally
vsql
# Note that the .vsqlrc is read and the following is
# displayed before the vsql prompt
#
# Using VSQLRC in tmp/jsmith
VSQL_HOME=/tmp/jsmith vsql

6.20 - VSQL_SSLMODE

VSQL_SSLMODE 指定客户端（例如 admintools）在连接到服务器时如何使用（或是否使用）SSL。默认值为 prefer，表示使用 SSL（如果服务器提供的话）。合法值为 require、prefer、allow 和 disable。此变量的作用等于命令行选项 -m（或 --sslmode）。

7 - 提示

可以根据您的首选项自定义 vsql 所发出的提示。PROMPT1、PROMPT2 和 PROMPT3 三个变量可以包含描述了提示的外观的字符串和特殊转义序列。提示 1 是在 vsql 请求新的命令时使用的普通提示。如果在输入命令期间由于命令不以分号终止或引号未关闭而需要更多输入，将发出提示 2。当您运行 SQL COPY 命令并且需要在终端上键入行值时，将发出提示 3。

将逐字输入所选提示变量的值，除非遇到百分号 (%)。根据下一个字符，某些其他文本会被替换。已定义的替换如下：

%M

数据库服务器的完整主机名（包括域名）、[local]（如果连接通过套接字）或 [local:/dir/name]（如果不在默认位置编译该套接字）。

%m

数据库服务器的主机名（在第一个点处截断）或 [local]。

%>

数据库服务器正在侦听的端口号。

%n

数据库会话的用户名。

%/

当前数据库的名称。

%~

类似于 %/，但如果数据库是默认数据库，则输出是 ~（波浪符）。

%#

如果会话用户是数据库超级用户，则输出 #，否则会输出 >。（如果运行 SET SESSION AUTHORIZATION 命令，此值的扩展在数据库期间可能会更改。）

%R

在提示 1 中，通常替换为 =；但如果处于单行模式，则替换为 ^；如果会话已从数据库断开连接（当 \connect 失败时，将出现这种情况），则替换为 !。在提示 2 中，序列会替换为 -、、单引号、双引号或美元符号，具体取决于 vsql 是由于命令尚未终止还是由于处于 / ...*/ 注释之内或处于以引号或美元符号转义的字符串之内而需要更多输入。在提示 3 中，该序列不会生成任何内容。

%x

事务状态：空字符串（如果不在事务块中）、*（如果在事务块中）、!（如果在失败的事务块中）或 ? [如果事务状态不确定（例如，由于无连接）]。

%digits

带有所指示的数字代码的字符会被替换。如果数字以 0x 开头，则其余字符会解释为十六进制；如果第一个数字是 0，则数字会解释为八进制；否则会作为十进制数字读取数字。

%:name:

vsql 变量名称的值。有关详细信息，请参阅“变量”一节。

%`command`

命令的输出，类似于常见的“重音符”替换。

%[ ... %]

提示可能包含终端控制字符，例如，这些控制字符可能更改提示文本的颜色、背景或样式，或者可能更改终端窗口的标题。为使 Readline 的行编辑功能正常工作，必须通过用 %[ 和 %] 将这些非输出控制字符括起来将其指定为不可见。提示中可能会出现多对这些字符。以下示例将在兼容 VT100 且支持彩色的终端上生成粗体 (1;) 的黄色且带有黑色背景 (33;40) 的提示：

testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%#%[%033[0m%] '

若要将百分号插入到提示中，请编写 %%。提示 1 和 2 的默认提示为 '%/%R%#'，提示 3 的默认提示为 '>>'。

注意： 请参阅终端控制序列的规范（适用于 gnome-terminal 和 xterm）。

8 - 命令行编辑

vsql 支持 tecla 库，以便于进行行编辑和检索。

当 vsql 退出时，将自动保存命令历史记录；当 vsql 启动时，将重新加载命令历史记录。还支持 Tab 自动补全，但完成逻辑不会声称自己是 SQL 解析器。如果您由于某种原因而不想使用 Tab 自动补全，可以通过将以下代码放到主目录中名为 .teclarc 的文件来关闭该功能：

bind ^I

有关更多详细信息，请阅读 tecla 文档。

注意

tecla 库的 vsql 实施与 tecla 文档中所述存在如下偏差：

重新调用先前键入的行

在纯 tecla 下，所有新行会附加到历史输入行（在 GetLine 资源对象中维护）的列表中。在 vsql 中，只有不同的非空行才会附加到历史输入行的列表中。
历史记录文件

tecla 的历史记录文件没有标准名称。在 vsql 中，文件名为 ~/.vsql_hist。
国际字符集（元键和区域设置）

在 vsql 中，不再支持 8 位元字符。请通过将元字符的 EightBitInput X 资源设置为 False 来确保元字符发送转义符。可以通过以下方法之一执行此操作：
- 通过添加以下行来编辑 ~/.Xdefaults 文件：
```
XTerm*EightBitInput: False
```
- 使用 -xrm“*EightBitInput: False”命令行参数启动 xterm。
键绑定：
以下键绑定特定于 vsql：
- Insert，在插入模式（默认模式）和覆盖模式之间切换。
- Delete，删除光标右侧的字符。
- Home，将光标移到行的开头。
- End，将光标移到行的结尾。
- ^R，执行历史记录向后搜索。

9 - vsql 环境变量

每次启动 vsql 时，将自动设置下列一个或多个环境变量以供已定义的属性使用：

PAGER: 如果查询结果无法在屏幕上显示，将通过此命令传送这些结果。典型值为 more 或 less。默认值由平台决定。使用 \pset 命令启用/禁用寻呼机。
VSQL_DATABASE: 您连接的数据库。例如 VMart。
TMPDIR: 用于存储临时文件的目录。默认值由平台决定。在类 Unix 系统上，默认值为 /tmp。
VSQL_EDITOR EDITOR VISUAL: 由 \e 命令使用的编辑器。将按照列出变量的顺序检查变量；将使用所设置的第一个变量。
VSQL_HOME: 默认情况下，vsql 程序从用户的主目录读取配置文件。如果这么做不合适，可以通过设置 VSQL_HOME 环境变量来覆盖配置文件位置，而且设置 VSQL_HOME 环境变量时可以不需要修改共享资源。
VSQL_HOST: Vertica 节点的主机名或 IP 地址。
VSQL_PASSWORD: 数据库密码。使用此环境变量可提高站点安全性，因为无需在命令行中输入数据库密码。
VSQL_PORT: 要用于连接的端口。
VSQL_SSLMODE: 指定客户端（如 admintools）在连接到服务器时是否以及如何使用 SSL。
VSQL_USER: 要用于连接的用户名。

10 - 区域设置

Linux 下的默认终端模拟器是 gnome-terminal，但您也可以使用 xterm。

Vertica 建议在 UTF-8 模式下将 gnome-terminal 与 vsql 结合使用，这是默认设置。

在 Linux 上更改设置

从 vsql 屏幕顶部的选项卡中，选择“终端 (Terminal)”。
单击设置字符编码 (Set Character Encoding)。
选择 Unicode (UTF-8)。

注意
这适用于标准键盘。xterm 有一个类似的 UTF-8 选项。

在 Windows 上使用 PuTTy 更改设置

右键单击 vsql 屏幕标题栏，然后选择更改设置 (Change Settings)。
单击窗口 (Window)，然后单击转换 (Translation)。
从右侧的下拉菜单中选择 UTF-8。

注意

vsql 无法了解您如何设置了终端模拟器选项。
tecla 库已准备好使用 POSIX LANG 等环境变量对交互式输入执行从本地编码到 UTF-8 的 POSIX 类型转换。此类型转换对使用非 UTF-8 键盘的国际用户很有用。有关详细信息，请参阅 tecla 文档。

Vertica 建议使用以下区域设置（或您觉得合适的任何其他 .UTF-8 区域设置）：
```
export LANG=en_US.UTF-8
```
vsql \locale 命令将调用并跟踪服务器的 SET LOCALE TO 命令，如中所述。目前，vsql 本身不对此区域设置执行任何操作，而会将其输入（来自文件或 tecla）、所有输出及其与服务器的所有交互视为 UTF-8。除了在 printf 等中使用的任何“automatic”之外，vsql 将忽略 POSIX 区域变量。

11 - 使用 vsql 输入数据

使用 vsql 时经常需要插入字面量数据。例如：

使用 INSERT 语句向表中添加一行数据。
通过 COPY FROM STDIN 语句添加多行数据。

下表列出了 Vertica 支持的数据类型，以及您在使用 vsql 时用于在查询中输入该数据的格式。

12 - 文件

启动之前，vsql 会尝试读取并执行系统范围 vsqlrc 文件和用户的 ~/.vsqlrc 文件中的命令。命令行历史记录存储在文件 ~/.vsql_history.

提示

如果要保存旧的历史记录文件，请打开另一个终端窗口，然后将副本另存为其他文件名。

13 - 使用 vsql 导出数据

可以使用 vsql 执行简单的数据导出任务，方法是更改其输出格式选项，以使输出适用于导入到其他系统（例如，Tab 分隔文件或逗号分隔文件）。可以从 vsql 会话中设置这些选项，或者也可以通过传递到 vsql 命令的命令行参数设置这些选项（这样可使导出过程适合通过编写脚步来实现自动化）。设置了 vsql 选项以使其采用目标系统可读取的格式输出数据之后，您可以运行查询并将结果捕获到文本文件。

下表列出了可用于更改 vsql 的输出格式的元命令和命令行选项。

以下示例演示了在输出中禁用填充和列标题，并演示了在交互式会话中设置字段分隔符以将表转储到制表符分隔的文本文件。

=> SELECT * FROM my_table;
 a |   b   | c
---+-------+---
 a | one   | 1
 b | two   | 2
 c | three | 3
 d | four  | 4
 e | five  | 5
(5 rows)
=> \a
Output format is unaligned.
=> \t
Showing only tuples.
=> \pset fieldsep '\t'
Field separator is "    ".
=> \o dumpfile.txt
=> select * from my_table;
=> \o
=> \! cat dumpfile.txt
a       one     1
b       two     2
c       three   3
d       four    4
e       five    5

注意

使用此技术在空字符串和 NULL 之间来回转换时，您可能会遇到问题。可以通过显式设置 null 值以使其输出诸如 NULLNULLNULL 等唯一字符串来防止任何混乱（例如，\pset null 'NULLNULLNULL'）。然后，在导入结束后将该唯一字符串转换回 null 值。例如，如果要将文件复制回 Vertica 数据库，您应向 COPY 语句提供实参 NULL 'NULLNULLNULL'。

如果已登录到数据库节点之一，您可以通过向 vsql 传递正确的参数直接从命令行创建相同的输出文件：

$ vsql -U username -F $'\t' -At -o dumpfile.txt -c "SELECT * FROM my_table;"
Password:
$ cat dumpfile.txt
a       one     1
b       two     2
c       three   3
d       four    4
e       five    5

如果要将 null 值转换为如前文所述的唯一字符串，您可以添加实参 -P null='NULLNULLNULL'（或所选的任何唯一字符串）。

通过将 -w vsql 命令行选项添加到示例命令行，您可以在批处理脚本中使用命令以将数据导出自动化。但是，该脚本将包含纯文本格式的数据库密码。如果采用此方法，您应防止该批处理脚本受到未经授权的访问，还应让脚本使用具有受限访问权限的数据库用户帐户。

以下示例演示了如何将分隔符字符设置为制表符 (\t)、垂直制表符 (\v) 以及垂直制表符的八进制值 (\013)。

$ vsql -At -c "SELECT * FROM testtable;"
A|1|2|3
B|4|5|6

$ vsql -F $'\t' -At -c "SELECT * FROM testtable;"
A       1       2       3
B       4       5       6

$ vsql -F $'\v' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6
$ vsql -F $'\013' -At -c "SELECT * FROM testtable;"
A
 1
  2
   3
B
 4
  5
   6

14 - 使用 vsql 复制数据

可以使用 vsql 在两个 Vertica 数据库之间复制数据。此技术类似于使用 vsql 导出数据中介绍的技术，但您应将一个 vsql 命令的输出传送到另一个 vsql 命令（从 STDIN 运行 COPY 语句）的输入，而不能让 vsql 将数据保存到文件以用于导出。此技术也适用于从输入流接受数据的其他数据库或应用程序。

注意

以下技术仅适用于单个表。要将整个数据库复制到另一个群集，请参阅将数据库复制到其他群集。

使用 vsql 进行复制的最简单方法是登录到目标数据库的一个节点，然后发出用于连接到源 Vertica 数据库的 vsql 命令以转储所需数据。例如，以下命令可将节点 testdb01 上的 vmart 数据库中的 store.store_sales_fact 表复制到您已登录到的节点上的 vmart 数据库：

vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT * from store.store_sales_fact"  \
| vsql -U username -w passwd -d vmart -c "COPY store.store_sales_fact FROM STDIN DELIMITER '|';"

注意

以上示例仅复制数据，而不复制表设计。数据复制的目标表必须已存在于目标数据库中。可以使用 EXPORT_OBJECTS 或 EXPORT_CATALOG 导出表设计。

如果使用的是 Bash shell，您可以对特殊分隔符进行转义。例如，DELIMITER E'\t' 可指定制表符。Bash 以外的其他 shell 可能具有其他字符串字面量语法。

监控进度（可选）

在 Vertica 数据库之间复制大量数据时，您可能希望使用某种方法来监控进度。监控复制操作的进度的方法之一是使用诸如 Pipe Viewer 等实用程序，此类实用程序直接将其输入传送到其输出并同时显示其传递的数据的数量和速度。如果提供所需处理的字节或行的总数，Pipe Viewer 甚至还能显示一个进度栏。可以通过运行将执行 SELECT COUNT 查询的单独的 vsql 命令来获取要处理的行数。

注意

Pipe Viewer 不是标准 Linux 命令，因此您需要自己下载并安装此实用程序。若要下载包并获取说明，请参阅 Pipe Viewer 页面。Vertica 不支持 Pipe Viewer。若要安装并使用此实用程序，您需要自行承担风险。

以下命令演示了如何使用 Pipe Viewer 监控前一个示例中所示的复制操作的进度。由于需要获取将复制的行数（可以在 Bash 反引号中使用单独的 vsql 命令来完成此操作，此 vsql 命令会执行字符串的内容并将命令的输出插入到命令行中），该命令变得复杂化。此 vsql 命令仅计算 in the store.store_sales_fact 表中的行数。

vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT * from store.store_sales_fact"  \
| pv -lpetr -s `vsql -U username -w passwd -h testdb01 -d vmart -At -c "SELECT COUNT (*) FROM store.store_sales_fact;"` \
| vsql -U username -w passwd -d vmart -c "COPY store.store_sales_fact FROM STDIN DELIMITER '|';"

运行以上命令时，将显示一个如下所示的进度栏：

0:00:39 [12.6M/s] [=============================>                             ] 50% ETA 00:00:40

15 - 输出格式设置示例

默认情况下，Vertica 按如下方式设置查询输出的格式：

=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
       category_description
----------------------------------
 Food
 Medical
 Misc
 Non-food
(4 rows)

您可以使用 \pset 命令以多种方式（例如更改边框）控制查询输出的格式：

=> \pset border 2
Border style is 2.
=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
+----------------------------------+
|       category_description       |
+----------------------------------+
| Food                             |
| Medical                          |
| Misc                             |
| Non-food                         |
+----------------------------------+
(4 rows)

=> \pset border 0
Border style is 0.
=> SELECT DISTINCT category_description FROM product_dimension ORDER BY category_description;
      category_description
--------------------------------
Food
Medical
Misc
Non-food
(4 rows)

以下 pset 命令序列以多种方式更改查询输出：

将边框样式设置为 1。
移除列对齐。
将字段分隔符更改为逗号。
移除列标题

=> \pset border 1
Border style is 1.
=> \pset format unaligned
Output format is unaligned.
=> \pset fieldsep ','
Field separator is ",".
=> \pset tuples_only
Showing only tuples.
=> SELECT product_key, product_description, category_description FROM product_dimension LIMIT 10;
1,Brand #2 bagels,Food
1,Brand #1 butter,Food
2,Brand #6 chicken noodle soup,Food
3,Brand #11 vanilla ice cream,Food
4,Brand #14 chocolate chip cookies,Food
4,Brand #12 rash ointment,Medical
6,Brand #18 bananas,Food
7,Brand #25 basketball,Misc
8,Brand #27 french bread,Food
9,Brand #32 clams,Food

以下示例使用元命令来切换输出格式（在本例中为 \a（对齐）、\t（仅元组）和 -x（扩展显示））：

=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is off.
=> SELECT product_key, product_description, category_description FROM product_dimension LIMIT 10;
 product_key |       product_description        |       category_description
-------------+----------------------------------+----------------------------------
           1 | Brand #2 bagels                  | Food
           1 | Brand #1 butter                  | Food
           2 | Brand #6 chicken noodle soup     | Food
           3 | Brand #11 vanilla ice cream      | Food
           4 | Brand #14 chocolate chip cookies | Food
           4 | Brand #12 rash ointment          | Medical
           6 | Brand #18 bananas                | Food
           7 | Brand #25 basketball             | Misc
           8 | Brand #27 french bread           | Food
           9 | Brand #32 clams                  | Food
(10 rows)

以下示例将输出格式设置为 HTML，因此 Vertica 将 HTML 标记中的查询结果呈现为表：


=> \pset format html
Output format is html.
=> \pset tableattr 'border="2" cellpadding="3"'
Table attribute is "border="2" cellpadding="3"".
=> SELECT product_key, product_description, category_description FROM product_dimension LIMIT 2;
<table border="1" border="2" cellpadding="3">
  <tr>
    <th align="center">product_key</th>
    <th align="center">product_description</th>
    <th align="center">category_description</th>
  </tr>
  <tr valign="top">
    <td align="right">1</td>
    <td align="left">Brand #2 bagels</td>
    <td align="left">Food                            </td>
  </tr>
  <tr valign="top">
    <td align="right">1</td>
    <td align="left">Brand #1 butter</td>
    <td align="left">Food                            </td>
  </tr>
</table>
<p>(2 rows)<br />
</p>