华为云用户手册

Hint使用准备 为了方便了解hint的使用场景，手册提供了所有查询改写hint的应用示例，请参见Hint使用说明，相关建表语句和环境准备如下： 会话设置： SET client_encoding = 'UTF8'; CREATE SCHEMA rewrite_rule_test; SET current_schema = rewrite_rule_test; SET enable_codegen= off;

功能描述 优化器支持一系列查询改写规则，可以对SQL语句进行等价的逻辑改写，从而生成更好的执行计划。但在一些场景下，用户并不希望改写SQL语句、或者优化器的改写会导致计划跳变，对于这些特定的场景，需要能够使用hint对改写规则进行控制，让优化器按照特定的方式进行改写。目前数据库支持对ANY/EXISTS的子链接、简单子查询、消减ORDER BY、HAVING子句下推、延迟聚合等多种场景的SQL进行hint控制，具体请参见：Hint使用说明。 部分查询改写规则同时受查询改写的hint和GUC参数控制，通常查询改写的hint优先级高于GUC参数控制，涉及到受GUC参数控制的改写规则会在Hint使用说明相关章节进行描述。 每条查询改写规则受一对互斥的hint控制，如：子查询展开的规则同时受EXPAND_SUBQUERY和NO_EXPAND_SUBQUERY控制，其中，EXPAND_SUBQUERY Hint表示允许应用该规则对SQL进行改写，NO_EXPAND_SUBQUERY表示禁止使用该规则对SQL进行改写。且当同一个查询块（queryblock）中同时存在两个互斥的hint时，以获取的首个hint为准，例如：/*+ EXPAND_SUBQUERY NO_EXPAND_SUBQUERY */，则EXPAND_SUBQUERY Hint生效。 查询改写的hint允许重复，但对于重复的hint数据库只会使用第一个，对于其他未使用的hint则会报"unused hint" Warning提示。例如：/*+ EXPAND_SUBLINK EXPAND_SUBLINK */，由于数据库只使用第一个EXPAND_SUBLINK hint，所以仍然会报"unused hint" Warning提示。

示例 -- 创建adt1策略。 gaussdb=# CREATE AUDIT POLICY adt1 PRIVILEGES CREATE; CREATE AUDIT POLICY --删除审计策略adt1。 gaussdb=# DROP AUDIT POLICY adt1; DROP AUDIT POLICY --删除一个不存在的审计策略adt0,提示删除失败，该审计策略不存在。 gaussdb=# DROP AUDIT POLICY adt0; ERROR: adt0 policy does not exist, drop failed

示例 --创建源表及触发表。 gaussdb=# CREATE TABLE test_trigger_src_tbl(id1 INT, id2 INT, id3 INT); gaussdb=# CREATE TABLE test_trigger_des_tbl(id1 INT, id2 INT, id3 INT); INSERT触发器的使用。 --创建insert触发器函数。 gaussdb=# CREATE OR REPLACE FUNCTION tri_insert_func() RETURNS TRIGGER AS $$ DECLARE BEGIN INSERT INTO test_trigger_des_tbl VALUES(NEW.id1, NEW.id2, NEW.id3); RETURN NEW; END $$ LANGUAGE plpgsql; --创建INSERT触发器。 gaussdb=# CREATE TRIGGER insert_trigger BEFORE INSERT ON test_trigger_src_tbl FOR EACH ROW EXECUTE PROCEDURE tri_insert_func(); --执行INSERT触发事件并检查触发结果。 gaussdb=# INSERT INTO test_trigger_src_tbl VALUES(100,200,300); gaussdb=# SELECT * FROM test_trigger_src_tbl; id1 | id2 | id3 -----+-----+----- 100 | 200 | 300 (1 row) gaussdb=# SELECT * FROM test_trigger_des_tbl; //查看触发操作是否生效。 id1 | id2 | id3 -----+-----+----- 100 | 200 | 300 (1 row) UPDATE触发器的使用。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 --创建UPDATE触发器函数。 gaussdb=# CREATE OR REPLACE FUNCTION tri_update_func() RETURNS TRIGGER AS $$ DECLARE BEGIN UPDATE test_trigger_des_tbl SET id3 = NEW.id3 WHERE id1=OLD.id1; RETURN OLD; END $$ LANGUAGE plpgsql; --创建UPDATE触发器。 gaussdb=# CREATE TRIGGER update_trigger AFTER UPDATE ON test_trigger_src_tbl FOR EACH ROW EXECUTE PROCEDURE tri_update_func(); --执行UPDATE触发事件并检查触发结果。 gaussdb=# UPDATE test_trigger_src_tbl SET id3=400 WHERE id1=100; gaussdb=# SELECT * FROM test_trigger_src_tbl; id1 | id2 | id3 -----+-----+----- 100 | 200 | 400 (1 row) gaussdb=# SELECT * FROM test_trigger_des_tbl; //查看触发操作是否生效。 id1 | id2 | id3 -----+-----+----- 100 | 200 | 400 (1 row) DELETE触发器的使用。 --创建DELETE触发器函数。 gaussdb=# CREATE OR REPLACE FUNCTION TRI_DELETE_FUNC() RETURNS TRIGGER AS $$ DECLARE BEGIN DELETE FROM test_trigger_des_tbl WHERE id1=OLD.id1; RETURN OLD; END $$ LANGUAGE plpgsql; --创建DELETE触发器。 gaussdb=# CREATE TRIGGER delete_trigger BEFORE DELETE ON test_trigger_src_tbl FOR EACH ROW EXECUTE PROCEDURE tri_delete_func(); --执行DELETE触发事件并检查触发结果。 gaussdb=# DELETE FROM test_trigger_src_tbl WHERE id1=100; gaussdb=# SELECT * FROM test_trigger_src_tbl; id1 | id2 | id3 -----+-----+----- (0 rows) gaussdb=# SELECT * FROM test_trigger_des_tbl; //查看触发操作是否生效。 id1 | id2 | id3 -----+-----+----- (0 rows) 修改触发器名称。 1 2 --修改触发器的名称。 gaussdb=# ALTER TRIGGER delete_trigger ON test_trigger_src_tbl RENAME TO delete_trigger_renamed; 禁用触发器。 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 --禁用insert_trigger触发器。 gaussdb=# ALTER TABLE test_trigger_src_tbl DISABLE TRIGGER insert_trigger; gaussdb=# INSERT INTO test_trigger_src_tbl VALUES(100,200,300); gaussdb=# SELECT * FROM test_trigger_src_tbl; id1 | id2 | id3 -----+-----+----- 100 | 200 | 300 (1 row) gaussdb=# SELECT * FROM test_trigger_des_tbl; //可以看到触发器没有生效。 id1 | id2 | id3 -----+-----+----- (0 rows) --禁用当前表上所有触发器。 gaussdb=# ALTER TABLE test_trigger_src_tbl DISABLE TRIGGER ALL; 删除触发器。 1 2 3 4 5 gaussdb=# DROP TRIGGER insert_trigger ON test_trigger_src_tbl; gaussdb=# DROP TRIGGER update_trigger ON test_trigger_src_tbl; gaussdb=# DROP TRIGGER delete_trigger_renamed ON test_trigger_src_tbl; 删除函数。 1 2 3 4 5 gaussdb=# DROP FUNCTION tri_insert_func; gaussdb=# DROP FUNCTION tri_update_func; gaussdb=# DROP FUNCTION tri_delete_func; 1 2 3 --删除源表及触发表。 gaussdb=# DROP TABLE test_trigger_src_tbl; gaussdb=# DROP TABLE test_trigger_des_tbl;

