华为云用户手册

Psycopg接口参考 Psycopg接口是一套提供给用户的API方法，本节将对部分常用接口做具体描述。 psycopg2.connect() connection.cursor() cursor.execute(query,vars_list) cursor.executemany(query,vars_list) connection.commit() connection.rollback() cursor.fetchone() cursor.fetchall() cursor.close() connection.close() 父主题： 基于Psycopg开发

语法格式 设置外部数据封装属性 ALTER FOREIGN DATA WRAPPER name [ HANDLER handler_function | NO HANDLER ] [ VALIDATOR validator_function | NO VALIDATOR ] [ OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ]) ];

参数说明 name 已有外部数据封装的名称。 HANDLER handler_function 为外部数据封装指定一个新的处理函数。 NO HANDLER 这个参数用来指定外部数据封装不再拥有处理函数。 使用外部数据封装但没有handler的外表不能访问。 VALIDATOR validator_function 为外部数据封装指定一个新的验证函数。 根据新的验证器，外部数据封装器或依赖的服务器、 用户映射或外部表的已经存在的选项是有可能是无效的。用户在使用外部数据封装之前需要保证这些选项是正确的。 不过，ALTER FOREIGN DATA WRAPPER 命令中指定的任何选项都将使用新的验证函数检查。 NO VALIDATOR 这个用来指定外部数据封装不再有验证函数。 OPTIONS ( [ ADD | SET | DROP ] option ['value'] [, ... ] ) 修改外部数据封装的选项。 ADD, SET, 和 DROP 指定表现的动作。如果没有明确指定操作默认是ADD。选项名必须唯一。 使用外部数据封装验证函数时，名字和取值也会被验证。

示例 --创建一个外部数据封装dbi。 gaussdb=# CREATE FOREIGN DATA WRAPPER dbi OPTIONS (bar 'true'); --修改一个外部数据封装dbi，增加选项foo，删除bar。 gaussdb=# ALTER FOREIGN DATA WRAPPER dbi OPTIONS (ADD foo '1', DROP 'bar'); --修改外部数据封装dbi验证器为file_fdw_validator。 gaussdb=# ALTER FOREIGN DATA WRAPPER dbi VALIDATOR file_fdw_validator; --修改外部数据封装dbi处理函数为file_fdw_handler。 gaussdb=# ALTER FOREIGN DATA WRAPPER dbi HANDLER file_fdw_handler;

STATIO_SYS_SEQUEN CES STATIO_SYS_SEQUENCES显示命名空间中所有系统序列的I/O状态信息，如表1所示。 表1 STATIO_SYS_SEQUENCES字段 名称 类型 描述 relid oid 序列OID。 schemaname name 序列中模式名。 relname name 序列名。 blks_read bigint 从序列中读取的磁盘块数。 blks_hit bigint 序列中缓存命中数。 父主题： Cache/IO

示例 --创建表。 gaussdb=# CREATE TABLE my_table (c1 int, c2 int) WITH(STORAGE_TYPE=ASTORE); --创建名为my_mv的物化视图。 gaussdb=# CREATE MATERIALIZED VIEW my_mv AS SELECT * FROM my_table; --删除名为my_mv的物化视图。 gaussdb=# DROP MATERIALIZED VIEW my_mv; --删除表。 gaussdb=# DROP TABLE my_table;

GS_MY_ILMTASKS GS_MY_ILMTASKS视图反映ADO Task的概要信息，包含Task ID，Task Owner，状态以及时间信息。 表1 GS_MY_ILMTASKS字段 名称 类型 描述 task_id bigint ADO Task的ID。 task_owner character varying(128) ADO Task发起的用户。 state character varying(9) 状态： INACTIVE：非活动。 ACTIVE：活动。 COMPLETED：完成。 UNKNOWN：评估中。 creation_time timestamp with time zone 创建时间。 start_time timestamp with time zone 变成活动状态的时间。 completion_time timestamp with time zone 完成时间。 node_name name 数据来源节点的名称。 父主题： OLTP表压缩

