\copyright

显示 GaussDB 的版本和版权信息。

-

\g [FILE] or ;

执行查询（并将结果发送到文件或管道）。

-

\h(\help) [NAME]

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

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

\parallel [on [num]|off]

控制并发执行开关。

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

num的默认值：1024。

\q

退出gsql程序。在一个脚本文件里，只在脚本终止的时候执行。

-

\e [FILE] [LINE]

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

\ef [FUNCNAME [LINE]]

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

\p

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

\r

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

\w FILE

将当前查询缓冲区输出到文件。

\copy { table [ ( column_list ) ] | ( query ) } { from | to } { filename | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] 'character' ] [ null [ as ] 'string' ] [ csv [ header ] [ quote [ as ] 'character' ] [ escape [ as ] 'character' ] [ force quote column_list | * ] [ force not null column_list ] ] [parallel integer]

在任何gsql客户端登录数据库成功后可以执行导入导出数据，这是一个运行SQL COPY命令的操作，但不是读取或写入指定文件的服务器，而是读取或写入文件，并在服务器和本地文件系统之间路由数据。这意味着文件的可访问性和权限是本地用户的权限，而不是服务器的权限，并且不需要数据库初始化用户权限。

\echo [STRING]

把字符串写到标准输出。

\i FILE

从文件FILE中读取内容，并将其当作输入，执行查询。

\i+ FILE KEY

执行加密文件中的命令。

\ir FILE

和\i类似，只是相对于存放当前脚本的路径。

\ir+ FILE KEY

和\i+类似，只是相对于存放当前脚本的路径。

\o [FILE]

把所有的查询结果发送到文件里。

\qecho [STRING]

把字符串写到查询结果输出流里。

\d[S+]

列出当前search_path中模式下所有的表、视图和序列。当search_path中不同模式存在同名对象时，只显示search_path中位置靠前模式下的同名对象。

-

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

1

openGauss=# \d

\d[S+] NAME

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

-

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

1

openGauss=# \dtable+ a

\d+ [PATTERN]

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

如果声明了PATTERN，只显示名称匹配PATTERN的表、视图和索引。

列出所有名称以f开头的表、视图和索引。

1

openGauss=# \d+ f*

\da[S] [PATTERN]

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

如果声明了PATTERN，只显示名称匹配PATTERN的聚集函数。

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

1

openGauss=# \da f*

\db[+] [PATTERN]

列出所有可用的表空间。

如果声明了PATTERN，只显示名称匹配PATTERN的表空间。

列出所有名称以p开头的可用表空间。

1

openGauss=# \db p*

\dc[S+] [PATTERN]

列出所有字符集之间的可用转换。

如果声明了PATTERN，只显示名称匹配PATTERN的转换。

列出所有字符集之间的可用转换。

1

openGauss=# \dc *

\dC[+] [PATTERN]

列出所有类型转换。

PATTERN需要使用实际类型名，不能使用别名。

如果声明了PATTERN，只显示名称匹配PATTERN的转换。

列出所有名称以c开头的类型转换。

1

openGauss=# \dC c*

\dd[S] [PATTERN]

显示所有匹配PATTERN的描述。

如果没有给出参数，则显示所有可视对象。“对象”包括：聚集、函数、操作符、类型、关系(表、视图、索引、序列、大对象)、规则。

列出所有可视对象。

1

openGauss=# \dd

\ddp [PATTERN]

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

如果指定了PATTERN，只显示名称匹配PATTERN的使用权限。

列出所有默认的使用权限。

1

openGauss=# \ddp

\dD[S+] [PATTERN]

列出所有可用域。

如果声明了PATTERN，只显示名称匹配PATTERN的域。

列出所有可用域。

1

openGauss=# \dD

\ded[+] [PATTERN]

列出所有的Data Source对象。

如果声明了PATTERN，只显示名称匹配PATTERN的对象。

列出所有的Data Source对象。

1

openGauss=# \ded

\det[+] [PATTERN]

列出所有的外部表。

如果声明了PATTERN，只显示名称匹配PATTERN的表。

列出所有的外部表。

1

openGauss=# \det

\des[+] [PATTERN]

列出所有的外部服务器。

如果声明了PATTERN，只显示名称匹配PATTERN的服务器。

列出所有的外部服务器。

1

openGauss=# \des

\deu[+] [PATTERN]

列出用户映射信息。

如果声明了PATTERN，只显示名称匹配PATTERN的信息。

列出用户映射信息。

1

openGauss=#\deu

\dew[+] [PATTERN]

列出封装的外部数据。

如果声明了PATTERN，只显示名称匹配PATTERN的数据。

列出封装的外部数据。

1

openGauss=# \dew

\df[antw][S+] [PATTERN]