参数说明 OR REPLACE 可选项，指定此参数将在TRIGGER已存在的前提下修改已有的TRIGGER。 无法通过OR REPLACE语法创建或修改CONSTRAINT TRIGGER和INTERNAL TRIGGER。CONSTRAINT TRIGGER是指通过CREATE CONSTRAINT TRIGGER创建的TRIGGER，INTERNAL TRIGGER是指某些SQL语句隐式创建的TRIGGER（如给表加上外键约束会隐式创建4个trigger，这4个TRIGGER即为INTERNAL TRIGGER）。 CONSTRAINT 可选项，指定此参数将创建约束触发器，即触发器作为约束来使用。除了可以使用SET CONSTRAINTS调整触发器触发的时间之外，这与常规触发器相同。 约束触发器必须是AFTER ROW触发器。 name 触发器名称，该名称不能限定模式，因为触发器自动继承其所在表的模式，且同一个表的触发器不能重名。 对于约束触发器，使用SET CONSTRAINTS修改触发器行为时也使用此名称。 取值范围：符合标识符命名规范的字符串，且最大长度不超过63个字符。 BEFORE 触发器函数是在触发事件发生前执行。 AFTER 触发器函数是在触发事件发生后执行，约束触发器只能指定为AFTER。 INSTEAD OF 触发器函数直接替代触发事件。 event 启动触发器的事件，取值范围包括：INSERT、UPDATE、DELETE或TRUNCATE，也可以通过OR同时指定多个触发事件。 对于UPDATE事件类型，可以使用下面语法指定列： UPDATE OF column_name1 [, column_name2 ... ] 表示只有这些列作为UPDATE语句的目标列时，才会启动触发器，但是INSTEAD OF UPDATE类型不支持指定列信息。如果UPDATE OF指定的列包含生成列，当生成列依赖的列是UPDATE语句的目标列时，也会启动触发器。 table_name 需要创建触发器的表名称。 取值范围：数据库中已经存在的表名称。 referenced_table_name 约束引用的另一个表的名称。 只能为约束触发器指定，常见于外键约束。由于当前不支持外键，因此不建议使用。 取值范围：数据库中已经存在的表名称。 DEFERRABLE | NOT DEFERRABLE 约束触发器的启动时机，仅作用于约束触发器。这两个关键字设置该约束是否可推迟。 详细介绍请参见CREATE TABLE。 INITIALLY IMMEDIATE | INITIALLY DEFERRED 如果约束是可推迟的，则这个子句声明检查约束的缺省时间，仅作用于约束触发器。 详细介绍请参见CREATE TABLE。 FOR EACH ROW | FOR EACH STATEMENT 触发器的触发频率。 FOR EACH ROW是指该触发器是受触发事件影响的每一行触发一次。 FOR EACH STATEMENT是指该触发器是每个SQL语句只触发一次。 未指定时默认值为FOR EACH STATEMENT。约束触发器只能指定为FOR EACH ROW。 condition 决定是否实际执行触发器函数的条件表达式。当指定WHEN时，只有在条件返回true时才会调用该函数。 在FOR EACH ROW触发器中，WHEN条件可以通过分别写入OLD.column_name或NEW.column_name来引用旧行或新行值的列。INSERT触发器不能引用OLD，DELETE触发器不能引用NEW。 INSTEAD OF触发器不支持WHEN条件。 WHEN表达式不能包含子查询。 对于约束触发器，WHEN条件的评估不会延迟，而是在执行更新操作后立即发生。 如果条件返回值不为true，则触发器不会排队等待延迟执行。 function_name 用户定义的函数，必须声明为不带参数并返回类型为触发器，在触发器触发时执行。 arguments 执行触发器时要提供给函数的可选的以逗号分隔的参数列表。参数是文字字符串常量，简单的名称和数字常量也可以写在这里，但它们都将被转换为字符串。 请检查触发器函数的实现语言的描述，以了解如何在函数内访问这些参数。 关于触发器种类： INSTEAD OF的触发器必须标记为FOR EACH ROW，并且只能在视图上定义。 BEFORE和AFTER触发器作用在视图上时，只能标记为FOR EACH STATEMENT。 TRUNCATE类型触发器仅限FOR EACH STATEMENT。 表1 表和视图上支持的触发器种类： 触发时机 触发事件 行级 语句级 BEFORE INSERT/UPDATE/DELETE 表 表和视图 TRUNCATE 不支持 表 AFTER INSERT/UPDATE/DELETE 表 表和视图 TRUNCATE 不支持 表 INSTEAD OF INSERT/UPDATE/DELETE 视图 不支持 TRUNCATE 不支持 不支持 表2 plpgsql类型触发器函数特殊变量： 变量名 变量含义 NEW INSERT及UPDATE操作涉及tuple信息中的新值，对DELETE为空，并且对于statement级别的触发器此变量也为空。 OLD UPDATE及DELETE操作涉及tuple信息中的旧值，对INSERT为空，并且对于statement级别的触发器此变量也为空。 TG_NAME 触发器名称。 TG_WHEN 触发器触发时机（BEFORE/AFTER/INSTEAD OF）。 TG_LEVEL 触发频率（ROW/STATEMENT）。 TG_OP 触发操作（INSERT/UPDATE/DELETE/TRUNCATE）。 TG_RELID 触发器所在表OID。 TG_RELNAME 触发器所在表名（已废弃，现用TG_TABLE_NAME替代）。 TG_TABLE_NAME 触发器所在表名。 TG_TABLE_SCHEMA 触发器所在表的SCHEMA信息。 TG_NARGS 触发器函数参数个数。 TG_ARGV[] 触发器函数参数列表。

