gbase数据、南大通用产品文档：GBase8s环境、连接和语句句柄

当应用程序请求它时，驱动程序和驱动程序管理器为关于环境、每一连接和每一 SQL 语
句的信息分配存储。
对于这些分配，驱动程序为每一应用程序返回一个句柄，在每一函数调用中，其使用一个
或多个句柄。
GBase 8s ODBC Driver API 使用下列句柄类型：
环境句柄
环境句柄为全局信息标识内存存储，包括有效的连接句柄和当前活动的连接句柄。
环境句柄为 henv 变量类型。一个应用程序使用一个环境句柄。在它连接至数据源
之前，它必须请求此句柄。
连接句柄
连接句柄为关于特殊连接的信息标识内存存储。连接句柄为 hdbc变量类型。应用
程序必须在连接至数据源之前，必须请求连接句柄。每个连接句柄都与环境句柄相
关联。但是，环境句柄可以与多个连接句柄相关联。
语句句柄
语句句柄为关于 SQL 语句的信息标识内存存储。语句句柄为 hstmt 变量类型。在

GBase 8s ODBC Driver 程序员指南
南大通用数据技术股份有限公司
- 14 -
应用程序提交 SQL 请求之前，它必须请求一语句句柄。每一语句句柄仅与一个连
接句柄相关联。但是，每一连接句柄可与多个语句句柄相关联。


format_type(type_oid, typemod)
描述：获取数据类型的SQL 名称。
返回类型：text
备注：format_type 通过某个数据类型的类型OID 以及可能的类型修饰词，返回其SQL
名称。如果不知道具体的修饰词，则在类型修饰词的位置传入NULL。类型修饰词一般只对
有长度限制的数据类型有意义。format_type 所返回的SQL 名称中包含数据类型的长度值，
其大小是：实际存储长度len - sizeof(int32)，单位字节。原因是数据存储时需要32 位的空间
来存储用户对数据类型的自定义长度信息，即实际存储长度要比用户定义长度多4 个字节。
在下例中，format_type 返回的SQL 名称为“character varying(6)”，6 表示varchar 类型的长度
值是6 字节，因此该类型的实际存储长度为10 字节。
gbase=# SELECT format_type((SELECT oid FROM pg_type WHERE typname='varchar'),
10);
format_type
----------------------
character varying(6)
(1 row)

getdistributekey(table_name)
描述：获取一个hash 表的分布列。单机环境下不支持分布，该函数返回为空。

pg_check_authid(role_oid)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
415
描述：检查是否存在给定oid 的角色名。
返回类型：bool
示例：
gbase=# select pg_check_authid(1);
pg_check_authid
-----------------
f
(1 row)

pg_describe_object(catalog_id, object_id, object_sub_id)
描述：获取数据库对象的描述。
返回类型：text
备注：pg_describe_object 返回由目录OID，对象OID 和一个（或许0 个）子对象ID 指
定的数据库对象的描述。这有助于确认存储在pg_depend 系统表中对象的身份。

pg_get_constraintdef(constraint_oid)
描述：获取约束的定义。
返回类型：text

pg_get_constraintdef(constraint_oid, pretty_bool)
描述：获取约束的定义。
返回类型：text
备注：
pg_get_constraintdef 和pg_get_indexdef 分别从约束或索引上使用创建命令进行重
构。

pg_get_expr(pg_node_tree, relation_oid)
描述：反编译表达式的内部形式，假设其中的任何Vars 都引用第二个参数指定的关系。
返回类型：text

pg_get_expr(pg_node_tree, relation_oid, pretty_bool)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
416
描述：反编译表达式的内部形式，假设其中的任何Vars 都引用第二个参数指定的关系。
返回类型：text
备注：pg_get_expr 反编译一个独立表达式的内部形式，比如一个字段的缺省值。在检
查系统表的内容的时候很有用。如果表达式可能包含关键字，则指定他们引用相关的OID
作为第二个参数；如果没有关键字，零就足够了。

pg_get_functiondef(func_oid)
描述：获取函数的定义。
返回类型：text
示例：
gbase=# select * from pg_get_functiondef(598);
headerlines |
definition
-------------+----------------------------------------------------
4 | CREATE OR REPLACE FUNCTION pg_catalog.abbrev(inet)+
|
RETURNS text
+
|
LANGUAGE internal
+
|
IMMUTABLE STRICT NOT FENCED NOT SHIPPABLE
+
| AS $function$inet_abbrev$function$;
+
|
(1 row)