ADM_AUDIT_STATEMENT ADM_AUDIT_STATEMENT显示所有GRANT、REVOKE审计跟踪条目， GaussDB 审计信息主要通过gs_query_audit函数查询，该视图同时存在于PG_CATA LOG 和SYS schema下。仅拥有AUDITADMIN属性的用户才可以查看审计信息。 表1 ADM_AUDIT_STATEMENT字段 名称 类型 描述 os_username character varying(255) 暂不支持，值为NULL。 username character varying(128) 操作被审计的用户的名称，不是用户id。 userhost character varying(128) 暂不支持，值为NULL。 terminal character varying(255) 暂不支持，值为NULL。 timestamp date 在本地数据库会话时区中创建审计跟踪条目的日期和时间（审计会话创建条目的用户的登录日期和时间）。 owner character varying(128) 受操作影响的对象的创建者。 obj_name character varying(128) 受操作影响的对象的名称。 action_name character varying(28) action列中的数字代码对应的action类型名称。 说明： GaussDB的action_name字段与ORA数据库审计动作不一致。 new_name character varying(128) 暂不支持，值为NULL。 obj_privilege character varying(32) 暂不支持，值为NULL。 sys_privilege character varying(40) 暂不支持，值为NULL。 admin_option character varying(1) 暂不支持，值为NULL。 grantee character varying(128) 暂不支持，值为NULL。 audit_option character varying(40) 暂不支持，值为NULL。 ses_actions character varying(19) 暂不支持，值为NULL。 comment_text character varying(4000) 暂不支持，值为NULL。 sessionid numeric 暂不支持，值为NULL。 entryid numeric 暂不支持，值为NULL。 statementid numeric 暂不支持，值为NULL。 returncode numeric 暂不支持，值为NULL。 priv_used character varying(40) 暂不支持，值为NULL。 client_id character varying(128) 暂不支持，值为NULL。 econtext_id character varying(64) 暂不支持，值为NULL。 session_cpu numeric 暂不支持，值为NULL。 extended_timestamp timestamp(6) with time zone 创建审计跟踪条目的时间戳（创建条目的用户登录时间戳UTC（协调通用）中的审计会话时间）时区。 proxy_sessionid numeric 暂不支持，值为NULL。 global_uid character varying(32) 暂不支持，值为NULL。 instance_number numeric 暂不支持，值为NULL。 os_process character varying(16) 暂不支持，值为NULL。 transactionid text 访问或修改对象事务的事务标识符。 说明： GaussDB的transactionid字段与ORA数据库中transactionid数据的类型保持一致。 scn numeric 暂不支持，值为NULL。 sql_bind nvarchar2(2000) 暂不支持，值为NULL。 sql_text character varying(2000) 查询的SQL文本。 说明： GaussDB的sql_text字段为解析后sql描述语句，不完全与执行的sql语句相同。 obj_edition_name character varying(128) 暂不支持，值为NULL。 父主题： 审计

示例 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 --创建test_jim和test_tom用户。 gaussdb=# CREATE USER test_jim PASSWORD '********'; gaussdb=# CREATE USER test_tom PASSWORD '********'; --查看自动创建的模式的拥有者为同名的用户。 gaussdb=# \dn test* List of schemas Name | Owner ----------+---------- test_jim | test_jim test_tom | test_tom (2 rows) --将所有test_jim拥有的数据库对象的属主更改为test_tom。 gaussdb=# REASSIGN OWNED BY test_jim TO test_tom; --查看schema的信息，test_jim模式的属主更换为test_tom。 gaussdb=# \dn test* List of schemas Name | Owner ----------+---------- test_jim | test_tom test_tom | test_tom (2 rows) --删除test_jim和test_tom用户。 gaussdb=# DROP USER test_jim, test_tom CASCADE;

设置回调 设置回调操作，当告警或者错误发生时，直接执行具体操作进行处理，设置回调命令如下： EXEC SQL WHENEVER condition action; condition取值范围： SQLERROR：当在SQL语句执行期间发生错误时，调用指定操作。 SQLWARNING：当在SQL语句执行期间发生告警时，调用指定操作。 NOT FOUND：当SQL语句检索或者影响为零行时，调用指定操作。 action取值范围： CONTINUE：忽略回调错误条件，继续执行，通常可以用来停止break包含条件，为缺省值。 GOTO label/GO TO label：跳转到指定标签（使用C语言goto语句）。 SQLPRINT：输出消息到标准错误。 STOP：调用exit(1)，终止程序。 DO BREAK：执行C语句break，只能在循环中或者switch语句中使用。 示例如下： /* 当出现一个告警时它打印一个消息，发生一个错误时中止程序。 */ EXEC SQL WHENEVER SQLWARNING SQLPRINT; EXEC SQL WHENEVER SQLERROR STOP; 语句EXEC SQL WHENEVER是SQL预处理器的一个指令，而非一个C语言语句。不管C语言程序的流程如何，该语句设置的错误或告警动作都适用于位于处理程序设置点之后的嵌入式SQL语句，除非第一个EXEC SQL WHENEVER语句和导致错误或告警情况发生的SQL语句之间为同一个情况设置了不同的动作。因此下面的两个C语言程序都不会得到预期的效果： /* * 错误 */ void func() { ... if (verbose) { EXEC SQL WHENEVER SQLWARNING SQLPRINT; } ... EXEC SQL SELECT ...; ... } /* * 错误 */ void func() { ... set_error_handler(); ... EXEC SQL SELECT ...; ... } static void set_error_handler(void) { EXEC SQL WHENEVER SQLERROR STOP; } 当使用DO BREAK时只能用于while/for/switch场景，且用完需要使用CONTINUE语句忽略。 父主题： 错误处理