FORALL批量查询语句 语法图 forall::=语句图图9所示。 图9 forall::= label declaration ::语句如图10所示。 图10 label declaration ::= 变量index会自动定义为integer类型并且只在此循环里存在。index的取值介于low_bound和upper_bound之间。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 gaussdb=# CREATE TABLE TEST_t1 ( title NUMBER(6), did VARCHAR2(20), data_period VARCHAR2(25), kind VARCHAR2(25), interval VARCHAR2(20), time DATE, isModified VARCHAR2(10) ) DISTRIBUTE BY hash(did); CREATE TABLE gaussdb=# INSERT INTO TEST_t1 VALUES( 8, 'Donald', 'OConnell', 'DOCONNEL', '650.507.9833', to_date('21-06-1999', 'dd-mm-yyyy'), 'SH_CLERK' ); INSERT 0 1 gaussdb=# CREATE OR REPLACE PROCEDURE proc_forall() AS BEGIN FORALL i IN 100..120 update TEST_t1 set title = title + 100*i; END; / CREATE PROCEDURE --调用存储过程 gaussdb=# CALL proc_forall(); proc_forall ------------- (1 row) --查询存储过程调用结果 gaussdb=# SELECT * FROM TEST_t1; title | did | data_period | kind | interval | time | ismodified --------+--------+-------------+----------+--------------+---------------------+------------ 231008 | Donald | OConnell | DOCONNEL | 650.507.9833 | 1999-06-21 00:00:00 | SH_CLERK (1 row) --删除存储过程和表 gaussdb=# DROP PROCEDURE proc_forall; DROP PROCEDURE gaussdb=# DROP TABLE TEST_t1; DROP TABLE

FOR_LOOP查询语句 语法图 for_loop_query::=语句如图7所示。 图7 for_loop_query::= label declaration ::=语句如如图8所示。 图8 label declaration ::= 变量target会自动定义，类型和query的查询结果的类型一致，并且只在此循环中有效。target的取值就是query的查询结果。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 --循环输出查询结果。 gaussdb=# CREATE OR REPLACE PROCEDURE proc_for_loop_query() AS record VARCHAR2(50); BEGIN FOR record IN SELECT spcname FROM pg_tablespace LOOP dbe_output.print_line(record); END LOOP; END; / CREATE PROCEDURE --调用存储过程 gaussdb=# CALL proc_for_loop_query(); pg_default pg_global proc_for_loop_query --------------------- (1 row) --删除存储过程 gaussdb=# DROP PROCEDURE proc_for_loop_query; DROP PROCEDURE

GUC参数设置 GaussDB 提供了六类GUC参数，具体分类和设置方式请参考表1。 表1 GUC参数分类 参数类型 说明 设置方式 INTERNAL 固定参数，在创建数据库的时候确定，用户无法修改，只能通过show语法或者pg_settings视图进行查看。 无 POSTMASTER 数据库服务端参数，在数据库启动时确定，可以通过配置文件指定。 支持表2中的方式一。 SIGHUP 数据库全局参数，可在数据库启动时设置或者在数据库启动后，发送指令重新加载。 支持表2中的方式一、方式二。 BACKEND 会话连接参数。在创建会话连接时指定，连接建立后无法修改。连接断掉后参数失效。内部使用参数，不推荐用户设置。 支持表2中的方式一、方式二。 说明： 设置该参数后，下一次建立会话连接时生效。 SUSET 数据库管理员参数。可在数据库启动时、数据库启动后或者数据库管理员通过SQL进行设置。 支持表2中的方式一、方式二或由数据库管理员通过方式三设置。 USERSET 普通用户参数。可被任何用户在任何时刻设置。 支持表2中的方式一、方式二或方式三设置。 说明： 设置USERSET类型的参数时，ALTER DATABASE设置的参数值优先级高于gs_guc设置。如果想要gs_guc设置的参数值生效，则需要执行“alter database xxx reset xxx”进行重置。 GaussDB提供了三种方式来修改GUC参数，具体操作请参考表2： 表2 GUC参数设置方式 序号 设置方法 方式一 登录管理控制台。 在“实例管理”页面，选择指定的实例，单击实例名称，进入实例基本信息页面。 在左侧导航栏单击“参数修改”，进入参数修改页面，在该页面修改参数。 如果需要修改的参数在管理该控制台无法修改，请提前评估风险后再联系客服进行修改。 重启数据库使参数生效。 说明： 重启数据库集群操作会导致用户执行操作中断，请在操作之前规划好合适的执行窗口。 方式二 登录管理控制台。 在“实例管理”页面，选择指定的实例，单击实例名称，进入实例基本信息页面。 在左侧导航栏单击“参数修改”，进入参数修改页面，在该页面修改参数。 如果需要修改的参数在管理该控制台无法修改，请提前评估风险后再联系客服进行修改。 方式三 修改会话级别的参数。 设置会话级别的参数 1 gaussdb=# SET paraname TO value; 修改本次会话中的取值。退出会话后，设置将失效。 使用方式一和方式二设置参数时，若所设参数不属于当前节点，数据库会提示参数不在支持范围内的相关信息。 使用方式三设置参数时，若参数值为int整型，则会将整数前导零过滤掉，例如SET paraname TO 008192与SET paraname TO 8192效果相同。

