vsql
功能描述
vsql是VexDB提供的在命令行下运行的数据库连接工具，用户可以通过此工具连接服务器并对其进行操作和维护，除了具备操作数据库的基本功能，vsql还提供了若干高级特性，便于用户使用。
基本功能
- 连接数据库： 详情请参考使用vsql连接。
- 执行SQL语句： 支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。
- 执行元命令： 元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果、以及连接到新的数据库等。元命令的详细说明请参见元命令参考。在vsql里输入的任何以不带引号的反斜杠开头的命令都是vsql元命令，这些命令是将由vsql自己处理的，元命令通常也被称为斜杠或反斜杠命令。
说明
高级特性
vsql支持的高级特性包括：
- 设置变量：vsql提供类似于Linux的shell命令的变量特性，可以使用vsql的元命令
\set设置一个变量。 - SQL代换：利用vsql的变量特性，可以将常用的SQL语句设置为变量，以简化操作。
- 提示符：vsql使用的提示符支持用户自定义。
- 命令自动补齐：vsql支持使用Tab键进行命令的自动补齐，当编译时指定了选项
--with-readline，且客户端连接时指定-r参数，此功能被打开。客户端连接时内置-r参数，无需用户显式指定。 说明 - 客户端操作历史记录：vsql支持客户端操作历史记录，当客户端连接时指定
-r参数，此功能被打开。客户端连接时内置了-r参数，无需用户显式指定，本功能默认可用。
设置变量
vsql支持使用元命令\set设置一个变量，格式如下：
\set varname value
删除变量使用如下语法：
\unset varname
例如：把变量foo的值设置为bar：\set foo bar，如果想要引用变量的值，在变量前面加冒号。例如查看变量的值：\echo :foo
上述变量的引用方法适用于正规的SQL语句和元命令，除此之外vsql还包含一些特殊变量，同时也规划了变量的取值。为了保证和后续版本最大限度地兼容，请避免以其他目的使用这些变量。所有特殊变量见表1. 特殊变量设置。
- 所有特殊变量都由大写字母、数字和下划线组成。
- 要查看特殊变量的默认值，请使用元命令\echo
（例如\echo ）。
| 变量 | 设置方法 | 变量说明 |
|---|---|---|
| DBNAME | \set DBNAME dbname |
当前连接的数据库的名称。每次连接数据库时都会被重新设置。 |
| ECHO | \set ECHO all | queries |
|
| ECHO_HIDDEN | \set ECHO_HIDDEN on | off | noexec |
当使用元命令查询数据库信息（例如\dg）时，此变量的取值决定了查询的行为： |
| ENCODING | \set ENCODING encoding |
当前客户端的字符集编码。 |
| FETCH_COUNT | \set FETCH_COUNT variable |
|
| HOST | \set HOST hostname |
已连接的数据库主机名称。 |
| IGNOREEOF | \set IGNOREEOF variable |
|
| LASTOID | \set LASTOID oid |
最后影响的 oid 值，即为从一条 INSERT 或 lo_import 命令返回的值。此变量只保证在下一条 SQL 语句的结果显示之前有效。 |
| ON_ERROR_ROLLBACK | \set ON_ERROR_ROLLBACK on | interactive | off |
|
| ON_ERROR_STOP | \set ON_ERROR_STOP on | off |
|
| PORT | \set PORT port |
正连接数据库的端口号。 |
| USER | \set USER username |
当前用于连接的数据库用户。 |
| VERBOSITY | \set VERBOSITY terse | default | verbose |
这个选项可以设置为值 terse、default、verbose 之一以控制错误报告的冗余行。 |
SQL代换
vsql变量可以把变量替换成正规的SQL语句，并且vsql还支持为变量更换新的别名或其他标识符等功能。使用SQL代换的方式替换一个变量的值可以在变量前面加上冒号，例如，执行如下命令即可查询系统表PG_PROC。
1.执行元命令设置别名。
\set foo 'pg_proc'
```
2.通过元命令查询系统表。
```sql
select * from :foo;
```
变量的值是逐字复制的，甚至可以包含不对称的引号或反斜杠命令。所以必须保证输入的内容有意义。
提示符
通过如下变量可以设置vsql的提示符，这些变量是由字符和特殊的转义字符所组成。
表2 提示符
| 变量 | 描述 | 示例 |
|---|---|---|
| PROMPT1 | vsql 请求一个新命令时使用的正常提示符。PROMPT1 的默认值为：%/%R%# |
使用变量 PROMPT1切换提示符： |
| PROMPT2 | 在一个命令输入期待更多输入时（例如，查询没有用一个分号结束或者引号不完整）显示的提示符。 | 使用变量 PROMPT2显示提示符：\set PROMPT2 TESTselect * from pg_proc TEST; |
| PROMPT3 | 当执行 COPY 命令，并期望在终端输入数据时（例如，COPY FROM STDIN），显示提示符。 | 使用变量 PROMPT3显示 COPY 提示符：\set PROMPT3 '>>>>'copy pg_proc from STDIN; |
提示符变量的值是按实际字符显示的，但是，当设置提示符的命令中出现%时，变量的值根据%后的字符，替换为已定义的内容，已定义的提示符请参见下表：
表3 已定义的提示符
| 符号 | 符号说明 |
|---|---|
| %M | 主机的全名（包含域名），若连接是通过 Unix 域套接字进行的，则全名为[local]，若 Unix 域套接字不是编译的缺省位置，就是[local:/dir/name]。 |
| %m | 主机名删去第一个点后面的部分。若通过 Unix 域套接字连接，则为[local]。 |
| %> | 主机正在侦听的端口号。 |
| %n | 数据库会话的用户名。 |
| %/ | 当前数据库名称。 |
| %~ | 类似%/，如果数据库是缺省数据库时输出的是波浪线~。 |
| %# | 如果会话用户是数据库系统管理员，使用#，否则用>。 |
| %R | |
| %x | 事务状态： |
| %digits | 指定字节值的字符将被替换到该位置。 |
| %:name | vsql 变量“name”的值。 |
| %command | command 的输出，类似于使用“^”替换。 |
| %[ . . . %] | 提示可以包含终端控制字符，这些字符可以改变颜色、背景、提示文本的风格、终端窗口的标题。例如，\set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%#' |
命令自动补齐
根据VexDB语法规则，vsql支持使用Tab键进行命令的自动补齐，当编译时指定了选项--with-readline，且客户端连接时指定-r参数，此功能被打开。例如，crea后键入Tab，vsql会将其补齐为create。
客户端连接时内置了-r参数，无需用户显式指定。
- 支持数据库SQL关键字如SELECT 、CREATE、TABLE等。
- 支持表名、视图名等自定义标识符的补齐。
- 元命令选项'S'、'+'不支持自动补齐。
- 对系统表进行补齐时，前缀是“pg_”、“gs_”、“vb_” 才会补齐系统表。
- 不支持建表时字段类型的补齐。
- SELECT后不支持任何补齐。
- 不支持常量与宏的自动补齐。
- select * from a,b...不支持第二个开始表的自动补齐, insert into t1 (col1, col2, ...)不支持第二个列的自动补齐。
- 不支持create tablespace语句with以及with后参数的自动补齐。
- 创建索引不支持local、global的自动补齐，修改索引不支持rebuild自动补齐。
- set语句仅支持自动补全USER和SUPERUSER级别的参数。
- 不支持if exists的自动补齐。
- 不支持表名.列名的自动补齐，如
alter sequence。owned by tableName.colName，owned by - 不支持自定义操作符自动补齐。使用复制粘贴这种方式输入命令，如果粘贴的命令里面有TAB键有可能会使输入命令的格式错乱，无法正常执行。
\t\n@$><=;|&{()这些特殊字符在sql语句中具有固定含义。如果自定义表名中包含这些特殊字符，那么输入的sql语句从这些字符开始不支持自动补齐。
客户端操作历史记录
vsql支持客户端操作历史记录，当客户端连接时指定-r参数，此功能被打开。可以通过\set设置记录历史的条数，例如，\set HISTSIZE 50，将记录历史的条数设置为50，\set HISTSIZE 0，不记录历史。
客户端连接时内置了-r参数，无需用户显式指定。 客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端交互式输入包含中文字符时，只支持UTF-8 的编码环境。 出于安全考虑，将包含PASSWORD、IDENTIFIED敏感词的记录识别为敏感信息，不会记录到历史信息中，即不能通过上下翻回显。
环境变量
与vsql相关的环境变量如下表所示：
表4 与vsql相关的环境变量
| 名称 | 描述 |
|---|---|
| COLUMNS | 如果\set columns为0，则由此参数控制 wrapped 格式的宽度。这个宽度用于决定在自动扩展的模式下，是否要把宽输出模式变成竖线的格式。 |
| PAGER | 如果查询结果无法在一页显示，它们就会被重定向到这个命令。可以用\pset 命令关闭分页器。典型的是用命令 more 或 less 来实现逐页查看。缺省值是平台相关的。说明：less 的文本显示，受系统环境变量 LC_CTYPE 影响。 |
| PSQL_EDITOR | \e 和\ef 命令使用环境变量指定的编辑器。变量是按照列出的先后顺序检查的。在 Unix 系统上默认的编辑工具是 vi。 |
| EDITOR | |
| VISUAL | |
| PSQL_EDITOR_LINENUMBER_ARG | 当\e 和\ef 带上一行数字参数使用时，这个变量指定的命令行参数用于向编辑器传递起始行数。像 Emacs 或 vi 这样的编辑器，这只是个加号。如果选项和行号之间需要空白，在变量的值后加一个空格。例如：PSQL_EDITOR_LINENUMBER_ARG = '+'PSQL_EDITOR_LINENUMBER_ARG='--line 'Unix 系统默认的是+。 |
| PSQLRC | 用户的.vsqlrc 文件的交互位置。 |
| SHELL | 使用 \! 命令跟 shell 执行的命令是一样的效果。 |
| TMPDIR | 存储临时文件的目录。缺省是/tmp。 |
获取帮助
vsql--help
help;
You are using vsql, the command-line interface to postgres.
Type: \copyright for distribution terms
\h for help with SQL commands
\? for help with vsqlcommands
\g or terminate with semicolon to execute query
\q to quit
- 查看VexDB支持的所有SQL语句。
\h - 查看某条语句的命令帮助，例如查看CREATE DATABASE命令的参数可使用下面的命令：
\help CREATE DATABASE
语法格式
vsql [OPTION]... [DBNAME [USERNAME]]
DBNAME：声明要连接的数据库名称。
参数说明
通用参数
- -c, --command=COMMAND
声明vsql要执行一条字符串命令然后退出。 - -d, --dbname=DBNAME
指定想要连接的数据库名称。另外vsql允许使用直接在命令行上指定DBNAME。
此外vsql允许使用扩展的DBNAME，即'postgresql://[user或@][netloc][ ][,...][/dbname]?param1=value1&...' 'key=value ...'形式的连接串作为DBNAME，vsql将从连接串中解析连接信息。 - -f, --file=FILENAME
使用文件作为命令源而不是交互式输入。vsql将在处理完文件后结束。如果FILENAME是-（连字符），则从标准输入读取。
取值范围：绝对路径或相对路径。 - -l, --list
列出所有可用的数据库，然后退出。 - -v, --set=, --variable=NAME=VALUE
使用vsql设置变量。类似于使用元命令\set进行变量设置。变量的示例和详细说明请参见设置变量。 - -X, --no-vsqlrc
不读取启动文件，启动文件默认为~/.vsqlrc。 - -1 ("one"), --single-transaction
当vsql使用-1选项执行脚本时，会在脚本的开头和结尾分别加上START TRANSACTION/COMMIT用以把整个脚本当作一个事务执行。这将保证该脚本完全执行成功，或者脚本无效。 - -?, --help
显示关于vsql命令行参数的帮助然后退出。
输入输出参数
- -a, --echo-all
在读取行时向标准输出打印所有内容。
使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - -e, --echo-queries
把所有发送给服务器的查询同时回显到标准输出。
使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。 - -E, --echo-hidden
回显由\d等其他反斜杠命令生成的实际查询。 - -D, --with-decryption=SWS-KMS-SM4/TAS-KMS-SM4
解密方式。主要是针对vb_dump生成的文件，使用vsql解析的时候选择的解密方式，包括SWS-KMS-SM4或TAS-KMS-SM4。 - -k, --with-key=KEY
使用vsql对导入的加密文件进行解密。 说明- 对于本身就是shell命令中的关键字符如单引号（'）或双引号（"），Linux shell会检测输入的单引号（'）或双引号（"）是否匹配。如果不匹配，shell认为用户没有输入完毕，会一直等待用户输入，从而不会进入到vsql程序。
- 不支持解密导入存储过程和函数。
- -L, --log-file=FILENAME
除了正常的输出源之外，把所有查询输出记录到指定的FILENAME文件中。
取值范围：绝对路径或相对路径。 说明- 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。
- 此参数只保留查询结果到相应文件中，主要目标是为了查询结果能够更好更准确地被其他调用者（例如自动化运维脚本）解析，而不是保留vsql运行过程中的相关日志信息。
- -m, --maintenance
允许在两阶段事务恢复期间连接VexDB。该选项是一个开发选项，禁止用户使用，只限专业技术人员使用。功能是：使用该选项时，vsql可以连接到备机，用于校验主备机数据的一致性。 说明 - -n, --no-libedit
关闭命令行编辑。 - -o, --output=FILENAME
将所有查询输出重定向到文件FILENAME中。
取值范围：绝对路径或相对路径。 - -q, --quiet
安静模式，指定该选项在执行vsql命令时不会打印出额外信息。 - -C, --enable-client-encryption
当使用-C参数连接本地数据库或者远程连接数据库时，可通过该选项打开全密态数据库开关。 - -s, --single-step
单步模式运行。意味着每个查询在发往服务器之前都要提示用户，用这个选项也可以取消执行。此选项主要用于调试脚本。 - -S, --single-line
单行运行模式，这时每个命令都将由换行符结束，像分号那样。
输入格式参数
- -A, --no-align
切换为非对齐输出模式。 - -F, --field-separator=STRING
设置域分隔符，默认为“|”。 - -H, --html
打开HTML格式输出。 - -P, --pset=VAR=ARG
在命令行上以\pset的风格设置打印选项。该选项是一个开发选项，禁止用户使用，只限专业技术人员使用。功能是：使用该选项时，vsql可以连接到备机，用于校验主备机数据的一致性。 说明 - -R, --record-separator=STRING
设置记录分隔符。 - -r
开启在客户端操作中可以进行编辑的模式。
客户端连接时内置了-r参数，无需用户显式指定，但若用户显式指定-r参数也不会报错。 - -t, --tuples-only
只打印行。 - -T, --table-attr=TEXT
允许声明放在HTML table标签里的选项。
该参数使用时需搭配-H, --html参数一起使用，指定输出为HTML格式。 - -x, --expanded
打开扩展表格式模式。 - -z, --field-separator-zero
设置非对齐输出模式的域分隔符为空。
该参数使用时需搭配-A, --no-align参数一起使用，指定非对齐输出模式。 - -0, --record-separator-zero
设置非对齐输出模式的记录分隔符为空。
该参数使用时需搭配-A, --no-align参数一起使用，指定非对齐输出模式。 - -2, --pipeline
使用管道传输密码，禁止在终端使用，必须和-c或者-f参数一起使用。
连接选项
- -h, --host=HOSTNAME
指定正在运行服务器的主机名或者Unix域套接字的路径。
如果省略主机名，vsql将通过Unix域套接字与本地主机的服务器相连，或者在没有Unix域套接字的机器上，通过TCP/IP与localhost连接。 - -p, --port=PORT
指定数据库服务器的端口号。可以通过修改配置文件postgresql.conf中port参数修改默认端口号。
默认值：5432 - -U, --username=USERNAME
指定连接数据库的用户。
取值范围：字符串，默认使用与当前操作系统用户同名的用户。 说明- 通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。您可以通过交换方式输入密码，或者通过-W参数指定密码。
- 用户名中包含有字符$，需要在字符$前增加转义字符才可成功连接数据库。
- -W, --password=PASSWORD
当使用-U参数连接数据库时，可通过该选项指定密码。
元命令参考
该部分介绍使用VexDB数据库命令行交互工具登录数据库后，vsql所提供的元命令。所谓元命令就是在vsql里输入的任何以不带引号的反斜杠开头的命令。
用户想要知道VexDB支持的元命令有哪些，可以连接到数据库之后执行如下命令：
\?
一般元命令
- \copyright
显示VexDB的版权信息。 - \g FILE or ;
把当前查询缓冲区的内容发送给服务器并且把查询的输出存到文件中，或者将输出重定向到到shell命令。
单独一个\g实际上等效于一个分号。 - \h(\help) NAME
给出指定SQL语句的语法帮助。
如果没有给出NAME，vsql将列出可获得帮助的所有命令。如果NAME是一个星号（*），则显示所有SQL语句的语法帮助。 - \parallel on num|off
控制并发执行开关。
取值范围：on，off - on：打开控制并发执行开关，且最大并发数为num。
- off：关闭控制并发执行开关。
- 不支持事务中开启并发执行以及并发中开启事务。
- 不支持\d这类元命令的并发。
- 不推荐在并发中使用set语句，否则导致结果与预期不一致。
- parallel内部不允许创建临时表。如需使用临时表，需要在开启parallel之前创建好，并在parallel内部使用。
- \parallel中所有作业的持续时间不能超过session_timeout，否则可能会导致并发执行过程中断连。
- 在\parallel on之后一条或多条命令，会等到\parallel off命令执行后才会执行，因而，每个\parallel on需对应一个\parallel off，否则会导致\parallel on之后的命令无法执行。
- 服务器能接受的最大连接数受max_connections及当前已有连接数限制。
- 设置num时请考虑服务器当前可接受的实际连接数合理指定。
- \q
退出vsql程序。
默认值：100
查询缓存区元命令
- \e FILE LINE
使用外部编辑器编辑查询缓冲区或者文件。 - \ef FUNCNAME LINE
使用外部编辑器编辑函数定义。如果指定了LINE（即行号），则光标会指到函数体的指定行。 - \p
打印当前查询缓冲区到标准输出。 - \r
重置（或清空）查询缓冲区。 - \w FILE
将当前查询缓冲区内容输出到指定文件。
输入/输出元命令
- \copy ...
在任何vsql客户端登录数据库成功后使用该命令可以执行导入导出数据。
这是一个运行SQL语句COPY命令的操作，与COPY命令不同的是，COPY命令是服务去在读写指定文件，而vsql读写文件是作为本地的文件系统和服务器之间的跳板取出或写入数据。这意味着文件访问性和权限都是本地用户的，而不是服务器的，因此不需要SQL超级用户权限。 说明- \COPY只适合小批量，格式良好的数据导入，不会对非法字符进行预处理，也无容错能力。导入数据应优先选择COPY。
- \COPY支持分批导入：对导入数据的总行数进行分批，用户可以手动指定每批数据的行数（batch_size）。详情参考使用元命令导入数据。
- \COPY可以指定数据导入时的客户端数量，从而实现数据文件的并行导入，目前并发数范围为[1, 8]。
- \COPY并行导入目前存在以下约束:
- 不支持临时表、二进制文件以及事务内的并行导入。
- 数据导入支持AES128加密时不支持并行导入。
- 在这些情况下，即使指定了parallel参数，仍然会走非并行流程。
- \echo STRING
把字符串写到标准输出。 - \i FILE
从文件FILE中读取内容，并将其当作输入，执行查询。 - \i+ FILE KEY
对vb_dump/vb_dumpall生成的文件进行解密。 - \i+ FILE KEY USERPIN
执解密操作的用户名和密码。 - \ir FILE
和\i类似，只是对相关文件名的解析不同。
当在交互模式执行时，两个命令的表现相同。不过，当在脚本中调用时， \ir解释文件名关系为脚本所在的目录，而不是当前工作目录。 - \ir+ FILE KEY
和\i+类似，是对相关文件名的解析不同。 - \ir+ FILE KEY USERPIN
执解密操作的用户名和密码。 - \o FILE
把所有的查询结果发送到文件里。 - \qecho STRING
把字符串写到查询结果输出流里。
显示信息元命令
选项S表示显示系统对象。 选项+表示显示对象附加的描述信息。 PATTERN用来指定要被显示的对象名称。以下元命令中如果声明了PATTERN，只显示名称匹配PATTERN的内容。
- \dS+
列出当前search_path中模式下所有的表、视图和序列。 - \dS+ NAME
列出指定表、视图和索引的结构。
假设存在表a，列出指定表a的结构：\dtable+ a - \d+ PATTERN
列出所有表、视图和索引。支持\d时展示 disable 状态的约束/索引，由vb_enable_show_disabled_constraints参数控制，默认开启，表示支持展示。
例如，列出所有名称以f开头的表、视图和索引：\d+ f* - \daS PATTERN
列出所有可用的聚集函数以及它们操作的数据类型和返回值类型。
例如，列出所有名称以f开头可用的聚集函数以及它们操作的数据类型和返回值类型：\da f* - \db+ PATTERN
列出所有可用的表空间。
例如，列出所有名称以p开头的可用表空间：\db p* - \dcS+ PATTERN
列出所有字符集编码之间的转换
例如，列出所有名称以c开头的字符集编码转换：\dc c* - \dC+ PATTERN
列出所有类型转换。
例如，列出所有名称以c开头的类型转换：\dC c* - \ddS PATTERN
显示所有匹配PATTERN的描述。如果没有给出参数，则显示所有可视对象。包括：聚集、函数、操作符、类型、关系（表、视图、索引、序列、大对象）、规则。
例如，列出所有可视对象：\dd - \ddp PATTERN
显示所有默认的使用权限。
例如，列出所有默认的使用权限：\ddp - \dDS+ PATTERN
列出所有可用域。
例如，列出所有可用域：\dD - \ded+ PATTERN
列出所有的Data Source对象。
例如，列出所有的Data Source对象：\ded - \det+ PATTERN
列出所有的外部表。 - \des+ PATTERN
列出所有的外部服务器。 - \deu+ PATTERN
列出用户映射信息。 - \dew+ PATTERN
列出封装的外部数据。 - \df[antw]S+ PATTERN
列出所有可用函数以及它们的参数和返回的数据类型。- a：代表聚集函数。
- n：代表普通函数。
- t：代表触发器。
- w：代表窗口函数。
- \dF+ PATTERN
列出所有的文本搜索配置信息。
例如，列出所有的文本搜索配置信息：\dF+ - \dFd+ PATTERN
列出所有的文本搜索字典。 - \dFp+ PATTERN
列出所有的文本搜索分析器。 - \dFt+ PATTERN
列出所有的文本搜索模板。 - \dg+ PATTERN
列出所有数据库角色。因为用户和群组的概念被统一为角色，所以这个命令等价于\du。 - \dl
\lo_list的别名，显示一个大对象的列表。 - \dLS+ PATTERN
列出可用的程序语言。 - \dmS+ PATTERN
列出物化视图。 - \dnS+ PATTERN
列出所有的模式（名称空间）。 - \doS PATTERN
列出所有可用的操作符以及它们的操作数和返回的数据类型。 - \dOS+ PATTERN
列出排序规则。 - \dp PATTERN
列出一列可用的表、视图以及相关的权限信息。 - rolename=xxxx/yyyy：赋予一个角色的权限。
- =xxxx/yyyy：赋予public的权限。
- 对于过程语言，允许用户在创建函数时，指定过程语言。
- 对于模式，允许访问包含在指定模式中的对象。
- 对于序列，允许使用 nextval 函数。
- 对于数据库，允许在该数据库里创建新的模式。
- 对于模式，允许在该模式中创建新的对象。
- 对于序列，允许使用 nextval 函数。
- 对于表空间，允许在其中创建表以及允许创建数据库和模式的时候把该表空间指定为其缺省表空间。
- \drds PATTERN1 PATTERN2
列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。 说明- PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。
- 如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省或指定*时，则会列出所有设置。
例如，列出postgres数据库所有修改过的配置参数。\drds * postgres - \dTS+ PATTERN
列出所有的数据类型。 - \du+ PATTERN
列出所有数据库角色。
因为用户和群组的概念被统一为角色，所以这个命令等价于\dg。 - \dES+ PATTERN，\diS+ PATTERN，\dsS+ PATTERN，\dtS+ PATTERN，\dvS+ PATTERN
这一组命令，字母E、i、s、t和v分别代表着外部表、索引、序列、表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。
例如：\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。
默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。 - \dx+ PATTERN
列出安装数据库的扩展信息。 - \l+
列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。 - \sf+ FUNCNAME
显示函数的定义。
对于带圆括号的函数名，需要在函数名两端添加双引号，并且在双引号后面加上参数类型列表。参数类型列表两端添加圆括号。
假设存在函数名带圆括号的函数func()name，列出函数的定义。\sf "func()name"(argtype1, argtype2) - \z PATTERN
列出数据库中所有表、视图和序列以及它们相关的访问特权。如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。 - \a
对齐模式和非对齐模式之间的切换。 - \C STRING
把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。 - \f STRING
对于不对齐的查询输出，显示或者设置域分隔符。 - \H
- 若当前模式为文本格式，则切换为HTML输出格式。
- 若当前模式为HTML格式，则切换回文本格式。
- \pset NAME VALUE
设置影响查询结果表输出的选项。NAME的取值见下表可调节的打印选项。
表6 可调节的打印选项选项 选项说明 取值范围 border value 必须是一个数字。通常这个数字越大，表的边界就越宽线就越多，但是这个取决于特定的格式。 在 HTML 格式下，取值范围为大于0的整数。
在其他格式下，取值范围：0（无边框），1（内部分隔线），2（台架）。expanded (或 x) 在正常和扩展格式之间切换。 当打开扩展格式时，查询结果用两列显示，字段名称在左、数据在右。这个模式在数据无法放进通常的“水平”模式的屏幕时很有用。
在正常格式下，当查询输出的格式比屏幕宽时，用扩展格式。正常格式只对 aligned 和 wrapped 格式有用。fieldsep 声明域分隔符来实现非对齐输出。这样就可以创建其他程序希望的制表符或逗号分隔的输出。要设置制表符域分隔符，键入\pset fieldsep '\t'。缺省域分隔符是 '|' (竖条符)。 - fieldsep_zero 声明域分隔符来实现非对齐输出到零字节。 - footer 用来切换脚注。 - format 设置输出格式。允许使用唯一缩写（这意味着一个字母就够了）。 取值范围：
unaligned：写一行的所有列在一条直线上中，当前活动字段分隔符分隔。
aligned：此格式是标准的，可读性最好的文本输出。
wrapped：类似 aligned，但是包装跨行的宽数据值，使其适应目标字段的宽度输出。
html：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。
latex：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。
troff-ms：把表输出为可用于文档里的对应标记语言。输出不是完整的文档。null 打印一个字符串，用来代替一个 null 值。 缺省是什么都不打印，这样很容易和空字符串混淆。 numericlocale 切换分隔小数点左边的数值的区域相关的分组符号。 on：显示指定的分隔符。
off：不显示分隔符。
忽略此参数，显示默认的分隔符。pager 控制查询和 vsql 帮助输出的分页器。如果设置了环境变量 PAGER，输出将被指向到指定程序，否则使用系统缺省。 on：当输出到终端且不适合屏幕显示时，使用分页器。
off：不使用分页器。
always：当输出到终端无论是否符合屏幕显示时，都使用分页器。recordsep 声明在非对齐输出格式时的记录分隔符。 - recordsep_zero 声明在非对齐输出到零字节时的记录分隔符。 - tableattr（或 T） 声明放在 html 输出格式中 HTML table 标签的属性（例如：cellpadding 或 bgcolor）。注意：这里可能不需要声明 border，因为已经在\pset border 里用过了。如果没有给出 value，则不设置表的属性。 - title 为随后打印的表设置标题。这个可以用于给输出一个描述性标签。如果没有给出 value，不设置标题。 - tuples_only （或者 t） 在完全显示和只显示实际的表数据之间切换。完全显示将输出像列头、标题、各种脚注等信息。在 tuples_only 模式下，只显示实际的表数据。 - feedback 切换是否输出结果行数。 - 连接元命令
- \connect DBNAME|- USER|- HOST|- PORT|-
连接到一个新的数据库。当数据库名称长度超过127个字节时，默认前127个字节有效，连接到前127个字节对应的数据库，但是vsql的命令提示符中显示的数据库对象名仍为截断前的名称。
重新建立连接时，如果切换数据库登录用户，将可能会出现交互式输入，要求输入新用户的连接密码。该密码最长长度为999字节，受限于GUC参数password_max_length的最大值。 - \encoding ENCODING
设置客户端字符编码格式。不带参数时，显示当前的编码格式。 - \conninfo
输出当前连接的数据库的信息。
操作系统元命令
- \cd DIR
切换当前的工作目录。
取值范围：绝对路径或相对路径，且满足操作系统路径命名规则。 - \setenv NAME VALUE
设置环境变量NAME为VALUE，如果没有给出VALUE值，则不设置环境变量。 - \timing on|off
以毫秒为单位显示每条SQL语句的执行时间（不包括屏显打印时间）。
on表示打开显示。
off表示关闭显示。 - ! COMMAND
返回到一个单独的Unix shell或者执行Unix命令COMMAND。
变量元命令
- \prompt TEXT NAME
提示用户用文本格式来指定变量名称。 - \set NAME VALUE
设置内部变量NAME为VALUE或者如果给出了多于一个值，设置为所有这些值的连接结果。如果没有给出第二个参数，只设变量不设值。
有一些常用变量被SQL特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)，具体请参考下表。
表7 \set常用命令名称 命令说明 取值范围 \set VERBOSITY value 控制错误报告的冗余行。 value 取值范围：default， verbose，terse \set ON_ERROR_STOP value 如果设置了这个变量，脚本处理将马上停止。如果该脚本是从另外一个脚本调用的，那个脚本也会按同样的方式停止。如果最外层的脚本不是从一次交互的 vsql 会话中调用的而是用-f 选项调用的，vsql 将返回错误代码3，以示这个情况与致命错误条件的区别（错误代码为1）。 value 取值范围为：on/off，true/false，yes/no，1/0 \set RETRY [retry_times] 用于控制是否开启语句出错场景下的重试功能，参数 retry_times 用来指定最大重试次数，缺省值为5，取值范围为5-10。当重试功能已经开启时，再次执行\set RETRY可以关闭该功能。使用配置文件 retry_errcodes.conf 列举需要重试的错误码列表，该文件和 vsql 可执行程序位于同一级目录下。该配置文件为系统配置，非用户定义，不允许用户直接修改。支持的错误场景如下所示：
YY001：TCP 通信错误，对端连接重置。
YY002：TCP 通信错误，对端流重置。
YY003：锁等待超时。
YY004：TCP 通信错误，连接超时。
YY005：SET 命令发送失败，查询设置错误。
YY006：内存申请失败。
YY007：通信库错误，通信库内存分配错误。
YY008：通信库错误，无通信库缓存数据。
YY009：通信库错误，通信库释放内存关闭。
YY0010：通信库错误，SCTP、TCP 断开。
YY0011：通信库错误，通信库断开。
YY0012：通信库错误，通信库远程关闭。
YY0013：通信库错误，等待未知通信库通信。
YY0014：通信库错误，无效快照。
YY0015：通信库错误，通讯接收信息错误。
53200：内存耗尽。
08006：连接失败。
08000：连接异常。
57P01：管理员关闭系统。
XX003：关闭远程流接口。
XX009：重复查询编号。
说明
1、不支持事务块中的语句错误重试。
2、不支持通过 ODBC、JDBC 接口查询的出错重试。
3、含有 unlogged 表的 sql 语句，不支持节点故障后的出错重试。
4、vsql 客户端本身出现的错误，不在重跑考虑范围之内。retry_times 取值范围为：5-10 - \unset NAME
不设置（或删除）vsql变量名。
大对象元命令
\lo_list
显示一个目前存储在该数据库里的所有VexDB大对象和提供给它们的注释。示例
前提条件
vsql连接数据库时使用的用户需要具备访问数据库的权限。操作步骤
使用vsql连接postgres数据库。
vsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。 - \unset NAME
- 若未指定数据库名称，则使用初始化时默认生成的数据库名称。
- 若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名。
- 当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d）则该参数会被解释成数据库名。
- 如果已经指定数据库名（-d）而没有指定数据库用户名（-U）时，该参数则会被解释成数据库用户名。
- 连接数据库。
- 执行SQL语句。
- 执行vsql元命令。
- 开启log_hostname参数，但是配置了错误的DNS导致的连接性能问题。
连接上数据库，通过show log_hostname语句，检查数据库中是否开启了log_hostname参数。
如果开启了相关参数，那么数据库内核会通过DNS反查客户端所在机器的主机名。这时如果数据库主节点配置了不正确的或者不可达的DNS服务器，那么会导致数据库建立连接过程较慢。log_hostname参数详细请参见log_hostname参数。 - 数据库内核执行初始化语句较慢导致的性能问题。
此种情况定位较难，可以尝试使用Linux的跟踪命令：strace。strace vsql -U MyUserName -W MyPassWord -d postgres -h 127.0.0.1 -p 23508 -r -c '\q'
此时便会在屏幕上打印出数据库的连接过程。比如较长时间停留在下面的操作上：sendto(3, "Q\0\0\0\25SELECT VERSION()\0", 22, MSG_NOSIGNAL, NULL, 0) = 22 poll([{fd=3, events=POLLIN|POLLERR}], 1, -1) = 1 ([{fd=3, revents=POLLIN}])
此时便可以确定是数据库执行SELECT VERSION();语句较慢。
在连接上数据库后，便可以通过执行explain performance select version();语句来确定初始化语句执行较慢的原因。
另外还有一种场景不太常见：由于数据库主节点所在机器的磁盘满或故障，此时所查询等受影响，无法进行用户认证，导致连接过程挂起，表现为假死。解决此问题清理数据库主节点的数据盘空间便可。 - TCP连接创建较慢问题。
此问题可以参考上面的初始化语句较慢排查的做法，通过strace跟踪，如果长时间停留在：connect(3, {sa_family=AF_FILE, path="/home/test/tmp/gaussdb_llt1/.s.Pvsql.61052"}, 110) = 0
或者connect(3, {sa_family=AF_INET, sin_port=htons(61052), sin_addr=inet_addr("127.0.0.1")}, 16) = -1 EINPROGRESS (Operation now in progress)
那么说明客户端与数据库端建立物理连接过慢，此时应当检查网络是否存在不稳定、网络吞吐量太大的问题。 - vsql: could not connect to server: No route to host
此问题一般是指定了不可达的地址或者端口导致的。请检查-h参数与-p参数是否添加正确。 - vsql: FATAL: Invalid username/password,login denied.
此问题一般是输入了错误的用户名和密码导致的，请联系数据库管理员，确认用户名和密码的正确性。 - vsql: FATAL: Forbid remote connection with trust method!
数据库由于安全问题，禁止远程登录时使用trust模式。这时需要修改pg_hba.conf文件里的连接认证信息。 说明- 请不要修改pg_hba.conf中VexDB主机的相关设置，否则可能导致数据库功能故障。
- 建议业务应用部署在VexDB之外，而非VexDB内部。
- 连接数据库，添加-h 127.0.0.1可以连接，去掉后无法连接问题。
通过执行SQL语句show unix_socket_directory;检查数据库主节点使用的Unix套接字目录，是否与shell中的环境变量$PGHOST一致。
如果检查结果不一致，那么修改PGHOST环境变量到GUC参数unix_socket_directory指向的目录便可。
关于unix_socket_directory的更多信息，详见GUC参数说明unix_socket_directory。 - The “libpq.so” loaded mismatch the version of vsql, please check it.
此问题是由于环境中使用的libpq.so的版本与vsql的版本不匹配导致的，请通过“ldd vsql”命令确认当前加载的libpq.so的版本，并通过修改LD_LIBRARY_PATH环境变量来加载正确的libpq.so。 - vsql: symbol lookup error: xxx/vsql: undefined symbol: libpqVersionString
此问题是由于环境中使用的libpq.so的版本与vsql的版本不匹配导致的（也有可能是环境中存在PostgreSQL的libpq.so），请通过“ldd vsql”命令确认当前加载的libpq.so的版本，并通过修改LD_LIBRARY_PATH环境变量来加载正确的libpq.so。 - vsql: connect to server failed: Connection timed out
Is the server running on host “xx.xxx.xxx.xxx” and accepting TCP/IP connections on port xxxx?
此问题是由于网络连接故障造成。请检查客户端与数据库服务器间的网络连接。如果发现从客户端无法PING到数据库服务器端，则说明网络连接出现故障。请联系网络管理人员排查解决。 - vsql: FATAL: permission denied for database “postgres”
DETAIL: User does not have CONNECT privilege.
此问题是由于用户不具备访问该数据库的权限，可以使用如下方法解决。
1、使用管理员用户dbadmin连接数据库。vsql -d postgres -U dbadmin -p 5432
2、赋予用户user1访问数据库的权限。GRANT CONNECT ON DATABASE postgres TO user1;
实际上，常见的许多错误操作也可能产生用户无法连接上数据库的现象。如用户连接的数据库不存在，用户名或密码输入错误等。这些错误操作在客户端工具也有相应的提示信息。- vsql: FATAL: sorry, too many clients already，active/non-active: 2/10/3.
此问题是由于系统连接数量超过了最大连接数量。请联系数据库DBA进行会话连接数管理，释放无用会话。 - 会话状态可以在视图PG_STAT_ACTIVITY中查看。无用会话可以使用函数pg_terminate_backend进行释放。
例如：select datid,pid,state from pg_stat_activity;
返回结果如下：datid | pid | state -------+-----------------+-------- 17694 | 140381980522240 | active 17694 | 140381812676352 | 17694 | 140381846238976 | 17694 | 140381795895040 | active 17694 | 140381745510144 | idle 17694 | 140381615351552 | active 17694 | 140381581788928 | 17694 | 140381598570240 | 17693 | 140381460035328 | active (9 rows)
其中pid的值即为该会话的线程ID。根据线程ID结束空闲会话140381745510144。SELECT PG_TERMINATE_BACKEND(140381745510144);
返回结果如下：pg_terminate_backend ---------------------- t (1 row) - vsql: wait xxx.xxx.xxx.xxx:xxxx timeout expired
vsql在向数据库发起连接的时候，会有5分钟超时机制，如果在这个超时时间内，数据库未能正常的对客户端请求进行校验和身份认证，那么vsql会退出当前会话的连接过程，并报出如上错误。
一般来说，此问题是由于连接时使用的-h参数及-p参数指定的连接主机及端口有误（即错误信息中的xxx部分），导致通信故障；极少数情况是网络故障导致。要排除此问题，请检查数据库的主机名及端口是否正确。 - vsql: could not receive data from server: Connection reset by peer.
同时，检查数据库主节点日志中出现类似如下日志“ FATAL: cipher file “/data/dbnode/server.key.cipher” has group or world access”，一般是由于数据目录或部分关键文件的权限被误操作篡改导致。请参照其他正常实例下的相关文件权限，修改回来便可。 - vsql: FATAL: GSS authentication method is not allowed because XXXX user password is not disabled.
目标数据库主节点的pg_hba.conf里配置了当前客户端IP使用“gss”方式来做认证，该认证算法不支持用作客户端的身份认证，请修改到"sha256"后再试。 说明- 请不要修改pg_hba.conf中VexDB主机的相关设置，否则可能导致数据库功能故障。
- 建议业务应用部署在VexDB之外，而非VexDB内部。
示例1： 使用vexdb用户连接到本机postgres数据库的5432端口。
vsql -d postgres -p 5432示例2： 使用jack用户连接到远程主机（10.180.123.163）postgres数据库的5432端口。
本步骤执行之前应配置远程客户端接入认证，更多配置方法参见配置客户端接入认证。
vsql -h 10.180.123.163 -d postgres -U jack -p 15400示例3： 参数postgres和vexdb不属于任何选项时，分别被解释成了数据库名和用户名。
vsql postgres vexdb -p 5432等效于：
vsql -d postgres -U vexdb -p 5432详细的vsql参数请参见参数说明。
创建数据库human_staff为例，通常，输入的命令行在遇到分号的时候结束。如果输入的命令行没有错误，结果就会输出到屏幕上。
CREATE DATABASE human_staff;例如列出VexDB中所有数据库和描述信息。
\l返回结果如下：
List of databases Name | Owner | Encoding | Collate | Ctype | Access privileges -----------+----------+----------+------------+------------+----------------------- postgres | vexdb | UTF8 | en_US.utf8 | en_US.utf8 | template0 | vexdb | UTF8 | en_US.utf8 | en_US.utf8 | =c/vexdb + | | | | | vexdb=CTc/vexdb template1 | vexdb | UTF8 | en_US.utf8 | en_US.utf8 | =c/vexdb + | | | | | vexdb=CTc/vexdb vexdb | vexdb | UTF8 | en_US.utf8 | en_US.utf8 | (4 rows)删除创建的数据库。
DROP DATABASE human_staff;更多vsql元命令请参见元命令参考。
常见问题处理
连接性能问题
创建连接故障
表8 查看用户会话连接数的方法
描述 命令 查看指定用户的会话连接数上限。 执行如下命令查看连接到指定用户 USER1的会话连接数上限。其中-1表示没有对用户 user1设置连接数的限制。 返回结果如下：SELECT ROLNAME,ROLCONNLIMIT FROM PG_ROLES WHERE ROLNAME='user1';
rolname | rolconnlimit
---------+--------------
user1 | -1
(1 row)查看指定数据库的会话连接数上限。 执行如下命令查看连接到指定数据库 postgres 的会话连接数上限。其中-1表示没有对数据库 postgres 设置连接数的限制。 返回结果如下：SELECT DATNAME,DATCONNLIMIT FROM PG_DATABASE WHERE DATNAME='postgres';
datname | datconnlimit
---------+--------------
postgres | -1
(1 row)查看指定数据库已使用的会话连接数。 执行如下命令查看指定数据库 postgres 上已使用的会话连接数。其中，1表示数据库 postgres 上已使用的会话连接数。 返回结果如下：SELECT COUNT(*) FROM PG_STAT_ACTIVITY WHERE DATNAME='postgres';
count
-------
1
(1 row)其他故障
出现因“总线错误”（Bus error）导致的core dump或异常退出。
一般情况下出现此种问题，是进程运行过程中加载的共享动态库（在Linux为.so文件）出现变化，或者进程二进制文件本身出现变化，导致操作系统加载机器的执行码或者加载依赖库的入口发生变化，操作系统出于保护目的将进程杀死，产生core dump文件。
解决此问题，重试便可。同时请尽可能避免在升级等运维操作过程中，在VexDB内部运行业务程序，避免升级时因替换文件产生此问题。
此故障的core dump文件的可能堆栈是dl_main及其子调用，它是操作系统用来初始化进程做共享动态库加载的。如果进程已经初始化，但是共享动态库还未加载完成，严格意义上来说，进程并未完全启动。 说明 - \connect DBNAME|- USER|- HOST|- PORT|-
xxxx表示赋予的权限，yyyy表示授予这个权限的角色。权限的参数说明请参见下表。
表5 权限的参数说明
| 参数 | 说明 | |
|---|---|---|
| r | SELECT：允许对指定的表、视图读取数据。 | |
| w | UPDATE：允许对指定表更新字段。 | |
| a | INSERT：允许对指定表插入数据。 | |
| d | DELETE：允许删除指定表中的数据。 | |
| D | TRUNCATE：允许清理指定表中的数据。 | |
| x | REFERENCES：允许创建外键约束。由于当前不支持外键，所以该参数暂不生效。 | |
| t | TRIGGER：允许在指定表上创建触发器。 | |
| X | EXECUTE：允许使用指定的函数以及利用这些函数实现的操作符。 | |
| U | USAGE：
|
|
| C | CREATE：
|
|
| c | CONNECT：允许用户连接到指定的数据库。 | |
| T | TEMPORARY：允许创建临时表。 | |
| A | ALTER：允许用户修改指定对象的属性。 | |
| P | DROP：允许用户删除指定的对象。 | |
| m | COMMENT：允许用户定义或修改指定对象的注释。 | |
| i | INDEX：允许用户在指定表上创建索引。 | |
| v | VACUUM：允许用户对指定的表执行 ANALYZE 和 VACUUM 操作。 | |
| * | 给前面权限的授权选项。 |
