-\h(\help)
[NAME] 给出指定SQL语句的语法帮助。 如果没有给出NAME，
gsql将列出可获得帮助 的所有命令。如果 NAME是一个星号
（*），则显示所有 SQL语句的语法帮助。
参数 参数说明 取值范围
\parallel [on
[num]|off] 控制并发执行开关。
● on：打开控制并发执行开关，且最大并
● 并发select返回结果混乱问题，此为客户可 接受，core、进程停止响应不可接受。
● \parallel执行时最多会启动num个独立的 gsql进程连接服务器。
● \parallel中所有作业的持续时间不能超过 session_timeout，否则可能会导致并发执行 连接数受max_connection及 当前已有连接数限 制。
● 设置num时请考虑服 务器当前可接受的实 际连接数合理指定。
\q [value] 退出gsql程序。在一个脚本文件里，只在 脚本终止的时候执行。退出码可由value值
\ef [FUNCNAME [LINE]] 使用外部编辑器编辑函数定义。如果指定了LINE
（即行号），则光标会指到函数体的指定行。
\p 打印当前查询缓冲区到标准输出。
\r 重置（或清空）查询缓冲区。
\w FILE 将当前查询缓冲区输出到文件。
表3-13 输入/输出元命令
参数 参数说明
\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 ] ]
在任何psql客户端登录数据库成功后可以执行
\echo [STRING] 把字符串写到标准输出。
\i FILE 从文件FILE中读取内容，并将其当作输入，执 行查询。
\i+ FILE KEY 执行加密文件中的命令。
\ir FILE 和\i类似，只是相对于存放当前脚本的路径。
\ir+ FILE KEY 和\i+类似，只是相对于存放当前脚本的路径。
\o [FILE] 把所有的查询结果发送到文件里。
\qecho [STRING] 把字符串写到查询结果输出流里。
说明
表3-14中的选项S表示显示系统对象，+表示显示对象附加的描述信息。PATTERN用来指定要被 显示的对象名称。
表3-14 显示信息元命令
参数 参数说明 取值范围 示例
\d[S+] 列出当前search_path中模式 下所有的表、视图和序列。
参数 参数说明 取值范围 示例
\d+[PATTER N]
\ddp[PATTER N]
列出所有的Data Source对 象。
参数 参数说明 取值范围 示例
参数 参数说明 取值范围 示例
\dl \lo_list的别名，显示一个大
对象的列表。 - 列出所有的大对
\dp[PATTER N]
列出一列可用的表、视图以 及相关的权限信息。
\dp显示结果如下：
rolename=xxxx/yyyy --赋予一个角色 的权限=xxxx/yyyy --赋予public的权限 N1[PATTER N2]]
参数 参数说明 取值范围 示例
\sf function_a
\sf "func()name"(argtype1, argtype2)
\z[PATTER N]
列出数据库中所有表、视图 和序列，以及它们相关的访 问特权。
如果给出任何 pattern ，则被当 成一个正则表达
表3-15 权限的参数说明
参数 参数说明
r SELECT：允许对指定的表、视图读取数据。
w UPDATE：允许对指定表更新字段。
a INSERT：允许对指定表插入数据。
d DELETE：允许删除指定表中的数据。
D TRUNCATE：允许清理指定表中的数据。
x REFERENCES：允许创建外键约束。
t TRIGGER：允许在指定表上创建触发器。
X EXECUTE：允许使用指定的函数，以及利用这些函数实现的 操作符。
U USAGE：
● 对于过程语言，允许用户在创建函数时，指定过程语 言。
● 对于模式，允许访问包含在指定模式中的对象。
● 对于序列，允许使用nextval函数。
C CREATE：
● 对于数据库，允许在该数据库里创建新的模式。
● 对于模式，允许在该模式中创建新的对象。
● 对于表空间，允许在其中创建表，以及允许创建数据库 和模式的时候把该表空间指定为其缺省表空间。
c CONNECT：允许用户连接到指定的数据库。
T TEMPORARY：允许创建临时表。
A ANALYZE|ANALYSE：允许分析表。
arwdDxtA ALL PRIVILEGES：一次性给指定用户/角色赋予所有可赋予 的权限。
* 给前面权限的授权选项。
表3-16 格式化元命令
参数 参数说明
\a 对齐模式和非对齐模式之间的切换。
\C [STRING] 把正在打印的表的标题设置为一个查询的结果或者取 消这样的设置。
\f [STRING] 对于不对齐的查询输出，显示或者设置域分隔符。
参数 参数说明
\H ● 若当前模式为文本格式，则切换为HTML输出格
式。
● 若当前模式为HTML格式，则切换回文本格式。
\pset NAME [VALUE] 设置影响查询结果表输出的选项。NAME的取值见表
3-17。
\t [on|off] 切换输出的字段名的信息和行计数脚注。
\T [STRING] 指定在使用HTML输出格式时放在table标签里的属 性。如果参数为空，不设置。
\x [on|off|auto] 切换扩展行格式。
表3-17 可调节的打印选项
选项 选项说明 取值范围
border value必须是一个数字。通常这 个数字越大，表的边界就越宽 expanded (或
x) 在正常和扩展格式之间切换。 ● 当打开扩展格式时，查询结
fieldsep 声明域分隔符来实现非对齐输 出。这样就可以创建其他程序 希望的制表符或逗号分隔的输 出。要设置制表符域分隔符，
键入\pset fieldsep '\t'。缺省域 分隔符是 '|' (竖条符)。
-fieldsep_zero 声明域分隔符来实现非对齐输
出到零字节。
-footer 用来切换脚注。
-选项 选项说明 取值范围 format 设置输出格式。允许使用唯一
缩写（这意味着一个字母就够 了）。
取值范围：
● unaligned：写一行的所有列 在一条直线上中，当前活动 字段分隔符分隔。
● aligned：此格式是标准的，
可读性最好的文本输出。
● wrapped：类似aligned，但 是包装跨行的宽数据值，使
● troff-ms：把表输出为可用于 文档里的对应标记语言。输 出不是完整的文档。
null 打印一个字符串，用来代替一
个null值。 缺省是什么都不打印，这样很容
易和空字符串混淆。
numericlocale 切换分隔小数点左边的数值的
区域相关的分组符号。 ● on：显示指定的分隔符。
● off：不显示分隔符。
忽略此参数，显示默认的分隔 符。
pager 控制查询和gsql帮助输出的分 页器。如果设置了环境变量
● always：当输出到终端无论 是否符合屏幕显示时，都使 用分页器。
recordsep 声明在非对齐输出格式时的记
录分隔符。
-recordsep_zero 声明在非对齐输出到零字节时
的记录分隔符。
-tableattr（或
T） 声明放在html输出格式中 HTML table标签的属性（例 如：cellpadding或bgcolor）。
-选项 选项说明 取值范围 [DBNAME|-USER|- HOST|-PORT|-] GUC参数password max length的最大值。
\setenv NAME
[VALUE] 设置环境变量NAME为VALUE，如果 没有给出VALUE值，则不设置环境变 量。
-\timing [on|off] 以毫秒为单位显示每条SQL语句的执
行时间。 ● on表示打开显示。
● off表示关闭显示。
\! [COMMAND] 返回到一个单独的Unix shell或者执行 Unix命令COMMAND。
-表3-20 变量元命令
参数 参数说明
\prompt [TEXT] NAME 提示用户用文本格式来指定变量名字。
\set [NAME [VALUE]] 设置内部变量NAME为VALUE或者如果给出了多于一个 值，设置为所有这些值的连接结果。如果没有给出第二
\set-multi NAME [VALUE]
\end-multi
设置内部变量NAME为VALUE，VALUE可以由多行字符 串组成。\set-multi使用时，第二个参数必须给出。可 参考表下面的\set-multi元命令使用示例。
说明\set-multi 和\end-multi中出现的元命令会被忽略。
\unset NAME 不设置（或删除）gsql变量名。
\set-multi元命令使用示例 示例文件test.sql：
\set-multi multi_line_var select
id,name from student;
\end-multi
\echo multi_line_var is "${multi_line_var}"
\echo
---\echo result is
${multi_line_var}
gsql -d gaussdb -p 25308 --dynamic-param -f test.sql 执行结果：
multi_line_var is "select id,name
from student; "
---result is
id | name
通过\set-multi \end-multi设置变量multi_line_var为一个SQL语句，并在后面通过动 态变量解析获得这个变量。
示例文件test.sql：
\set-multi multi_line_var select 1 as id;
select 2 as id;
\end-multi
\echo multi_line_var is "${multi_line_var}"
\echo
---\echo result is
${multi_line_var}
gsql -d -p 25308 --dynamic-param -f test.sql 执行结果：
multi_line_var is "select 1 as id;
select 2 as id;"
---result is
id 1(1 row)
id 2(1 row)
通过\set-multi \end-multi设置变量multi_line_var为两个SQL语句，并在后面通过动 态变量解析获得这个变量。因为变量中的内容以“;”结尾，gsql发送SQL语句并获得 打印执行结果。
表3-21 \set 常用命令
名称 命令说明 取值范围
\set VERBOSITY
value 这个选项可以设置为值default， verbose，
terse之一以控制错误报告的冗余行。 value取值范 围：default，
verbose，
terse
\setON_ERROR_STO P value
如果设置了这个变量，脚本处理将马上停止。
如果该脚本是从另外一个脚本调用的，那个脚 本也会按同样的方式停止。如果最外层的脚本 不是从一次交互的gsql会话中调用的而是用-f 选项调用的，gsql将返回错误代码3，以示这个 情况与致命错误条件的区别(错误代码为1)。
value取值范围 为：on/off，
true/false，
yes/no，1/0
名称 命令说明 取值范围
\set RETRY
[retry_times] 用于控制是否开启语句出错场景下的重试功 能，参数retry_times用来指定最大重试次数，
缺省值为5，取值范围为5-10。当重试功能已 经开启时，再次执行\set RETRY可以关闭该功 能。
● YY001：TCP通信错误，Connection reset by peer（CN和DN间通信）
● 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会查询所有CN/DN的连接状 态，当状态异常时会sleep 1分钟再进行重试，
能够覆盖大部分主备切换场景下的出错重试。
retry_times取 值范围为：
5-10
名称 命令说明 取值范围 说明
1. 不支持事务块中的语句错误重试；
2. 不支持通过ODBC、JDBC接口查询的出错重试；
3. 含有unlogged表的sql语句，不支持节点故障后 的出错重试；
4. 当前不支持CN和GTM节点故障时，gsql客户端 的出错重试；
5. gsql客户端本身出现的错误，不在重跑考虑范围 之内；
表3-22 大对象元命令
参数 参数说明
\lo_list 显示一个目前存储在该数据库里的所有GaussDB(DWS)大对 象和提供给他们的注释。
表3-23 流程控制元命令
参数 参数说明 取值范围
\if EXPR
\elif EXPR
\else
\endif
这组元命令可实现可嵌套的条件块：
● 条件块以\if开始，\endif结束。
● \if和\endif两者之间可以出现任意 数量的\elif子句，或单一的\else子 句。
● \if和\elif命令支持布尔表达式计算 和字符串等值判断。
● \elif不能出现在\else和\endif之 间。 变量COMPARE_STRATEGY 控制（详见表3-2）。默
参数 参数说明 取值范围
\goto LABEL
\label LABEL
这组元命令可实现无条件跳转：
● \label元命令不支持在\if语句块中使 用。
● \goto \label不建议在事务、PL/SQL等 语句块中使用，避免出现不可预期结
● \goto \label不建议在事务、PL/SQL等 语句块中使用，避免出现不可预期结