参数说明 policy_name 行访问控制策略名称，同一个数据表上行访问控制策略名称不能相同。 table_name 行访问控制策略的表名。 PERMISSIVE | RESTRICTIVE PERMISSIVE指定行访问控制策略为宽容性策略，宽容性策略的条件用OR表达式拼接。RESTRICTIVE指定行访问控制策略为限制性策略，限制性策略的条件用AND表达式拼接。拼接方式如下： (using_expression_permissive_1 OR using_expression_permissive_2 ...) AND (using_expression_restrictive_1 AND using_expression_restrictive_2 ...) 缺省默认为PERMISSIVE。 command 当前行访问控制影响的SQL操作，可指定操作包括：ALL、SELECT、UPDATE、DELETE。当未指定时，ALL为默认值，涵盖SELECT、UPDATE、DELETE操作。 当command为SELECT时，SELECT类操作受行访问控制的影响，只能查看到满足条件(using_expression返回值为TRUE)的元组数据，受影响的操作包括SELECT，SELECT FOR UPDATE/SHARE，UPDATE ... RETURNING，DELETE ... RETURNING。 当command为UPDATE时，UPDATE类操作受行访问控制的影响，只能更新满足条件(using_expression返回值为TRUE)的元组数据，受影响的操作包括UPDATE, UPDATE ... RETURNING, SELECT ... FOR UPDATE/SHARE。 当command为DELETE时，DELETE类操作受行访问控制的影响，只能删除满足条件(using_expression返回值为TRUE)的元组数据，受影响的操作包括DELETE, DELETE ... RETURNING。 行访问控制策略与适配的SQL语法关系参见下表： 表1 ROW LEVEL SECURITY策略与适配SQL语法关系 Command SELECT/ALL policy UPDATE/ALL policy DELETE/ALL policy SELECT Existing row No No SELECT FOR UPDATE/SHARE Existing row Existing row No UPDATE No Existing row No UPDATE RETURNING Existing row Existing row No DELETE No No Existing row DELETE RETURNING Existing row No Existing row role_name 行访问控制影响的数据库用户。 CURRENT_USER表示当前执行环境的用户名；SESSION_USER则表示会话用户名；当未指定时，PUBLIC为默认值，PUBLIC表示影响所有数据库用户，可以指定多个受影响的数据库用户。 系统管理员不受行访问控制特性影响。

示例 --创建表reason_t1。 gaussdb=# CREATE TABLE reason_t1( r_reason_sk integer, r_reason_id character(16), r_reason_desc character(100) ) WITH(STORAGE_TYPE = ustore); --创建表reason_t2。 gaussdb=# CREATE TABLE reason_t2( r_reason_sk integer, r_reason_id character(16), r_reason_desc character(100) ) WITH(STORAGE_TYPE = ustore); -- 对表reason_t1和reason_t2添加索引。 gaussdb=# CREATE INDEX idx_t1 on reason_t1(r_reason_id); gaussdb=# CREATE INDEX idx_t2 on reason_t2(r_reason_id); gaussdb=# DROP TABLE reason_t1; gaussdb=# DROP TABLE reason_t2; --查看回收站。 gaussdb=# SELECT rcyname,rcyoriginname,rcytablespace FROM GS_RECYCLEBIN; rcyname | rcyoriginname | rcytablespace ----------------------------+---------------+--------------- BIN$31C94EB4207$8001$0==$0 | reason_t1 | 0 BIN$31C94EB420D$8001$0==$0 | idx_t1 | 0 BIN$31C94EB420A$8004$0==$0 | reason_t2 | 0 BIN$31C94EB420E$8004$0==$0 | idx_t2 | 0 (4 rows) --PURGE清除表。 gaussdb=# PURGE TABLE reason_t1; gaussdb=# SELECT rcyname,rcyoriginname,rcytablespace FROM GS_RECYCLEBIN; rcyname | rcyoriginname | rcytablespace ----------------------------+---------------+--------------- BIN$31C94EB420A$8004$0==$0 | reason_t2 | 0 BIN$31C94EB420E$8004$0==$0 | idx_t2 | 0 (2 rows) --PURG清除索引。 gaussdb=# PURGE INDEX idx_t2; gaussdb=# SELECT rcyname,rcyoriginname,rcytablespace FROM GS_RECYCLEBIN; rcyname | rcyoriginname | rcytablespace ----------------------------+---------------+--------------- BIN$31C94EB420A$8004$0==$0 | reason_t2 | 0 (1 row) --PURGE清除回收站所有对象。 gaussdb=# PURGE recyclebin; gaussdb=# SELECT rcyname,rcyoriginname,rcytablespace FROM GS_RECYCLEBIN; rcyname | rcyoriginname | rcytablespace -----------------------+---------------+--------------- (0 rows)

enable_twophase_commit 参数说明：当前云数据库主要解决SDS替换问题，采用模式为GTM Free，为防止业务滥用导致不可靠问题，提供guc参数开关enable_twophase_commit禁用分布式写事务，该参数属于USERSET类型参数，请参考表2中对应设置方法进行设置。 取值范围：布尔型 on表示开启GTM-FREE模式下，允许业务进行分布式两阶段写事务。 off表示开启GTM-FREE模式下，禁止业务进行分布式两阶段写事务。 默认值：on

enable_defer_calculate_snapshot 参数说明：延迟计算快照的xmin和oldestxmin，执行1000个事务或者间隔1s才触发计算，设置为on时可以在高负载场景下减少计算快照的开销，但是会导致oldestxmin推进较慢，影响垃圾元组回收，设置为off时xmin和oldestxmin可以实时推进，但是会增加计算快照时的开销。 参数类型：布尔型 参数单位：无 取值范围： on：表示延迟计算快照xmin和oldestxmin。 off：表示实时计算快照xmin和oldestxmin。 默认值：on 设置方式：该参数属于SIGHUP类型参数，请参考表2中对应设置方法进行设置。

enable_gtm_free 参数说明：大并发场景下同一时刻存在活跃事务较多，GTM下发的快照变大且快照请求变多的情况下，瓶颈卡在GTM与CN通讯的网络上。为消除该瓶颈，引入GTM-FREE模式。取消CN和GTM的交互，取消CN下发GTM获取的事务信息给DN。CN只向各个DN发送query，各个DN由本地产生快照及xid等信息，开启该参数支持分布式事务读最终一致性，即分布式事务只有写外部一致性，不具有读外部一致性。 该参数属于POSTMASTER类型参数，请参考表2中对应设置方法进行设置。 业务使用GTM-Free模式时，建议将application_type设置成perfect_sharding_type，以便及时发现可能导致数据不一致的SQL语句。否则，系统不会拦截可能导致数据不一致的语句，造成数据不一致。 取值范围：布尔型 on表示开启GTM-FREE模式，集群状态为读最终一致性。 off表示非GTM-FREE模式。 默认值：off

application_type 参数说明：此参数仅在enable_gtm_free为on时有效。此参数用来说明用户的业务类型。该参数属于USERSET类型参数，请参考表2中对应设置方法进行设置。此参数不允许使用gs_guc设置，只允许以下列两种方式设置： 使用gsql等客户端在session级别设置。 使用jdbc连接数据库时，给连接字符串指定ApplicationType参数。 取值范围：枚举类型 not_perfect_sharding_type表示跨节点的业务。取此值时，允许执行跨节点的语句。 perfect_sharding_type表示单节点的业务。取此值时，如果SQL语句需要多个节点参与，会直接报错。对应的SQL语句会同时打印到系统日志中。 取此值时，使用/*+ multinode */ hint可以显示允许SQL语句在多个节点执行。multinode hint可以加到select、insert、update、delete、merge关键字之后。