列出所有可用函数，以及它们的参数和返回的数据类型。a代表聚集函数，n代表普通函数，t代表触发器，w代表窗口函数。

如果声明了PATTERN，只显示名称匹配PATTERN的函数。

列出所有可用函数，以及它们的参数和返回的数据类型。

1

openGauss=# \df

\dF[+] [PATTERN]

列出所有的文本搜索配置信息。

如果声明了PATTERN，只显示名称匹配PATTERN的配置信息。

列出所有的文本搜索配置信息。

1

openGauss=# \dF+

\dFd[+] [PATTERN]

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

如果声明了PATTERN，只显示名称匹配PATTERN的字典。

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

1

openGauss=# \dFd

\dFp[+] [PATTERN]

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

如果声明了PATTERN，只显示名称匹配PATTERN的分析器。

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

1

openGauss=# \dFp

\dFt[+] [PATTERN]

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

如果声明了PATTERN，只显示名称匹配PATTERN的模板。

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

1

openGauss=# \dFt

\dg[+] [PATTERN]

列出所有数据库角色。

如果指定了PATTERN，只显示名称匹配PATTERN的角色。

列出名称为‘j_e’所有数据库角色。

1

openGauss=# \dg j?e

\dl

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

-

列出所有的大对象。

1

openGauss=# \dl

\dL[S+] [PATTERN]

列出可用的程序语言。

如果指定了PATTERN，只列出名称匹配PATTERN的语言。

列出可用的程序语言。

1

openGauss=# \dL

\dm[S+] [PATTERN]

列出物化视图。

如果指定了PATTERN，只列出名称匹配PATTERN的物化视图。

列出物化视图。

1

openGauss=# \dm

\dn[S+] [PATTERN]

列出所有模式（名称空间）。如果向命令追加+，会列出每个模式相关的权限及描述。

如果声明了PATTERN，只列出名称匹配PATTERN的模式名。缺省时，只列出用户创建的模式。

列出所有名称以d开头的模式以及相关信息。

1

openGauss=# \dn+ d*

\do[S] [PATTERN]

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

如果声明了PATTERN，只列出名称匹配PATTERN的操作符。缺省时，只列出用户创建的操作符。

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

1

openGauss=# \do

\dO[S+] [PATTERN]

列出排序规则。

如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省时，只列出用户创建的规则。

列出排序规则。

1

openGauss=# \dO

\dp [PATTERN]

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

\dp显示结果如下：

rolename=xxxx/yyyy  --赋予一个角色的权限

=xxxx/yyyy  --赋予public的权限 

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

如果指定了PATTERN，只列出名称匹配PATTERN的表、视图。

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

1

openGauss=# \dp

\drds [PATTERN1 [PATTERN2]]

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

如果声明了PATTERN，只列出名称匹配PATTERN的规则。缺省或指定*时，则会列出所有设置。

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

1

openGauss=# \drds *openGausss

\dT[S+] [PATTERN]

列出所有的数据类型。

如果指定了PATTERN，只列出名称匹配PATTERN的类型。

列出所有的数据类型。

1

openGauss=# \dT

\du[+] [PATTERN]

列出所有数据库角色。

如果指定了PATTERN，则只列出名称匹配PATTERN的角色。

列出所有数据库角色。

1

openGauss=# \du

\dE[S+] [PATTERN]

\di[S+] [PATTERN]

\ds[S+] [PATTERN]

\dt[S+] [PATTERN]

\dv[S+] [PATTERN]

这一组命令，字母E，i，s，t和v分别代表着外部表，索引，序列，表和视图。可以以任意顺序指定其中一个或者它们的组合来列出这些对象。例如：\dit列出所有的索引和表。在命令名称后面追加+，则每一个对象的物理尺寸以及相关的描述也会被列出。

如果指定了PATTERN，只列出名称匹配该PATTERN的对象。默认情况下只会显示用户创建的对象。通过PATTERN或者S修饰符可以把系统对象包括在内。

列出所有的索引和视图。

1

openGauss=# \div

\dx[+] [PATTERN]

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

如果指定了PATTERN，则只列出名称匹配PATTERN的扩展信息。

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

1

openGauss=# \dx

\l[+]

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

-

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

1

openGauss=# \l

\sf[+] FUNCNAME

显示函数的定义。

-

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

123

openGauss=# \sf function_aopenGauss=# \sf "func()name"(argtype1, argtype2)

\z [PATTERN]

列出数据库中所有表、视图和序列，以及它们相关的访问特权。

如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。

列出数据库中所有表、视图和序列，以及它们相关的访问特权。

1

openGauss=# \z

r

SELECT：允许对指定的表、视图读取数据。

w

UPDATE：允许对指定表更新字段。

a

INSERT：允许对指定表插入数据。

d

DELETE：允许删除指定表中的数据。

D