pg_get_function_arguments(func_oid)
描述：获取函数定义的参数列表（带默认值）
。
返回类型：text
备注：
pg_get_function_arguments返回一个函数的参数列表，
需要在CREATE FUNCTION
中使用这种格式。

pg_get_function_identity_arguments(func_oid)
描述：获取参数列表来确定一个函数（不带默认值）
。
返回类型：text

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
417
备注：
pg_get_function_identity_arguments 返回需要的参数列表用来标识函数，
这种形式
需要在ALTER FUNCTION 中使用，并且这种形式省略了默认值。

pg_get_function_result(func_oid)
描述：获取函数的RETURNS 子句。
返回类型：text
备注：pg_get_function_result 为函数返回适当的RETURNS 子句。

pg_get_indexdef(index_oid)
描述：获取索引的CREATE INDEX 命令。
返回类型：text
示例：
gbase=# select * from pg_get_indexdef(16416);
pg_get_indexdef
-------------------------------------------------------------------------
CREATE INDEX test3_b_idx ON test3 USING btree (b) TABLESPACE pg_default
(1 row)

pg_get_indexdef(index_oid, dump_schema_only)
描述：获取索引的CREATE INDEX 命令，仅用于dump 场景。对于包含local 索引的间
隔分区表，当dump_schema_only 为true 时，返回的创建索引语句中不包含自动创建的分区
的local 索引信息；当dump_schema_only 为false 时，返回的创建索引语句中包含自动创建
的分区的local 索引信息。对于非间隔分区表或者不包含local 索引的间隔分区分区表，
dump_schema_only 参数取值不影响函数返回结果。
返回类型：text
示例：
gbase=# CREATE TABLE sales
gbase-# (prod_id NUMBER(6),
gbase(#
cust_id NUMBER,
gbase(#
time_id DATE,

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
418
gbase (#
channel_id CHAR(1),
gbase (#
promo_id NUMBER(6),
gbase (#
quantity_sold NUMBER(3),
gbase (#
amount_sold NUMBER(10,2)
gbase (# )
gbase-# PARTITION BY RANGE( time_id) INTERVAL('1 day')
gbase -# (
gbase (# partition p1 VALUES LESS THAN ('2019-02-01 00:00:00'),
gbase (# partition p2 VALUES LESS THAN ('2019-02-02 00:00:00')
gbase (# );
CREATE TABLE
gbase=# create index index_sales on sales(prod_id) local (PARTITION
idx_p1 ,PARTITION idx_p2);
CREATE INDEX
-- 插入数据没有匹配的分区，新创建一个分区，并将数据插入该分区
gbase=# INSERT INTO sales VALUES(1, 12, '2019-02-05 00:00:00', 'a', 1, 1, 1);
INSERT 0 1
gbase=# select oid from pg_class where relname = 'index_sales';
oid
-------
16636
(1 row)
gbase=# select * from pg_get_indexdef(16636, true);
pg_get_indexdef
-----------------------------------------------------------------------------
-------------------------------------------------------------------------
CREATE INDEX index_sales ON sales USING ubtree (prod_id) LOCAL(PARTITION idx_p1,
PARTITION idx_p2)
WITH (storage_type=USTORE) TABLESPACE pg_default
(1 row)
gbase=# select * from pg_get_indexdef(16636, false);
pg_get_indexdef
------------------------------------------------------------------
------------------------------------------------------------------
------------------------------------------------
CREATE INDEX index_sales ON sales USING ubtree (prod_id) LOCAL(PA
RTITION idx_p1, PARTITION idx_p2, PARTITION sys_p1_prod_id_idx)
W
ITH (storage_type=USTORE) TABLESPACE pg_default
(1 row)

pg_get_indexdef(index_oid, column_no, pretty_bool)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
419
描述：获取索引的CREATE INDEX 命令，或者如果column_no 不为零，则只获取一个
索引字段的定义。
示例：
gbase=# select * from pg_get_indexdef(16416, 0, false);
pg_get_indexdef
-------------------------------------------------------------------------
CREATE INDEX test3_b_idx ON test3 USING btree (b) TABLESPACE pg_default
(1 row)
gbase=# select * from pg_get_indexdef(16416, 1, false);
pg_get_indexdef
-----------------
b
(1 row)
返回类型：text
备注：
pg_get_functiondef 为函数返回一个完整的CREATE OR REPLACE FUNCTION 语
句。

pg_get_keywords()
描述：获取SQL 关键字和类别列表。
返回类型：setof record
备注：
pg_get_keywords 返回一组关于描述服务器识别SQL 关键字的记录。
word 列包含
关键字。catcode 列包含一个分类代码：U 表示通用的，C 表示列名，T 表示类型或函数名，
或R 表示保留。catdesc 列包含了一个可能本地化描述分类的字符串。

pg_get_userbyid(role_oid)
描述：获取给定OID 的角色名。
返回类型：name
备注：pg_get_userbyid 通过角色的OID 抽取对应的用户名。

pg_check_authid(role_id)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
420
描述：通过role_id 检查用户是否存在。
返回类型：text
示例：
gbase=# select pg_check_authid(20);
pg_check_authid
-----------------
f
(1 row)

pg_get_viewdef(view_name)
描述：为视图获取底层的SELECT 命令。
返回类型：text

pg_get_viewdef(view_name, pretty_bool)
描述：为视图获取底层的SELECT 命令，如果pretty_bool 为true，行字段可以包含80
列。
返回类型：text
备注：
pg_get_viewdef 重构出定义视图的SELECT 查询。
这些函数大多数都有两种形式，
其中带有pretty_bool 参数，且参数为true 时，是”适合打印”的结果，这种格式更容易读。另
一种是缺省的格式，更有可能被将来的不同版本用同样的方法解释。
如果是用于转储，
那么
尽可能避免使用适合打印的格式。给pretty-print 参数传递false 生成的结果和没有这个参数
的变种生成的结果是完全一样。

pg_get_viewdef(view_oid)
描述：为视图获取底层的SELECT 命令。
返回类型：text

pg_get_viewdef(view_oid, pretty_bool)
描述：为视图获取底层的SELECT 命令，如果pretty_bool 为true，行字段可以包含80
列。

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
421
返回类型：text

pg_get_viewdef(view_oid, wrap_column_int)
描述：为视图获取底层的SELECT 命令；行字段被换到指定的列数，打印是隐含的。
返回类型：text

pg_get_tabledef(table_oid)
描述：根据table_oid 获取表定义
示例：
gbase=# select * from pg_get_tabledef(16384);
pg_get_tabledef
-------------------------------------------------------
SET search_path = public;
+
CREATE
TABLE t1 (
+
c1 bigint DEFAULT nextval('serial'::regclass)+
)
+
WITH (orientation=row, compression=no)
+
TO GROUP group1;
(1 row)
返回类型：text

pg_get_tabledef(table_name)
描述：根据table_name 获取表定义。
示例：
gbase=# select * from pg_get_tabledef('classes');
pg_get_tabledef
--------------------------------------------------------------
SET search_path = public;
+
CREATE TABLE classes (
+
name character varying,
+
score bigint
+
)
+
WITH (orientation=row, compression=no, storage_type=USTORE);
(1 row)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
422
返回类型：text
备注：pg_get_tabledef 重构出表定义的CREATE 语句，包含了表定义本身、索引信息、
comments 信息。对于表对象依赖的group、schema、tablespace、server 等信息，需要用户自
己去创建，表定义里不会有这些对象的创建语句。

pg_options_to_table(reloptions)
描述：获取存储选项名称/值对的集合。
返回类型：setof record
备注：pg_options_to_table 当通过pg_class.reloptions 或pg_attribute.attoptions 时返回存
储选项名称/值对（option_name/option_value）的集合。

pg_tablespace_databases(tablespace_oid)
描述：获取在指定的表空间中有对象的数据库OID 集合。
返回类型：setof oid
备注：pg_tablespace_databases 允许检查表空间的状况，返回在该表空间中保存了对象
的数据库OID 集合。如果这个函数返回数据行，则该表空间就是非空的，因此不能删除。
要显示该表空间中的特定对象，用户需要连接pg_tablespace_databases 标识的数据库与查询
pg_class 系统表。

pg_tablespace_location(tablespace_oid)
描述：获取表空间所在的文件系统的路径。
返回类型：text

pg_typeof(any)
描述：获取任何值的数据类型。
返回类型：regtype
备注：pg_typeof 返回传递给他的值的数据类型OID。这可能有助于故障排除或动态构
造SQL 查询。声明此函数返回regtype，这是一个OID 别名类型（请参考对象标识符类型）
；

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
423
这意味着它是一个为了比较而显示类型名称的OID。
示例：
gbase=# SELECT pg_typeof(33);
pg_typeof
-----------
integer
(1 row)
gbase=# SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
typlen
--------
4
(1 row)

collation for (any)
描述：获取参数的排序。
返回类型：text
备注：表达式collation for 返回传递给他的值的排序。
示例：
gbase=# SELECT collation for (description) FROM pg_description LIMIT 1;
pg_collation_for
------------------
"default"
(1 row)
值可能是引号括起来的并且模式限制的。如果没有为参数表达式排序，则返回一个null
值。如果参数不是排序的类型，则抛出一个错误。

pg_extension_update_paths(name)
描述：返回指定扩展的版本更新路径。
返回类型：text(source text), text(path text), text(target text)

pg_get_serial_sequence(tablename, colname)

GBase 8c SQL 参考手册
南大通用数据技术股份有限公司
424
描述：获取对应表名和列名上的序列。
返回类型：text
示例：
gbase=# select * from pg_get_serial_sequence('t1', 'c1');
pg_get_serial_sequence
------------------------
public.serial
(1 row)

pg_sequence_parameters(sequence_oid)
描述：获取指定sequence 的参数，包含起始值，最小值和最大值，递增值等。
返回类型：int16, int16,int16, bigint, Boolean
示例：
gbase=# select * from pg_sequence_parameters(16420);
start_value | minimum_value |
maximum_value
| increment | cycle_option
-------------+---------------+---------------------+-----------+-------------
101 |
1 | 9223372036854775807 |
1 | f
(1 row)

当您为数据库空间、BLOB 空间或智能大对象空间中的每个主块创建镜像块后，镜像开
始。
当您创建镜像块，数据库服务器就将数据从主块复制到镜像块。 当该过程完成，数据库
服务器开始镜像数据。 如果主块包含逻辑日志文件，数据库服务器不会在您创建镜像块
后立即复制数据，而是一直等待，直至您执行 0 级备份。有关此行为的说明，请参阅创
建镜像块。

GBase 8s 管理员指南
南大通用数据技术股份有限公司
- 327 -
重要： 您必须始终启动对整个数据库空间、BLOB 空间或智能大对象空间的镜像过程。
数据库服务器不允许您在数据库空间、BLOB 空间或智能大对象空间中选择特定块来镜
像。您必须为空间中的每个块创建镜像块。
在执行以下操作后，启动对存储空间的镜像过程：
•
在系统初始化期间创建镜像根数据库空间
•
将数据库空间的状态从未镜像更改为已镜像
•
创建镜像的数据库空间、BLOB 空间或智能大对象空间
这些操作中的每一个操作均需要您为存储空间中的现有块创建镜像块。
初始化期间为根数据库空间制作镜像
如果您在初始化数据库服务器时启用镜像，您还可为 Root 块指定镜像路径名和偏移量。
数据库服务器在初始化服务器时创建镜像块。但因为 Root 块包含逻辑日志文件，所以直
至您执行 0 级备份镜像才会实际开始。
要指定 Root 镜像路径名和偏移量，请在启动数据库服务器之前在 onconfig 文件中设置
MIRRORPATH 和 MIRROROFFSET 的值。
如果未提供镜像路径名和偏移量，但希望为根数据库空间启动镜像过程，那么必须在初始
化数据库服务器后更改根数据库空间的镜像状态。
更改镜像状态
您可以进行以下两种对镜像块状态的更改：
•
将镜像块从联机更改为脱机
•
将镜像块从脱机更改为恢复
仅当块是镜像对的一部分时才可以使块脱机或复原块。只要该对中的另一块处于联机状
态，您就可以使主块或镜像块脱机。
有关如何确定块状态的信息，请参阅监视磁盘使用量。