transaction_isolation 参数说明：设置当前事务的隔离级别。 该参数属于USERSET类型参数，请参考表2中对应设置方法进行设置。 取值范围：字符串，只识别以下字符串，大小写空格敏感： serializable：GaussDB中等价于REPEATABLE READ。 read committed：只能读取已提交的事务的数据（缺省），不能读取到未提交的数据。 repeatable read：仅能读取事务开始之前提交的数据，不能读取未提交的数据以及在事务执行期间由其它并发事务提交的修改。 default：设置为defualt_transaction_isolation所设隔离级别。 默认值：read committed

transaction_deferrable 参数说明：指定是否允许一个只读串行事务延迟执行，使其不会执行失败。该参数设置为on时，当一个只读事务发现读取的元组正在被其他事务修改，则延迟该只读事务直到其他事务修改完成。该参数为预留参数，该版本不生效。与该参数类似的还有一个default_transaction_deferrable，设置它来指定一个事务是否允许延迟。 该参数属于USERSET类型参数，请参考表2中对应设置方法进行设置。 取值范围：布尔型 on表示允许执行。 off表示不允许执行。 默认值：off

pgxc_node_name 参数说明：指定节点名称。 该参数属于POSTMASTER类型参数，请参考表2中对应设置方法进行设置。 在备机请求主机进行日志复制时，如果application_name参数没有被设置，那么pgxc_node_name参数会被用来作为备机在主机上的流复制槽名字。该流复制槽的命名方式为 "该参数值_备机ip_备机port"。其中，备机ip和备机port取自replconninfo参数中指定的备机ip和端口号。该流复制槽最大长度为61个字符，如果拼接后的字符串超过该长度，则会使用截断后的pgxc_node_name进行拼接，以保证流复制槽名字长度小于等于61个字符。 此参数修改后会导致连接集群失败，不建议进行修改。 取值范围：字符串。 默认值：当前节点名称。

enable_show_any_tuples 参数说明：该参数只有在只读事务中可用，用于分析。当这个参数被置为on/true时，表中元组的所有版本都会可见。 该参数属于USERSET类型参数，请参考表2中对应设置方法进行设置。 取值范围：布尔型 on/true表示表中元组的所有版本都会可见。 off/false表示表中元组的所有版本都不可见。 默认值：off 在toast场景下，如果reindex前后均有dml操作（主要是insert+update或insert+delete），在reindex操作后，开启只读事务并打开该GUC参数，release版本下单独查询toast表或toast索引表历史数据正常，但是通过主表查询toast列历史数据会报错“missing chunk number xxx”。

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 gaussdb=# CREATE OR REPLACE PROCEDURE proc_case_branch(pi_result in integer, pi_return out integer) AS BEGIN CASE pi_result WHEN 1 THEN pi_return := 111; WHEN 2 THEN pi_return := 222; WHEN 3 THEN pi_return := 333; WHEN 6 THEN pi_return := 444; WHEN 7 THEN pi_return := 555; WHEN 8 THEN pi_return := 666; WHEN 9 THEN pi_return := 777; WHEN 10 THEN pi_return := 888; ELSE pi_return := 999; END CASE; raise info 'pi_return : %',pi_return ; END; / CREATE PROCEDURE gaussdb=# CALL proc_case_branch(3,0); INFO: pi_return : 333 pi_return ----------- 333 (1 row) --删除存储过程 gaussdb=# DROP PROCEDURE proc_case_branch; DROP PROCEDURE

建议 推荐使用两个表*的hint。对于两个表采用*操作符的hint，只要两个表出现在join的两端，都会触发hint。例如：设置hint为rows(t1 t2 * 3)，对于(t1 t3 t4)和(t2 t5 t6)join时，由于t1和t2出现在join的两端，所以其join的结果集也会应用该hint规则乘以3。 rows hint支持在单表、多表、function table及subquery scan table的结果集上指定hint。

参数说明 @queryblock请参见指定Hint所处的查询块Queryblock章节，可省略，表示在当前查询块生效。 “#”、“+”、“-”、“*”，进行行数估算hint的四种操作符号。#表示直接使用后面的行数进行hint。“+”、“-”、“*”表示对原来估算的行数进行加、减、乘操作，运算后的行数最小值为1行。table_list为hint对应的单表或多表join结果集，与Join方式的Hint中table_list相同。

示例 --创建一个兼容性为ORA的数据库。 gaussdb=# CREATE DATABASE ora_test_db DBCOMPATIBILITY 'ORA'; --切换数据库。 gaussdb=# \c ora_test_db --创建拥有系统管理员权限的用户。 ora_test_db=# CREATE USER user1 WITH SYSADMIN PASSWORD '********'; ora_test_db=# SET ROLE user1 PASSWORD '********'; --创建私有dblink。 ora_test_db=# CREATE DATABASE LINK private_dblink CONNECT TO 'user1' IDENTIFIED BY '********' USING (host '192.168.11.11',port '54399',dbname 'db01'); --删除私有dblink。 ora_test_db=# DROP DATABASE LINK private_dblink; --创建公共dblink。 ora_test_db=# CREATE PUBLIC DATABASE LINK public_dblink CONNECT TO 'user1' IDENTIFIED BY '********' USING (host '192.168.11.11',port '54399',dbname 'db01'); --删除公共dblink。 ora_test_db=# DROP PUBLIC DATABASE LINK public_dblink; --删除创建出的用户。 ora_test_db=# RESET ROLE; ora_test_db=# DROP USER user1; --切换回初始数据库，并删除测试数据库。请用真实的数据库名替换postgres。 ora_test_db=# \c postgres gaussdb=# DROP DATABASE ora_test_db;

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 --创建表customer_demographics_t1。 gaussdb=# CREATE TABLE customer_demographics_t1 ( CD_DEMO_SK INTEGER NOT NULL, CD_GENDER CHAR(1) , CD_MARITAL_STATUS CHAR(1) , CD_EDUCATION_STATUS CHAR(20) , CD_PURCHASE_ESTIMATE INTEGER , CD_CREDIT_RATING CHAR(10) , CD_DEP_COUNT INTEGER , CD_DEP_EMPLOYED_COUNT INTEGER , CD_DEP_COLLEGE_COUNT INTEGER ) DISTRIBUTE BY HASH (CD_DEMO_SK); --插入记录。 gaussdb=# INSERT INTO customer_demographics_t1 VALUES(1920801,'M', 'U', 'DOCTOR DEGREE', 200, 'GOOD', 1, 0,0); --开启事务。 gaussdb=# START TRANSACTION; --更新字段值。把cd_education_status字段值更新为Unknown。 gaussdb=# UPDATE customer_demographics_t1 SET cd_education_status= 'Unknown'; --终止事务，上面所执行的更新会被撤销掉。 gaussdb=# ABORT; --查询数据。发现cd_education_status字段的值未被修改成Unknown。 gaussdb=# SELECT * FROM customer_demographics_t1 WHERE cd_demo_sk = 1920801; cd_demo_sk | cd_gender | cd_marital_status | cd_education_status | cd_purchase_estimate | cd_credit_rating | cd_dep_count | cd_dep_employed_count | cd_dep_college_count ------------+-----------+-------------------+----------------------+----------------------+------------------+--------------+-----------------------+---------------------- 1920801 | M | U | DOCTOR DEGREE | 200 | GOOD | 1 | 0 | 0 (1 row) --删除表。 gaussdb=# DROP TABLE customer_demographics_t1;