TRUNCATE：允许清理指定表中的数据。

x

REFEREN CES ：允许创建外键约束。

t

TRIGGER：允许在指定表上创建触发器。

X

EXECUTE：允许使用指定的函数，以及利用这些函数实现的操作符。

U

USAGE：

• 对于过程语言，允许用户在创建函数时，指定过程语言。
• 对于模式，允许访问包含在指定模式中的对象。
• 对于序列，允许使用nextval函数。

C

CREATE：

• 对于数据库，允许在该数据库里创建新的模式。
• 对于模式，允许在该模式中创建新的对象。
• 对于表空间，允许在其中创建表，以及允许创建数据库和模式的时候把该表空间指定为其缺省表空间。

c

CONNECT：允许用户连接到指定的数据库。

T

TEMPORARY：允许创建临时表。

A

ALTER：允许用户修改指定对象的属性。

P

DROP：允许用户删除指定的对象。

m

COMMENT：允许用户定义或修改指定对象的注释。

i

INDEX：允许用户在指定表上创建索引。

v

VACUUM：允许用户对指定的表执行ANALYZE和VACUUM操作。

*

给前面权限的授权选项。

\a

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

\C [STRING]

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

\f [STRING]

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

\H

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

\pset NAME [VALUE]

设置影响查询结果表输出的选项。NAME的取值见表7。

\t [on|off]

切换输出的字段名的信息和行计数脚注。

\T [STRING]

指定在使用HTML输出格式时放在table标签里的属性。如果参数为空，不设置。

\x [on|off|auto]

切换扩展行格式。

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

控制查询和gsql帮助输出的分页器。如果设置了环境变量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|-]

连接到一个新的数据库（当前数据库为postgres）。当数据库名称长度超过63个字节时，默认前63个字节有效，连接到前63个字节对应的数据库，但是gsql的命令提示符中显示的数据库对象名仍为截断前的名称。

-

\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或者如果给出了多于一个值，设置为所有这些值的连接结果。如果没有给出第二个参数，只设变量不设值。

有一些常用变量被gsql特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)。 表11是一个所有特殊对待的变量列表。

\unset NAME

不设置（或删除）gsql变量名。

\set VERBOSITY value

这个选项可以设置为值default，verbose，terse之一以控制错误报告的冗余行。

value取值范围：default， verbose，terse

\set ON_ERROR_STOP value

如果设置了这个变量，脚本处理将马上停止。如果该脚本是从另外一个脚本调用的，那个脚本也会按同样的方式停止。如果最外层的脚本不是从一次交互的gsql会话中调用的而是用-f选项调用的，gsql将返回错误代码3，以示这个情况与致命错误条件的区别(错误代码为1)。

value取值范围为：on/off，true/false，yes/no，1/0

\set AUTOCOMMIT [on|off]

设置当前gsql连接的自动提交行为，on为打开自动提交，off为关闭自动提交。默认情况下，gsql连接处于自动提交模式，每个单独的语句都被隐式提交。如果基于性能或者其它方面考虑，需要关闭自动提交时，需要用户自己显示的发出COMMIT命令来保证事务的提交。例如，在指定的业务SQL执行完之后发送COMMIT语句显式提交，特别是gsql客户端退出之前务必保证所有的事务已经提交。

• on表示打开自动提交。
• off表示关闭自动提交。

\set RETRY [retry_times]

用于控制是否开启语句出错场景下的重试功能，参数retry_times用来指定最大重试次数，缺省值为5，取值范围为5-10。当重试功能已经开启时，再次执行\set RETRY可以关闭该功能。

使用配置文件retry_errcodes.conf列举需要重试的错误码列表，该文件和gsql可执行程序位于同一级目录下。该配置文件为系统配置，非用户定义，不允许用户直接修改。

当前支持以下出错场景的重试：

• YY002：TCP通信错误，Connection reset by peer（DN和DN间通信）
• YY003：锁超时，Lock wait timeout.../wait transaction xxx sync time exceed xxx
• YY004：TCP通信错误，Connection timed out
• YY005：SET命令发送失败，ERROR SET query
• YY006：内存申请失败，memory is temporarily unavailable
• YY007：通信库错误，Memory allocate error
• YY008：通信库错误，No data in buffer
• YY009：通信库错误，Close because release memory
• YY010：通信库错误，TCP disconnect
• YY011：通信库错误，SCTP disconnect（由于规格变更，当前版本已经不再支持本特性，请不要使用）
• YY012：通信库错误，Stream closed by remote
• YY013：通信库错误，Wait poll unknown error

同时，出错时gsql会查询所有DN的连接状态，当状态异常时会sleep1分钟再进行重试，能够覆盖大部分主备切换场景下的出错重试。

retry_times取值范围为：5-10

\lo_list

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