GLOBAL_AIO_SLOT_USAGE_STATUS GLOBAL_AIO_SLOT_USAGE_STATUS视图显示集群所有实例中异步I/O提交槽位的相关统计信息，如表1所示。该视图需在CN上查询，在DN上查询报错。 表1 GLOBAL_AIO_SLOT_USAGE_STATUS字段 参数 类型 描述 node_name text 实例名称。 slot_id integer 槽位id。 slot_type "char" 槽位类型（r：读，w：写）。 status boolean 槽位占用状态。 buffer_id bigint 该槽位对应的buffer id。 relfilenode_blocknum text 该槽位对应的buffer所在的物理页面位置。 lsn bigint 页面对应的LSN。 submitted_time bigint 页面异步提交时的时间。 elapsed_time bigint 页面已经等待的时间。 父主题： Utility

PG_TS_CONFIG PG_TS_CONFIG系统表包含表示文本搜索配置的记录。其中的每一条配置包含一个特定的文本搜索解析器和字典映射的列表。 解析器在PG_TS_CONFIG记录中显示，但是字典映射的标记是由PG_TS_CONFIG_MAP里面的辅助记录定义的。 表1 PG_TS_CONFIG字段 名称 类型 引用 描述 oid oid - 行标识符（隐含字段，必须明确选择）。 cfgname name - 文本搜索配置名。 cfgnamespace oid PG_NAMESPACE.oid 包含这个配置的名称空间的OID。 cfgowner oid PG_AUTHID.oid 配置的所有者。 cfgparser oid PG_TS_PARSER.oid 这个配置的文本搜索解析器的OID。 cfoptions text[] - 分词相关配置选项。 父主题： 其他系统表

示例 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 --插入内容。 gaussdb=# ALTER GLOBAL CONFIGURATION with(redis_is_ok = true); --查询。 gaussdb=# SELECT * FROM gs_global_config; name | value -----------------+------- buckets_len | 16384 undostoragetype | page redis_is_ok | true (3 rows) --修改内容。 gaussdb=# ALTER GLOBAL CONFIGURATION with(redis_is_ok = false); --查询。 gaussdb=# SELECT * FROM gs_global_config; name | value -----------------+------- buckets_len | 16384 undostoragetype | page redis_is_ok | false (3 rows) --删除内容。 gaussdb=# DROP GLOBAL CONFIGURATION redis_is_ok; --查询。 gaussdb=# SELECT * FROM gs_global_config; name | value -----------------+------- buckets_len | 16384 undostoragetype | page (2 rows)

注意事项 仅支持数据库初始用户运行此命令。 参数名称不能为weak_password、undostoragetype。 参数名称为扩容重分布预留参数时，需设置GUC参数enable_cluster_resize为on，或者使用扩容工具进行修改。涉及的参数名称包括：lockwait_timeout、lockwait_interval、trylock_threshold、enable_cancel、last_catchup_threshold、catchup_times、write_error_mode、catchup_query_dop、parallel_catchup_threshold、parallel_reindex_jobs、redis_retry_times、redis_retry_interval、redis_bucket_expansion、redis_bucket_batchsize、redis_bucket_log_level、redis_bucket_lockhold_timeout、redis_bucket_timeout_penalty、redis_bucket_max_lockwait_timeout_retry、redis_bucket_max_lockhold_timeout_retry、redis_bucket_strategy_history_capacity、redis_bucket_strategy_recent_threshold、redis_bucket_workload_rule、redis_bucket_lsn_rule、redis_bucket_tx_bucket_min、redis_bucket_tx_bucket_max、redis_max_expected_tps、redis_bucket_sender_concurrency、redis_bucket_receiver_concurrency、redis_bucket_parse_redo_num、redis_bucket_workers_per_paser以及redis_bucket_keep_bucketxlogs。

SUMMARY_REL_IOSTAT 获取集群上所有节点的数据文件I/O统计信息的汇总求和结果，如表1所示。 表1 SUMMARY_REL_IOSTAT字段 名称 类型 描述 phyrds numeric 读物理文件的数目。 phywrts numeric 写物理文件的数目。 phyblkrd numeric 读物理文件的块的数目。 phyblkwrt numeric 写物理文件的块的数目。 dbid oid 在 分布式数据库 中，当前该值始终为0。 父主题： File