变量作用域 变量的作用域表示变量在代码块中的可访问性和可用性。只有在它的作用域内，变量才有效。 变量必须在declare部分声明，即必须建立BEGIN-END块。块结构也强制变量必须先声明后使用，即变量在过程内有不同作用域、不同的生存期。 同一变量可以在不同的作用域内定义多次，内层的定义会覆盖外层的定义。 在外部块定义的变量，可以在嵌套块中使用。但外部块不能访问嵌套块中的变量。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 gaussdb=# DECLARE emp_id INTEGER :=7788; --定义变量并赋值 outer_var INTEGER :=6688; --定义变量并赋值 BEGIN DECLARE emp_id INTEGER :=7799; --定义变量并赋值 inner_var INTEGER :=6688; --定义变量并赋值 BEGIN dbe_output.print_line('inner emp_id ='||emp_id); --显示值为7799 dbe_output.print_line('outer_var ='||outer_var); --引用外部块的变量 END; dbe_output.print_line('outer emp_id ='||emp_id); --显示值为7788 END; /

环境变量 表5 与gsql相关的环境变量 名称 描述 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 用户的.gsqlrc文件的交互位置。 SHELL 使用\!命令跟shell执行的命令是一样的效果。 TMPDIR 存储临时文件的目录。缺省是/tmp。

PATTERN 很多\d命令都可以用一个PATTERN参数来指定要被显示的对象名称。在最简单的情况下，PATTERN正好就是该对象的准确名称。在PATTERN中的字符通常会被变成小写形式（就像在SQL名称中那样），例如\dt FOO将会显示名为foo的表。就像在SQL名称中那样，把PATTERN放在双引号中可以阻止它被转换成小写形式。如果需要在一个PATTERN中包括一个真正的双引号字符，则需要把它写成两个相邻的双引号，这同样是符合SQL引用标识符的规则。例如，\dt "FOO""BAR"将显示名为FOO"BAR（不是foo"bar）的表。和普通的SQL名称规则不同，不能只在PATTERN的一部分周围放上双引号，例如\dt FOO"FOO"BAR将会显示名为fooFOObar的表。 不使用PATTERN参数时，\d命令会显示当前schema搜索路径中可见的全部对象——这等价于用*作为PATTERN。所谓对象可见是指可以直接用名称引用该对象，而不需要用schema来进行限定。要查看数据库中所有的对象而不管它们的可见性，可以把*.*用作PATTERN。 如果放在一个PATTERN中，*将匹配任意字符序列（包括空序列），而?会匹配任意的单个字符（这种记号方法就像 UNIX shell 的文件名PATTERN一样）。例如，\dt int*会显示名称以int开始的表。但是如果被放在双引号内，*和?就会失去这些特殊含义而变成普通的字符。 包含一个点号（.）的PATTERN被解释为一个schema名称模式后面跟上一个对象名称模式。例如，\dt foo*.*bar*会显示名称以foo开始的schema中所有名称包括bar的表。如果没有出现点号，那么模式将只匹配当前schema搜索路径中可见的对象。同样，双引号内的点号会失去其特殊含义并且变成普通的字符。 高级用户可以使用字符类等正则表达式记法，如[0-9]可以匹配任意数字。所有的正则表达式特殊字符都按照POSIX正则表达式所说的工作。以下字符除外： .会按照上面所说的作为一种分隔符。 *会被翻译成正则表达式记号.*。 ?会被翻译成.。 $则按字面意思匹配。 根据需要，可以通过书写?、(R+|)、(R|)和R?来分别模拟PATTERN字符.、R*和R?。$不需要作为一个正则表达式字符，因为PATTERN必须匹配整个名称，而不是像正则表达式的常规用法那样解释（换句话说，$会被自动地追加到PATTERN上）。如果不希望该PATTERN的匹配位置被固定，可以在开头或者结尾写上*。注意在双引号内，所有的正则表达式特殊字符会失去其特殊含义并且按照其字面意思进行匹配。另外，在操作符名称PATTERN中（即\do的PATTERN参数），正则表达式特殊字符也按照字面意思进行匹配。

