vsql

功能描述

vsql是Vastbase提供的在命令行下运行的数据库连接工具，用户可以通过此工具连接服务器并对其进行操作和维护，除了具备操作数据库的基本功能，vsql还提供了若干高级特性，便于用户使用。

基本功能

• 连接数据库： 详情请参考使用vsql连接。

• 执行SQL语句： 支持交互式地键入并执行SQL语句，也可以执行一个文件中指定的SQL语句。

• 执行元命令： 元命令可以帮助管理员查看数据库对象的信息、查询缓存区信息、格式化SQL输出结果、以及连接到新的数据库等。元命令的详细说明请参见元命令参考。

  

  在vsql里输入的任何以不带引号的反斜杠开头的命令都是vsql元命令，这些命令是将由vsql自己处理的，元命令通常也被称为斜杠或反斜杠命令。

高级特性

vsql支持的高级特性包括

• 设置变量：vsql提供类似于Linux的shell命令的变量特性，可以使用vsql的元命令\set设置一个变量。

• SQL代换：利用vsql的变量特性，可以将常用的SQL语句设置为变量，以简化操作。

• 支持用户自定义提示符：vsql使用的提示符支持用户自定义。

• 命令自动补齐功能：vsql支持使用Tab键进行命令的自动补齐，当编译时指定了选项--with-readline，且客户端连接时指定-r参数，此功能被打开。

• 客户端操作历史记录：vsql支持客户端操作历史记录，当客户端连接时指定-r参数，此功能被打开。

设置变量

vsql支持使用元命令\set设置一个变量，格式如下：

\set varname value

删除变量使用如下语法：

\unset varname

例如：把变量foo的值设置为bar：\set foo bar，如果想要引用变量的值，在变量前面加冒号。例如查看变量的值：\echo :foo

上述变量的引用方法适用于正规的SQL语句和元命令，除此之外vsql还包含一些特殊变量，同时也规划了变量的取值。为了保证和后续版本最大限度地兼容，请避免以其他目的使用这些变量。所有特殊变量见表1。

表1 特殊变量设置

• 所有特殊变量都由大写字母、数字和下划线组成。
• 要查看特殊变量的默认值，请使用元命令\echo :varname（例如\echo :DBNAME）。

\set DBNAME dbname

\set ECHO all | queries

\set ECHO_HIDDEN  on | off | noexec

\set ENCODING encoding

\set FETCH_COUNT variable

\set HOST hostname

\set IGNOREEOF variable

\set LASTOID oid

\set  ON_ERROR_ROLLBACK  on | interactive | off

\set ON_ERROR_STOP on | off

\set PORT port

\set USER username

\set VERBOSITY terse | default | verbose

SQL代换

vsql变量可以把变量替换成正规的SQL语句，并且vsql还支持为变量更换新的别名或其他标识符等功能。使用SQL代换的方式替换一个变量的值可以在变量前面加上冒号，例如，执行如下命令即可查询系统表pg_proc：

\set foo 'pg_proc'
select * from :foo;

变量的值是逐字复制的，甚至可以包含不对称的引号或反斜杠命令。所以必须保证输入的内容有意义。

提示符

通过如下变量可以设置vsql的提示符，这些变量是由字符和特殊的转义字符所组成。

\set PROMPT2 TEST
select * from pg_proc TEST;

 \set PROMPT3 '>>>>'
copy pg_proc from STDIN;

提示符变量的值是按实际字符显示的，但是，当设置提示符的命令中出现%时，变量的值根据%后的字符，替换为已定义的内容，已定义的提示符请参见下表：

命令自动补齐

根据Vastbase语法规则，vsql支持使用Tab键进行命令的自动补齐，当编译时指定了选项--with-readline，且客户端连接时指定-r参数，此功能被打开。例如，crea后键入Tab，vsql会将其补齐为create。