GLOBAL_COMM_DELAY GLOBAL_COMM_DELAY视图展示所有DN的TCP代理通信库时延状态，如表1所示。 表1 GLOBAL_COMM_DELAY字段 名称 类型 描述 node_name text 节点名称。 remote_name text 连接对端节点名称。 remote_host text 连接对端IP地址。 stream_num integer 当前物理连接使用的stream逻辑连接数量。 min_delay integer 当前物理连接一分钟内探测到的最小时延（单位：微秒）。 说明： 负数结果无效，请重新等待时延状态更新后再执行。 average integer 当前物理连接一分钟内探测时延的平均值（单位：微秒）。 max_delay integer 当前物理连接一分钟内探测到的最大时延（单位：微秒）。 父主题： Comm

如何查看某张表创建时间？ 答：在系统视图PG_TABLES里created字段的取值为表的真实创建时间。 示例如下： --创建表。 gaussdb=# CREATE TABLE test(id int, name varchar(10)); --查询test表创建时间。 gaussdb=# SELECT tablename,created FROM pg_tables WHERE tablename = 'test'; tablename | created -----------+------------------------------- test | 2024-01-12 14:50:59.611988+08 (1 row) 父主题： FAQ

ODBC接口参考 ODBC接口是一套提供给用户的API函数，本节将对部分常用接口做具体描述，若涉及其他接口可参考msdn（网址：https://msdn.microsoft.com/en-us/library/windows/desktop/ms714177(v=vs.85).aspx）中ODBC Programmer's Reference项的相关内容。 SQLAllocEnv SQLAllocConnect SQLAllocHandle SQLAllocStmt SQLBindCol SQLBindParameter SQLColAttribute SQLConnect SQLDisconnect SQLExecDirect SQLExecute SQLFetch SQLFreeStmt SQLFreeConnect SQLFreeHandle SQLFreeEnv SQLPrepare SQLGetData SQLGetDiagRec SQLSetConnectAttr SQLSetEnvAttr SQLSetStmtAttr 父主题： 基于ODBC开发

pgxc_xacts_iscommitted() 描述：返回集群中指定事务xid的事务的状态。t代表committed；f代表aborted；null代表others。需要sysadmin或者monadmin权限执行。 返回值类型：set of record 示例： 1 2 3 4 5 6 7 8 gaussdb=# SELECT pgxc_xacts_iscommitted(1); pgxc_xacts_iscommitted -------------------- (dn_6004_6005_6006,t) (cn_5001,t) (cn_5002,t) (dn_6001_6002_6003,t) (4 row)

pv_session_memory_detail() 描述：返回会话的内存使用情况，以MemoryContext节点来统计。 返回值类型：record 表2 返回值说明 名称 类型 描述 sessid text 关闭线程池（enable_thread_pool = off）时该字段表示线程启动时间+session标识（字符串信息为timestamp.sessionid）。 开启线程池（enable_thread_pool = on）时，内存上下文是线程级别的，则对应的该字段表示线程启动时间+线程标识（字符串信息为timestamp.threadid），内存上下文是session级别的，则对应的该字段表示线程启动时间+session标识（字符串信息为timestamp.sessionid）。 threadid bigint 会话绑定的线程标识。 contextname text 内存上下文名称。 level smallint 当前上下文在整体内存上下文中的层级。 parent text 父内存上下文名称。 totalsize bigint 当前内存上下文的内存总数，单位Byte。 freesize bigint 当前内存上下文中已释放的内存总数，单位Byte。 usedsize bigint 当前内存上下文中已使用的内存总数，单位Byte；“TempSmallContextGroup”内存上下文中该字段含义为统计计数。

pgxc_total_memory_detail() 描述：显示集群内存使用情况。需要sysadmin或者monadmin权限执行。 若GUC参数enable_memory_limit=off，该函数不能使用。 返回值类型：set of pv_total_memory_detail 示例： 1 2 3 4 5 6 7 8 gaussdb=# SELECT pgxc_total_memory_detail(); pgxc_total_memory_detail -------------------- (dn_6004_6005_6006,max_process_memory,81920) (dn_6004_6005_6006,process_used_memory,72747) (dn_6004_6005_6006,max_dynamic_memory,12096) (dn_6004_6005_6006,dynamic_used_memory,1530) (4 row)