元命令 元命令的详细说明请参见表1、表2、表3、表4、表6、表8、表9、表10和表12。 以下命令中所提到的FILE代表文件路径。此路径可以是绝对路径（如/home/gauss/file.txt），也可以是相对路径（file.txt，file.txt会默认在用户执行gsql命令所在的路径下创建）。 表1 一般的元命令 参数 参数说明 取值范围 \copyright 显示GaussDB的版本和版权信息。 - \g [FILE] or ; 执行查询（并将结果发送到文件或管道）。 - \h(\help) [NAME] 给出指定SQL语句的语法帮助。 如果没有给出NAME，gsql将列出可获得帮助的所有命令。如果NAME是一个星号（*），则显示所有SQL语句的语法帮助。 \parallel [on [num]|off] 控制并发执行开关。 on：打开控制并发执行开关，且最大并发数为num。 off：关闭控制并发执行开关。 说明： 不支持事务中开启并发执行以及并发中开启事务。 不支持\d这类元命令的并发。 并发select返回结果混乱问题，此为客户可接受，core、进程停止响应不可接受。 不推荐在并发中使用set语句，否则导致结果与预期不一致。 不支持创建临时表！如需使用临时表，需要在开启parallel之前创建好，并在parallel内部使用。parallel内部不允许创建临时表。 \parallel执行时最多会启动num个独立的gsql进程连接服务器。 \parallel中所有作业的持续时间不能超过session_timeout，否则可能会导致并发执行过程中断连。 num的默认值：1024。 须知： 服务器能接受的最大连接数受max_connection及当前已有连接数限制。 设置num时请考虑服务器当前可接受的实际连接数合理指定。 \q 退出gsql程序。在一个脚本文件里，只在脚本终止的时候执行。 - 表2 查询缓存区元命令 参数 参数说明 \e [FILE] [LINE] 使用外部编辑器编辑查询缓冲区（或者文件）。 \ef [FUNCNAME [LINE]] 使用外部编辑器编辑函数定义。如果指定了LINE（即行号），则光标会指到函数体的指定行。 \p 打印当前查询缓冲区到标准输出。 \r 重置（或清空）查询缓冲区。 \w FILE 将当前查询缓冲区输出到文件。 表3 输入/输出元命令 参数 参数说明 \copy { table [ ( column_list ) ] | ( query ) } { from | to } { filename | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] 'character' ] [ useeof ] [ 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命令的操作，但不是读取或写入指定文件的服务器，而是读取或写入文件，并在服务器和本地文件系统之间路由数据。这意味着文件的可访问性和权限是本地用户的权限，而不是服务器的权限，并且不需要数据库初始化用户权限。 说明： \COPY只适合小批量，格式良好的数据导入，不会对非法字符进行预处理，也无容错能力。导入数据应优先选择GDS或COPY。 \COPY 可以指定数据导入时的客户端数量，从而实现数据文件的并行导入，目前并发数范围为[1, 8]。 \COPY并行导入目前存在以下约束： 临时表的并行导入不支持、在事务内的并行导入不支持、对二进制文件的并行导入不支持、数据导入支持AES128加密时不支持以及COPY选项中存在EOL。在这些情况下，即使指定了parallel参数，仍然会走非并行流程。 \echo [STRING] 把字符串写到标准输出。 \i FILE 从文件FILE中读取内容，并将其当作输入，执行查询。 \i+ FILE KEY 执行加密文件中的命令。 \ir FILE 和\i类似，只是相对于存放当前脚本的路径。 \ir+ FILE KEY 和\i+类似，只是相对于存放当前脚本的路径。 \o [FILE] 把所有的查询结果发送到文件里。 \qecho [STRING] 把字符串写到查询结果输出流里。 表4中的选项S表示显示系统对象，+表示显示对象附加的描述信息。PATTERN用来指定要被显示的对象名称。 表4 显示信息元命令 参数 参数说明 取值范围 示例 \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 \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] 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\du。为了和以前兼容，所以保留两个命令。 如果指定了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的规则。缺省或指定*时，则会列出所有设置。 列出数据库所有修改过的配置参数。 1 openGauss=# \drds * dbname \dT[S+] [PATTERN] 列出所有的数据类型。 如果指定了PATTERN，只列出名称匹配PATTERN的类型。 列出所有的数据类型。 1 openGauss=# \dT \du[+] [PATTERN] 列出所有数据库角色。 说明： 因为用户和群组的概念被统一为角色，所以这个命令等价于\dg。为了和以前兼容，所以保留两个命令。 如果指定了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，列出函数的定义。 1 2 3 openGauss=# \sf function_a openGauss=# \sf "func()name"(argtype1, argtype2) \z [PATTERN] 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 如果给出任何pattern ，则被当成一个正则表达式，只显示匹配的表、视图、序列。 列出数据库中所有表、视图和序列，以及它们相关的访问特权。 1 openGauss=# \z 表5 权限的参数说明 参数 参数说明 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操作。 * 给前面权限的授权选项。 表6 格式化元命令 参数 参数说明 \a 对齐模式和非对齐模式之间的切换。 \C [STRING] 把正在打印的表的标题设置为一个查询的结果或者取消这样的设置。 \f [STRING] 对于不对齐的查询输出，显示或者设置域分隔符。 \H 若当前模式为文本格式，则切换为HTML输出格式。 若当前模式为HTML格式，则切换回文本格式。 \pset NAME [VALUE] 设置影响查询结果表输出的选项。NAME的取值见表7。 \t [on|off] 切换输出的字段名的信息和行计数脚注。 \T [STRING] 指定在使用HTML输出格式时放在table标签里的属性。如果参数为空，不设置。 \x [on|off|auto] 切换扩展行格式。 表7 可调节的打印选项 选项 选项说明 取值范围 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 切换是否输出结果行数。 - 表8 连接元命令 参数 参数说明 取值范围 \c[onnect] [DBNAME|- USER|- HOST|- PORT|-] 连接到一个新的数据库。当数据库名称长度超过63个字节时，默认前63个字节有效，连接到前63个字节对应的数据库，但是gsql的命令提示符中显示的数据库对象名仍为截断前的名称。 说明： 重新建立连接时，如果切换数据库登录用户，将可能会出现交互式输入，要求输入新用户的连接密码。该密码最长长度为999字节，受限于GUC参数password_max_length的最大值。 - \encoding [ENCODING] 设置客户端字符编码格式。 不带参数时，显示当前的编码格式。 \conninfo 输出当前连接的数据库的信息。 - 表9 操作系统元命令 参数 参数说明 取值范围 \cd [DIR] 切换当前的工作目录。 绝对路径或相对路径，且满足操作系统路径命名规则。 \setenv NAME [VALUE] 设置环境变量NAME为VALUE，如果没有给出VALUE值，则不设置环境变量。 - \timing [on|off] 以毫秒为单位显示每条SQL语句的执行时间。 on表示打开显示。 off表示关闭显示。 \! [COMMAND] 返回到一个单独的UNIX shell或者执行UNIX命令COMMAND。 - 表10 变量元命令 参数 参数说明 \prompt [TEXT] NAME 提示用户用文本格式来指定变量名称。 \set [NAME [VALUE]] 设置内部变量NAME为VALUE或者如果给出了多于一个值，设置为所有这些值的连接结果。如果没有给出第二个参数，只设变量不设值。 有一些常用变量被gsql特殊对待，它们是一些选项设置，通常所有特殊对待的变量都是由大写字母组成(可能还有数字和下划线)。 表11是一个所有特殊对待的变量列表。 \unset NAME 不设置（或删除）gsql变量名。 表11 \set常用命令 名称 命令说明 取值范围 \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客户端退出之前务必保证所有的事务已经提交。 说明： gsql默认使用自动提交模式，若关闭自动提交，将会导致后面执行的语句都受到隐式事务包裹，数据库中不支持在事务中执行的语句不能在此模式下执行。 on表示打开自动提交。 off表示关闭自动提交。 表12 大对象元命令 参数 参数说明 \lo_list 显示一个目前存储在该数据库里的所有GaussDB大对象和提供给他们的注释。