• 支持数据库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 <name> owned by tableName.colName，owned by。
• 不支持自定义操作符自动补齐。使用复制粘贴这种方式输入命令，如果粘贴的命令里面有TAB键有可能会使输入命令的格式错乱，无法正常执行。
• \t\n@$><=;|&{()这些特殊字符在sql语句中具有固定含义。如果自定义表名中包含这些特殊字符，那么输入的sql语句从这些字符开始不支持自动补齐。

客户端操作历史记录

vsql支持客户端操作历史记录，当客户端连接时指定-r参数，此功能被打开。可以通过\set设置记录历史的条数，例如，\set HISTSIZE 50，将记录历史的条数设置为50，\set HISTSIZE 0，不记录历史。

• 客户端操作历史记录条数默认设置为32条，最多支持记录500条。当客户端交互式输入包含中文字符时，只支持UTF-8 的编码环境。
• 出于安全考虑，将包含PASSWORD、IDENTIFIED敏感词的记录识别为敏感信息，不会记录到历史信息中，即不能通过上下翻回显。

环境变量

与vsql相关的环境变量如下表所示：

PSQL_EDITOR_LINENUMBER_ARG = '+'
PSQL_EDITOR_LINENUMBER_ARG='--line '

获取帮助

• 连接数据库时可使用如下命令获取帮助信息。

  vsql --help
  

• 连接到数据库后，可以使用如下命令获取帮助信息。

  help
  

  显示如下帮助信息：

  You are using vsql, the command-line interface to vastbase.
  Type:  \copyright for distribution terms
      \h for help with SQL commands
      \? for help with vsql commands
      \g or terminate with semicolon to execute query
      \q to quit
  

• 查看Vastbase支持的SQL语句帮助

  • 查看Vastbase支持的所有SQL语句。

    \h
    

  • 查看某条语句的命令帮助，例如查看CREATE DATABASE命令的参数可使用下面的命令：

    \help CREATE DATABASE
    

语法格式

vsql [OPTION]... [DBNAME [USERNAME]]

DBNAME：声明要连接的数据库名称。

参数说明

通用参数

• -c, --command=COMMAND

  声明vsql要执行一条字符串命令然后退出。

• -d, --dbname=DBNAME

  指定想要连接的数据库名称。另外vsq允许使用直接在命令行上指定DBNAME。

  此外vsql允许使用扩展的DBNAME，即'postgres[ql]://[user[:password]@][netloc][:port][,...][/dbname][?param1=value1&...]'或'[key=value] [...]'形式的连接串作为DBNAME，vsql将从连接串中解析连接信息。

• -f, --file=FILENAME

  使用文件作为命令源而不是交互式输入。vsql将在处理完文件后结束。如果FILENAME是-（连字符），则从标准输入读取。

  取值范围：绝对路径或相对路径。

• -l, --list

  列出所有可用的数据库，然后退出。

• -v, --set=, --variable=NAME=VALUE

  使用vsql设置变量。类似于使用元命令\set进行变量设置。变量的示例和详细说明请参见变量。

• -V, --version

  打印vsql版本信息然后退出。

• -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。

• -u, --with-userpin=username:password

  执解密操作的用户名和密码。

  

  -D和-u参数只有硬件加密的时候才会用到。

• -k, --with-key=KEY

  使用vsql对导入的加密文件进行解密。

  

  • 对于本身就是shell命令中的关键字符如单引号（'）或双引号（”），Linux shell会检测输入的单引号（'）或双引号（”）是否匹配。如果不匹配，shell认为用户没有输入完毕，会一直等待用户输入，从而不会进入到vsql程序。

  • 不支持解密导入存储过程和函数。

• -L, --log-file=FILENAME

  除了正常的输出源之外，把所有查询输出记录到指定的FILENAME文件中。

  取值范围：绝对路径或相对路径。

  

  • 使用此参数可能会暴露部分SQL语句中的敏感信息，如创建用户语句中的password信息等，请谨慎使用。
  • 此参数只保留查询结果到相应文件中，主要目标是为了查询结果能够更好更准确地被其他调用者（例如自动化运维脚本）解析，而不是保留vsql运行过程中的相关日志信息。

• -m, --maintenance

  允许在两阶段事务恢复期间连接Vastbase。

  

  该选项是一个开发选项，禁止用户使用，只限专业技术人员使用。功能是：使用该选项时，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

  开启在客户端操作中可以进行编辑的模式。

• -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参数连接数据库时，可通过该选项指定密码。

  

  • 通过该参数指定用户连接数据库时，需要同时提供用户密码用以身份验证。您可以通过交换方式输入密码，或者通过-W参数指定密码。
  • 用户名中包含有字符$，需要在字符$前增加转义字符才可成功连接数据库。

元命令参考

该部分介绍使用Vastbase数据库命令行交互工具登录数据库后，vsql所提供的元命令。所谓元命令就是在vsql里输入的任何以不带引号的反斜杠开头的命令。

用户想要知道Vastbase支持的元命令有哪些，可以连接到数据库之后执行如下命令：

\?

一般元命令

• \copyright

  显示Vastbase的版权信息。

• \g [FILE] or ;

  把当前查询缓冲区的内容发送给服务器并且把查询的输出存到文件中，或者将输出重定向到到shell命令。

  单独一个\g实际上等效于一个分号。

• \h(\help) [NAME]

  给出指定SQL语句的语法帮助。

  如果没有给出NAME，vsql将列出可获得帮助的所有命令。如果NAME是一个星号（*），则显示所有SQL语句的语法帮助。

• \parallel [on [num]|off]

  控制并发执行开关。

  取值范围：on，off

  • on：打开控制并发执行开关，且最大并发数为num。
  • off：关闭控制并发执行开关。

  默认值：1024

  

  • 不支持事务中开启并发执行以及并发中开启事务。
  • 不支持\d这类元命令的并发。
  • 不推荐在并发中使用set语句，否则导致结果与预期不一致。
  • parallel内部不允许创建临时表。如需使用临时表，需要在开启parallel之前创建好，并在parallel内部使用。
  • \parallel中所有作业的持续时间不能超过session_timeout，否则可能会导致并发执行过程中断连。

  • 在\parallel on之后一条或多条命令，会等到\parallel off命令执行后才会执行，因而，每个\parallel on需对应一个\parallel off，否则会导致\parallel on之后的命令无法执行。

    

  • 服务器能接受的最大连接数受max_connections及当前已有连接数限制。

  • 设置num时请考虑服务器当前可接受的实际连接数合理指定。

• \q

  退出vsql程序。

查询缓存区元命令

• \e [FILE] [LINE]

  使用外部编辑器编辑查询缓冲区或者文件。

• \ef [FUNCNAME [LINE]]

  使用外部编辑器编辑函数定义。如果指定了LINE（即行号），则光标会指到函数体的指定行。

• \p

  打印当前查询缓冲区到标准输出。

• \r

  重置（或清空）查询缓冲区。

• \w FILE

  将当前查询缓冲区内容输出到指定文件。

输入/输出元命令

• \copy …

  在任何vsql客户端登录数据库成功后使用该命令可以执行导入导出数据。

  这是一个运行SQL语句COPY命令的操作，与COPY命令不同的是，COPY命令是服务去在读写指定文件，而vsql读写文件是作为本地的文件系统和服务器之间的跳板取出或写入数据。这意味着文件访问性和权限都是本地用户的，而不是服务器的，因此不需要SQL超级用户权限。

  

  • \COPY只适合小批量，格式良好的数据导入，不会对非法字符进行预处理，也无容错能力。导入数据应优先选择COPY。
  • \COPY支持分批导入：对导入数据的总行数进行分批，用户可以手动指定每批数据的行数（batch_size）。详情参考使用vsql元命令导入数据。
  • \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的内容。

• \d[S+]

  列出当前search_path中模式下所有的表、视图和序列。

• \d[S+] NAME

  列出指定表、视图和索引的结构。

  假设存在表a，列出指定表a的结构：

  \dtable+ a
  

• \d+ [PATTERN]

  列出所有表、视图和索引。

  例如，列出所有名称以f开头的表、视图和索引：

  \d+ f*
  

• \da[S] [PATTERN]

  列出所有可用的聚集函数以及它们操作的数据类型和返回值类型。

  例如，列出所有名称以f开头可用的聚集函数以及它们操作的数据类型和返回值类型：

  \da f*
  

• \db[+] [PATTERN]

  列出所有可用的表空间。

  例如，列出所有名称以p开头的可用表空间：

  \db p*
  

• \dc[S+] [PATTERN]

  列出所有字符集编码之间的转换

  例如，列出所有名称以c开头的类型转换：

  \dc *
  

• \dC[+] [PATTERN]

  列出所有类型转换。

  例如，列出所有名称以c开头的类型转换：

  \dC c*
  

• \dd[S] [PATTERN]

  显示所有匹配PATTERN的描述。如果没有给出参数，则显示所有可视对象。包括：聚集、函数、操作符、类型、关系（表、视图、索引、序列、大对象）、规则。

  例如，列出所有可视对象：

  \dd
  

• \ddp [PATTERN]

  显示所有默认的使用权限。

  例如，列出所有默认的使用权限：

  \ddp
  

• \dD[S+] [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]

  列出所有的文本搜索分析器。

• \dFd[+] [PATTERN]

  列出所有的文本搜索字典。

• \dFt[+] [PATTERN]

  列出所有的文本搜索模板。

• \dg[+] [PATTERN]

  列出所有数据库角色。

  

  因为用户和群组的概念被统一为角色，所以这个命令等价于\du。

• \dl

  \lo_list的别名，显示一个大对象的列表。

• \dL[S+] [PATTERN]

  列出可用的程序语言。

• \dm[S+] [PATTERN]

  列出物化视图。

• \dn[S+] [PATTERN]

  列出所有的模式（名称空间）。

• \do[S] [PATTERN]

  列出所有可用的操作符以及它们的操作数和返回的数据类型。

• \dO[S+] [PATTERN]

  列出排序规则。

• \dp [PATTERN]

  列出一列可用的表、视图以及相关的权限信息。

  \dp显示结果如下：

  • rolename=xxxx/yyyy：赋予一个角色的权限。
  • =xxxx/yyyy：赋予public的权限

  

  xxxx表示赋予的权限，yyyy表示授予这个权限的角色。权限的参数说明请参见表权限的参数说明。

  权限的参数说明

  参数	参数说明
  r	SELECT：允许对指定的表、视图读取数据。
  w	UPDATE：允许对指定表更新字段。
  a	INSERT：允许对指定表插入数据。
  d	DELETE：允许删除指定表中的数据。
  D	TRUNCATE：允许清理指定表中的数据。
  x	REFERENCES：允许创建外键约束。由于当前不支持外键，所以该参数暂不生效。
  t	TRIGGER：允许在指定表上创建触发器。
  X	EXECUTE：允许使用指定的函数以及利用这些函数实现的操作符。
  U	USAGE： 对于过程语言，允许用户在创建函数时，指定过程语言。 对于模式，允许访问包含在指定模式中的对象。 对于序列，允许使用nextval函数。
  C	CREATE： 对于数据库，允许在该数据库里创建新的模式。 对于模式，允许在该模式中创建新的对象。 对于序列，允许使用nextval函数。对于表空间，允许在其中创建表以及允许创建数据库和模式的时候把该表空间指定为其缺省表空间。
  c	CONNECT：允许用户连接到指定的数据库。
  T	TEMPORARY：允许创建临时表。
  A	ALTER：允许用户修改指定对象的属性。
  P	DROP：允许用户删除指定的对象。
  m	COMMENT：允许用户定义或修改指定对象的注释。
  i	INDEX：允许用户在指定表上创建索引。
  v	VACUUM：允许用户对指定的表执行ANALYZE和VACUUM操作。
  *	给前面权限的授权选项。

• \drds [PATTERN1 [PATTERN2]]

  列出所有修改过的配置参数。这些设置可以是针对角色的、针对数据库的或者同时针对两者的。

  

  • PATTERN1和PATTERN2表示要列出的角色PATTERN和数据库PATTERN。
  • 如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省或指定*时，则会列出所有设置。

  例如，列出postgres数据库所有修改过的配置参数。

  \drds * postgres
  

• \dT[S+] [PATTERN]

  列出所有的数据类型。

• \du[+] [PATTERN]

  列出所有数据库角色。

  

  因为用户和群组的概念被统一为角色，所以这个命令等价于\dg。

• \dE[S+] [PATTERN]，\di[S+] [PATTERN]，\ds[S+] [PATTERN]，\dt[S+] [PATTERN]，\dv[S+] [PATTERN]

  这一组命令，字母E、i、s、t和v分别代表着外部表、索引、序列、表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。

  例如：\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。

  默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。

• \dx[+] [PATTERN]

  列出安装数据库的扩展信息。

• \l[+]

  列出服务器上所有数据库的名称、所有者、字符集编码以及使用权限。

• \sf[+] FUNCNAME

  显示函数的定义。

  

  对于带圆括号的函数名，需要在函数名两端添加双引号，并且在双引号后面加上参数类型列表。参数类型列表两端添加圆括号。

  假设存在函数function_a和函数名带圆括号的函数func()name，列出函数的定义。

  \sf function_a
  \sf "func()name"(argtype1, argtype2)
  

• \z [PATTERN]

  列出数据库中所有表、视图和序列以及它们相关的访问特权。如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。

格式化元命令

• \a

  对齐模式和非对齐模式之间的切换。

• \C [STRING]

  把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。

• \f [STRING]

  对于不对齐的查询输出，显示或者设置域分隔符。

• \H

  • 若当前模式为文本格式，则切换为HTML输出格式。
  • 若当前模式为HTML格式，则切换回文本格式。

• \pset NAME [VALUE]

  设置影响查询结果表输出的选项。NAME的取值见下表可调节的打印选项。

  可调节的打印选项

  选项	选项说明	取值范围
  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	切换是否输出结果行数。	-

连接元命令

• \c[onnect] [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特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)，具体请参考下表：\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

显示一个目前存储在该数据库里的所有Vastbase大对象和提供给他们的注释。

示例

前提条件

vsql连接数据库时使用的用户需要具备访问数据库的权限。

操作步骤

1、使用vsql连接vastbase数据库。

vsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。

• 若未指定数据库名称，则使用初始化时默认生成的数据库名称。
• 若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名。
• 当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d）则该参数会被解释成数据库名。
• 如果已经指定数据库名（-d）而没有指定数据库用户名（-U）时，该参数则会被解释成数据库用户名。

示例1： 使用vastbase用户连接到本机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和vastbase不属于任何选项时，分别被解释成了数据库名和用户名。

vsql postgres vastbase -p 5432

等效于：

vsql -d posvtgres -U vastbase -p 5432

详细的vsql参数请参见参数说明。

2、执行SQL语句。

创建数据库human_staff为例。

CREATE DATABASE human_staff;

通常，输入的命令行在遇到分号的时候结束。如果输入的命令行没有错误，结果就会输出到屏幕上。

3、执行vsql元命令。

例如列出Vastbase中所有数据库和描述信息。

 \l

返回结果为：

                                 List of databases
   Name    |  Owner   | Encoding |  Collate   |   Ctype    |   Access privileges
-----------+----------+----------+------------+------------+-----------------------
 postgres  | vastbase | UTF8     | en_US.utf8 | en_US.utf8 |
 template0 | vastbase | UTF8     | en_US.utf8 | en_US.utf8 | =c/vastbase          +
           |          |          |            |            | vastbase=CTc/vastbase
 template1 | vastbase | UTF8     | en_US.utf8 | en_US.utf8 | =c/vastbase          +
           |          |          |            |            | vastbase=CTc/vastbase
 vastbase  | vastbase | UTF8     | en_US.utf8 | en_US.utf8 |
(4 rows)

更多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中Vastbase主机的相关设置，否则可能导致数据库功能故障。
  • 建议业务应用部署在Vastbase之外，而非Vastbase内部。

• 连接数据库，添加-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进行会话连接数管理，释放无用会话。

  关于查看用户会话连接数的方法如下表所示：

  描述	命令
  查看指定用户的会话连接数上限。	执行如下命令查看连接到指定用户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)

  会话状态可以在视图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中Vastbase主机的相关设置，否则可能导致数据库功能故障。
  • 建议业务应用部署在Vastbase之外，而非Vastbase内部。

其他故障

出现因“总线错误”（Bus error）导致的core dump或异常退出。

一般情况下出现此种问题，是进程运行过程中加载的共享动态库（在Linux为.so文件）出现变化，或者进程二进制文件本身出现变化，导致操作系统加载机器的执行码或者加载依赖库的入口发生变化，操作系统出于保护目的将进程杀死，产生core dump文件。

解决此问题，重试便可。同时请尽可能避免在升级等运维操作过程中，在Vastbase内部运行业务程序，避免升级时因替换文件产生此问题。

此故障的core dump文件的可能堆栈是dl_main及其子调用，它是操作系统用来初始化进程做共享动态库加载的。如果进程已经初始化，但是共享动态库还未加载完成，严格意义上来说，进程并未完全启动。