pv_total_memory_detail() 描述：统计当前数据库节点使用内存的信息，单位为MB。 若GUC参数enable_memory_limit=off，该函数不能使用。 返回值类型：record 表1 返回值说明 名称 类型 描述 nodename text 节点名称。 memorytype text 内存类型，包括以下几种： max_process_memory：GaussDB集群实例所占用的内存大小。 process_used_memory：GaussDB线程所使用的内存大小。 max_dynamic_memory：最大动态内存。 dynamic_used_memory：已使用的动态内存。 dynamic_peak_memory：内存的动态峰值。 dynamic_used_shrctx：最大动态共享内存上下文。 dynamic_peak_shrctx：共享内存上下文的动态峰值。 max_shared_memory：最大共享内存。 shared_used_memory：已使用的共享内存。 max_sctpcomm_memory：通信库所允许使用的最大内存。 sctpcomm_used_memory：通信库已使用的内存大小。 sctpcomm_peak_memory：通信库的内存峰值。 other_used_memory：其他已使用的内存大小。 memorymbytes integer 内存类型分配内存的大小。

pg_conf_load_time() 描述：配置加载时间。pg_conf_load_time返回最后加载服务器配置文件的时间戳。 返回值类型：timestamp with time zone 示例： 1 2 3 4 5 gaussdb=# SELECT pg_conf_load_time(); pg_conf_load_time ------------------------------ 2017-09-01 16:05:23.89868+08 (1 row)

session_context( 'namespace' , 'parameter') 描述：获取并返回指定namespace下参数parameter的值。 返回值类型：VARCHAR 示例： 1 2 3 4 5 gaussdb=# SELECT session_context('USERENV', 'CURRENT_SCHEMA'); session_context ------------- public (1 row) 根据当前所在的实际schema而变化。 备注：目前仅支持SESSION_CONTEXT('USERENV', 'CURRENT_SCHEMA') 和SESSION_CONTEXT('USERENV', 'CURRENT_USER')两种格式。

get_nodeinfo(text) 描述：根据检索的属性返回对应的节点信息的值，可检索属性目前包括node_name和node_type。 返回值类型：text 示例： 1 2 3 4 5 6 7 8 9 10 gaussdb=# SELECT get_nodeinfo('node_type'); get_nodeinfo -------------- DIS_CN (1 row) gaussdb=# SELECT get_nodeinfo('node_name'); get_nodeinfo -------------- coordinator1 (1 row)

pgxc_parse_clog(OUT xid int8, OUT nodename text, OUT status text) 描述：返回当前集群中普通表所有事务的状态。 返回值类型：set of record 示例： 1 2 3 4 5 6 7 gaussdb=# SELECT pgxc_parse_clog(); pgxc_parse_clog ---------------- (0,dn_6004_6005_6006,INPROGRESS) (1,dn_6004_6005_6006,COMMITTED) (2,dn_6004_6005_6006,INPROGRESS) (3 row)

pgxc_parse_clog(IN int2 bucketid, OUT xid int8, OUT nodename text, OUT status text) 描述：返回当前集群中指定bucketid的所有事务的状态，入参是hash bucket表bucketid，取值范围[-1,1023]，普通表取值-1。 返回值类型：set of record 示例： 1 2 3 4 5 6 7 gaussdb=# SELECT pgxc_parse_clog('-1'); pgxc_parse_clog ---------------- (0,dn_6004_6005_6006,INPROGRESS) (1,dn_6004_6005_6006,COMMITTED) (2,dn_6004_6005_6006,INPROGRESS) (3 row)

pg_my_temp_schema() 描述：会话的临时模式的OID，不存在则为0。 返回值类型：oid 示例： 1 2 3 4 5 gaussdb=# SELECT pg_my_temp_schema(); pg_my_temp_schema ------------------- 0 (1 row) 备注：pg_my_temp_schema返回当前会话中临时模式的OID，如果不存在（没有创建临时表）的话则返回0。如果给定的OID是其它会话中临时模式的OID，pg_is_other_temp_schema则返回true。

sessionid2pid() 描述：从sessionid中得到pid信息（如: pv_session_stat中sessid列）。 返回值类型：int8 示例： 1 2 3 4 5 6 gaussdb=# select sessionid2pid(sessid::cstring) from pv_session_stat limit 2; sessionid2pid ----------------- 139973107902208 139973107902208 (2 rows)

version() 描述：版本信息。version返回一个描述服务器版本信息的字符串。 返回值类型：text 示例： 1 2 3 4 5 gaussdb=# SELECT version(); version ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- gaussdb (GaussDB XXX.XXX.XXX build f521c606) compiled at 2021-09-16 14:55:22 commit 2935 last mr 6385 release (1 row)