注意事项 一个gsql元命令的格式是反斜杠后面紧跟一个动词，然后是任意参数。参数命令动词和其他参数以任意个空白字符间隔。 要在参数里面包含空白，必须用单引号把它引起来。要在这样的参数里包含单引号，可以在前面加一个反斜杠。任何包含在单引号里的内容都会被进一步进行类似C语言的替换：\n（新行）、\t（制表符）、\b（退格）、\r（回车）、\f（换页）、\digits（八进制表示的字符）、\xdigits（十六进制表示的字符）。 用""包围的内容被当做一个命令行传入shell。该命令的输出（删除了结尾的新行）被当做参数值。 如果不带引号的参数以冒号（:）开头，它会被当做一个gsql变量，并且该变量的值最终会成为真正的参数值。 有些命令以一个SQL标识的名称（比如一个表）为参数。这些参数遵循SQL语法关于双引号的规则：不带双引号的标识强制转换成小写，而双引号保护字母不进行大小写转换，并且允许在标识符中使用空白。在双引号中，成对的双引号在结果名称中分析成一个双引号。比如，FOO"BAR"BAZ解析成fooBARbaz；而"Aweird""name"解析成A weird"name。 对参数的分析在遇到另一个不带引号的反斜杠时停止。这里会认为是一个新的元命令的开始。特殊的双反斜杠序列（\\）标识参数的结尾并将继续分析后面的SQL语句（如果存在）。这样SQL和gsql命令可以自由地在一行里面混合。但是在任何情况下，一条元命令的参数不能延续超过行尾。

示例 以把一个查询分成多行输入为例。注意提示符的变化： 1 2 3 4 5 openGauss=# CREATE TABLE HR.areaS( openGauss(# area_ID NUMBER, openGauss(# area_NAME VARCHAR2(25) openGauss-# )tablespace EXAMPLE; CREATE TABLE 查看表的定义： 1 2 3 4 5 6 openGauss=# \d HR.areaS Table "hr.areas" Column | Type | Modifiers -----------+-----------------------+----------- area_id | numeric | not null area_name | character varying(25) | 向HR.areaS表插入四行数据： 1 2 3 4 5 6 7 8 openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (1, 'Europe'); INSERT 0 1 openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (2, 'Americas'); INSERT 0 1 openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (3, 'Asia'); INSERT 0 1 openGauss=# INSERT INTO HR.areaS (area_ID, area_NAME) VALUES (4, 'Middle East and Africa'); INSERT 0 1 切换提示符： 1 2 openGauss=# \set PROMPT1 '%n@%m %~%R%#' omm@[local] openGauss=# 查看表： 1 2 3 4 5 6 7 8 omm@[local] openGauss=#SELECT * FROM HR.areaS; area_id | area_name ---------+------------------------ 1 | Europe 4 | Middle East and Africa 2 | Americas 3 | Asia (4 rows) 可以用\pset命令以不同的方法显示表： 1 2 3 4 5 6 7 8 9 10 11 12 omm@[local] openGauss=#\pset border 2 Border style is 2. omm@[local] openGauss=#SELECT * FROM HR.areaS; +---------+------------------------+ | area_id | area_name | +---------+------------------------+ | 1 | Europe | | 2 | Americas | | 3 | Asia | | 4 | Middle East and Africa | +---------+------------------------+ (4 rows) 1 2 3 4 5 6 7 8 9 10 omm@[local] openGauss=#\pset border 0 Border style is 0. omm@[local] openGauss=#SELECT * FROM HR.areaS; area_id area_name ------- ---------------------- 1 Europe 2 Americas 3 Asia 4 Middle East and Africa (4 rows) 使用元命令： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 omm@[local] openGauss=#\a \t \x Output format is unaligned. Showing only tuples. Expanded display is on. omm@[local] openGauss=#SELECT * FROM HR.areaS; area_id|2 area_name|Americas area_id|1 area_name|Europe area_id|4 area_name|Middle East and Africa area_id|3 area_name|Asia omm@[local] openGauss=#

操作步骤 使用gsql连接到GaussDB服务器。 gsql工具使用-d参数指定目标数据库名、-U参数指定数据库用户名、-h参数指定主机名、-p参数指定端口号信息。 若未指定数据库名称，则使用初始化时默认生成的数据库名称；若未指定数据库用户名，则默认使用当前操作系统用户作为数据库用户名；当某个值没有前面的参数（-d、-U等）时，若连接的命令中没有指定数据库名（-d）则该参数会被解释成数据库名；如果已经指定数据库名（-d）而没有指定数据库用户名（-U）时，该参数则会被解释成数据库用户名。 示例1，使用omm用户连接到本机gaussdb数据库的8000端口。 gsql -d gaussdb -p 8000 示例2，使用jack用户连接到远程主机gaussdb数据库的8000端口。 gsql -h 10.180.123.163 -d gaussdb -U jack -p 8000 示例3，参数gaussdb和omm不属于任何选项时，分别被解释成了数据库名和用户名。 gsql gaussdb omm -p 8000 等效于 gsql -d gaussdb -U omm -p 8000 详细的gsql参数请参见命令参考。 执行SQL语句。 以创建数据库human_staff为例。 1 2 CREATE DATABASE human_staff; CREATE DATABASE 通常，输入的命令行在遇到分号的时候结束。如果输入的命令行没有错误，结果就会输出到屏幕上。 执行gsql元命令。 以列出GaussDB中所有的数据库和描述信息为例。 1 2 3 4 5 6 7 8 9 10 11 12 openGauss=# \l List of databases Name | Owner | Encoding | Collate | Ctype | Access privileges ----------------+----------+-----------+---------+-------+----------------------- human_resource | omm | SQL_ASCII | C | C | postgres | omm | SQL_ASCII | C | C | template0 | omm | SQL_ASCII | C | C | =c/omm + | | | | | omm=CTc/omm template1 | omm | SQL_ASCII | C | C | =c/omm + | | | | | omm=CTc/omm human_staff | omm | SQL_ASCII | C | C | (5 rows) 更多gsql元命令请参见元命令参考。