KingbaseES插件参考手册.pdf

KingbaseES 插件参考手册 金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024） 发布日期：2023 年 10 月 12 日 北京人大金仓信息技术股份有限公司 目 目 录 录 第 1 章 前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 扩展插件概述 3 第 3 章 amcheck 9 3.1 插件 amcheck 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2 插件 amcheck 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.3 插件 amcheck 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.4 插件 amcheck 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.5 插件 amcheck 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.6 插件 amcheck 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 第 4 章 auth_delay 12 4.1 插件 auth_delay 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.2 插件 auth_delay 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.3 插件 auth_delay 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.4 插件 auth_delay 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.5 插件 auth_delay 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.6 插件 auth_delay 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 第 5 章 auto_bmr 14 5.1 插件 auto_bmr 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.2 插件 auto_bmr 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.3 插件 auto_bmr 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.4 插件 auto_bmr 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5.5 插件 auto_bmr 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.6 插件 auto_bmr 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 I 目 第 6 章 auto_explain 录 17 6.1 插件 auto_explain 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 6.2 插件 auto_explain 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 6.3 插件 auto_explain 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 6.4 插件 auto_explain 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 6.5 插件 auto_explain 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 6.6 插件 auto_explain 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 第 7 章 backtrace 20 7.1 插件 backtrace 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.2 插件 backtrace 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.3 插件 backtrace 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.4 插件 backtrace 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.5 插件 backtrace 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.6 插件 backtrace 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 第 8 章 backup_pri 22 8.1 插件 backup_pri 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.2 插件 backup_pri 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.3 插件 backup_pri 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 8.4 插件 backup_pri 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.4.1 备份恢复权限的授予与回收 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.4.2 备份恢复权限流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 8.4.3 相关系统视图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 8.5 插件 backup_pri 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 8.6 插件 backup_pri 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 第 9 章 bloom 27 9.1 插件 bloom 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9.2 插件 bloom 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9.3 插件 bloom 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9.4 插件 bloom 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 9.5 插件 bloom 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 9.6 插件 bloom 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 第 10 章 citext 29 10.1 插件 citext 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.2 插件 citext 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.3 插件 citext 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.4 插件 citext 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.4.1 regexp_matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.4.2 citext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 10.4.3 citext_eq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 II 目 录 10.4.4 citext_ne(citext, citext) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 10.4.5 citext_hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 10.4.6 支持两个 citext 类型 �,�,>,<, ＝,!= 等操作符的操作 . . . . . . . . . . . . . . . . . . . . . . . . 32 10.5 插件 citext 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 10.6 插件 citext 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 第 11 章 cstore_fdw 34 11.1 插件 cstore_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 11.2 插件 cstore_fdw 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 11.3 插件 cstore_fdw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 11.4 插件 cstore_fdw 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 11.4.1 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 11.4.2 升级 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 11.5 插件 cstore_fdw 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 11.6 插件 cstore_fdw 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 第 12 章 cube 39 12.1 插件 cube 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 12.2 插件 cube 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 12.3 插件 cube 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 12.4 插件 cube 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 12.4.1 外部表示 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 12.4.2 精度 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 12.4.3 操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 12.4.4 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 12.4.5 默认值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 12.5 插件 cube 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 12.6 插件 cube 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 第 13 章 dblink 46 13.1 插件 dblink 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 13.2 插件 dblink 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 13.3 插件 dblink 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 13.4 插件 dblink 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 13.4.1 dblink_connect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 13.4.2 dblink_connect_u . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 13.4.3 dblink_disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 13.4.4 dblink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 13.4.5 dblink_exec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 13.4.6 dblink_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 13.4.7 dblink_fetch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 13.4.8 dblink_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 13.4.9 dblink_get_connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 III 目 录 13.4.10 dblink_error_message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 13.4.11 dblink_send_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 13.4.12 dblink_is_busy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 13.4.13 dblink_get_notify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 13.4.14 dblink_get_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 13.4.15 dblink_cancel_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 13.4.16 dblink_get_pkey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 13.4.17 dblink_build_sql_insert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 13.4.18 dblink_build_sql_delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 13.4.19 dblink_build_sql_update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 13.5 插件 dblink 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 13.6 插件 dblink 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 第 14 章 dbms_ddl 70 14.1 插件 dbms_ddl 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 14.2 插件 dbms_ddl 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 14.3 插件 dbms_ddl 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 14.4 插件 dbms_ddl 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 14.4.1 DBMS_DDL.WRAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 14.4.2 DBMS_DDL.CREATE_WRAPPED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 14.5 插件 dbms_ddl 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 14.6 插件 dbms_ddl 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 第 15 章 dbms_lob 74 15.1 插件 dbms_lob 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 15.2 插件 dbms_lob 的加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 15.3 插件 dbms_lob 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 15.4 插件 dbms_lob 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 15.4.1 dbms_lob.createtemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 15.4.2 dbms_lob.istemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 15.4.3 dbms_lob.freetemporary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 15.4.4 dbms_lob.append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 15.4.5 dbms_lob.substr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 15.4.6 dbms_lob.writeappend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 15.4.7 dbms_lob.instr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 15.4.8 dbms_lob.compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 15.4.9 dbms_lob.getlength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 15.4.10 dbms_lob.trim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 15.4.11 dbms_lob.erase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 15.4.12 dbms_lob.copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 15.5 dbms_lob.read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.6 插件 dbms_lob 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 15.7 插件 dbms_lob 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 IV 目 第 16 章 dbms_metadata 录 88 16.1 插件 dbms_metadata 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.2 插件 dbms_metadata 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.3 插件 dbms_metadata 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.4 插件 dbms_metadata 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.4.1 DBMS_METADATA.GET_DDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.5 插件 dbms_metadata 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 16.6 插件 dbms_metadata 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 第 17 章 dbms_mview 92 17.1 插件 dbms_mview 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.2 插件 dbms_mview 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.3 插件 dbms_mview 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.3.1 REFRESH 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.4 插件 dbms_mview 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 17.5 插件 dbms_mview 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 第 18 章 dbms_obfuscation_toolkit 94 18.1 插件 dbms_obfuscation_toolkit 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 18.2 插件 dbms_obfuscation_toolkit 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 18.3 插件 dbms_obfuscation_toolkit 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 18.4 插件 dbms_obfuscation_toolkit 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 18.4.1 限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 18.4.2 启用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 18.4.3 禁用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 18.4.4 DBMS_OBFUSCATION_TOOLKIT 系统包子函数接口 . . . . . . . . . . . . . . . . . . . . . 95 18.4.4.1 DES3ENCRYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 18.4.4.2 DES3DECRYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 18.4.4.3 DESENCRYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 18.4.4.4 DESDECRYPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 18.4.4.5 MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 18.5 插件 dbms_obfuscation_toolkit 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 18.6 插件 dbms_obfuscation_toolkit 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 第 19 章 dbms_output 100 19.1 插件 dbms_output 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 19.2 插件 dbms_output 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 19.3 插件 dbms_output 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 19.4 插件 dbms_output 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 19.4.1 限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 19.4.2 启用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 19.4.3 禁用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 19.4.4 DBMS_OUTPUT 系统包支持向缓冲区输入信息 . . . . . . . . . . . . . . . . . . . . . . . . . . 102 V 目 录 19.4.4.1 向缓冲区中追加内容 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 19.4.4.2 向缓冲区追加单行信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 19.4.4.3 向缓冲区追加新行 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 19.4.5 DBMS_OUTPUT 系统包支持从缓冲区中获取信息 . . . . . . . . . . . . . . . . . . . . . . . . . 104 19.4.5.1 获取首行信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 19.4.5.2 获取多行信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 19.4.6 DBMS_OUTPUT 系统包支持客户端显示缓冲区信息 . . . . . . . . . . . . . . . . . . . . . . . 106 19.4.6.1 客户端命令启动输出功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 19.4.6.2 客户端命令禁用输出功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 19.5 插件 dbms_output 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 19.6 插件 dbms_output 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 第 20 章 dbms_random 109 20.1 插件 dbms_random 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 20.2 插件 dbms_random 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 20.3 插件 dbms_random 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 20.4 插件 dbms_random 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 20.4.1 INITIALIZE Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 20.4.2 NORMAL Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 20.4.3 RANDOM Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 20.4.4 SEED Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 20.4.5 STRING Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 20.4.6 TERMINATE Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 20.4.7 VALUE Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 20.5 插件 dbms_random 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 20.6 插件 dbms_random 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 第 21 章 dbms_session 116 21.1 插件 dbms_session 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 21.2 插件 dbms_session 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 21.3 插件 dbms_session 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 21.4 插件 dbms_session 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 21.4.1 DBMS_SESSION 系统包子程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 21.4.2 CLEAR_ALL_CONTEXT 过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 21.4.3 CLEAR_CONTEXT 过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 21.4.4 LIST_CONTEXT 过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 21.4.5 SET_CONTEXT 过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 21.5 插件 dbms_session 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 21.6 插件 dbms_session 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 第 22 章 dbms_sql 124 22.1 插件 dbms_sql 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 22.2 插件 dbms_sql 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 VI 目 录 22.3 插件 dbms_sql 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 22.4 插件 dbms_sql 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 22.4.1 DBMS_SQL 包预定义类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 22.4.1.1 DBMS_SQL 常量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 22.4.1.2 DBMS_SQL 集合类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 22.4.2 DBMS_SQL 包子程序 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 22.4.2.1 打开新游标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 22.4.2.2 解析语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 22.4.2.3 绑定变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 22.4.2.3.1 绑定到游标的基本数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 22.4.2.3.2 绑定到游标的 CHAR 类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 22.4.2.3.3 绑定到游标的关联数组类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 22.4.2.3.4 绑定到游标的包中类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 22.4.2.4 定义类型接收列值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 22.4.2.4.1 定义基本数据类型接收单行列值 . . . . . . . . . . . . . . . . . . . . . . . . . 138 22.4.2.4.2 定义 CHAR 类型接收单行列值 . . . . . . . . . . . . . . . . . . . . . . . . . . 140 22.4.2.4.3 定义关联数组类型接收单行列值 . . . . . . . . . . . . . . . . . . . . . . . . . 142 22.4.2.5 执行游标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 22.4.2.6 检索游标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 22.4.2.7 执行游标，并检索游标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 22.4.2.8 返回游标中指定类型列值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 22.4.2.8.1 返回游标基础数据类型的列值 . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 22.4.2.8.2 返回游标关联数组类型的列值 . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 22.4.2.8.3 返回游标 CHAR 类型的列值 . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 22.4.2.9 返回游标中给定变量的值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 22.4.2.9.1 返回游标基础数据类型的变量值 . . . . . . . . . . . . . . . . . . . . . . . . . 150 22.4.2.9.2 返回游标关联数组类型的变量值 . . . . . . . . . . . . . . . . . . . . . . . . . 152 22.4.2.9.3 返回游标 CHAR 类型的变量值 . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.4.2.9.4 返回游标包中类型的变量值 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.4.2.10 获取查询项的描述信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 22.4.2.10.1 获取查询项的描述信息，为 DESC_TAB 类型 . . . . . . . . . . . . . . . . . 154 22.4.2.11 关闭游标 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 22.4.2.12 判断游标是否打开 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 22.4.2.13 返回累计检索出来的行的数量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 22.4.2.14 游标转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 22.4.2.14.1 将游标变量转换为 DBMS_SQL 包内部游标 . . . . . . . . . . . . . . . . . . 159 22.4.2.14.2 将 DBMS_SQL 包内的游标转换为本地动态 SQL 游标 . . . . . . . . . . . . 160 22.4.2.15 返回语句结果集 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 22.4.2.16 接收 RETURN_RESULT 过程的一个返回结果，并返回给客户端应用程序 . . . . . . 163 22.4.2.17 返回 SQL 语句错误发生处的字节偏移量 . . . . . . . . . . . . . . . . . . . . . . . . . 166 22.4.2.18 返回该语句的 SQL 函数代码 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 22.4.2.19 其他示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 VII 目 录 22.5 插件 dbms_sql 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 22.6 插件 dbms_sql 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 第 23 章 dbms_utility 173 23.1 插件 dbms_utility 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 23.2 插件 dbms_utility 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 23.3 插件 dbms_utility 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 23.4 插件 dbms_utility 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 23.4.1 FORMAT_CALL_STACK 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 23.4.2 FORMAT_ERROR_BACKTRACE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 23.4.3 FORMAT_ERROR_STACK 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 23.4.4 GET_TIME 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 23.4.5 GET_HASH_VALUE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 23.5 插件 dbms_utility 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 23.6 插件 dbms_utility 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 第 24 章 dict_int 181 24.1 插件 dict_int 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 24.2 插件 dict_int 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 24.3 插件 dict_int 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 24.4 插件 dict_int 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 24.5 插件 dict_int 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 24.6 插件 dict_int 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 第 25 章 dict_xsyn 183 25.1 插件 dict_xsyn 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 25.2 插件 dict_xsyn 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 25.3 插件 dict_xsyn 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 25.4 插件 dict_xsyn 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 25.5 插件 dict_xsyn 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 25.6 插件 dict_xsyn 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 第 26 章 earthdistance 186 26.1 插件 earthdistance 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 26.2 插件 earthdistance 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 26.3 插件 earthdistance 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 26.4 插件 citext 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 26.4.1 geo_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 26.4.2 earth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 26.4.3 sec_to_gc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 26.4.4 gc_to_sec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 26.4.5 ll_to_earth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 26.4.6 latitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 VIII 目 录 26.4.7 longitude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 26.4.8 earth_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 26.4.9 earth_box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 26.4.10 geo_distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 26.5 插件 earthdistance 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 26.6 插件 earthdistance 升级方法:= . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 第 27 章 file_fdw 199 27.1 插件 file_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 27.2 插件 file_fdw 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 27.3 插件 file_fdw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 27.4 插件 file_fdw 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 27.5 插件 file_fdw 卸载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 27.6 插件 file_fdw 升级方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 第 28 章 fix_security_hole 203 28.1 插件 fix_security_hole 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 28.2 插件 fix_security_hole 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 28.3 插件 fix_security_hole 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 28.4 插件 fix_security_hole 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 28.5 插件 fix_security_hole 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 28.6 插件 fix_security_hole 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 第 29 章 ftutilx 205 29.1 插件 ftutilx 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 29.2 插件 ftutilx 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 29.3 插件 ftutilx 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 29.4 插件 ftutilx 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 29.4.1 使用 ftutilx 全文检索的联合使用方案 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 29.4.2 注意事项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 29.5 插件 ftutilx 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 29.6 插件 ftutilx 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 第 30 章 fuzzystrmatch 208 30.1 插件 fuzzystrmatch 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.2 插件 fuzzystrmatch 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.3 插件 fuzzystrmatch 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.4 插件 fuzzystrmatch 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.4.1 levenshtein . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 30.4.2 levenshtein_with_costs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 30.4.3 levenshtein_less_equal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 30.4.4 levenshtein_less_equal_with_costs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 30.4.5 metaphone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 IX 目 录 30.4.6 soundex, text_soundex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 30.4.7 difference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 30.4.8 dmetaphone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 30.5 插件 fuzzystrmatch 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 30.6 插件 fuzzystrmatch 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 第 31 章 hstore 214 31.1 插件 hstore 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 31.2 插件 hstore 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 31.3 插件 hstore 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 31.4 插件 hstore 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 31.4.1 hstore 类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 31.4.2 hstore_to_jsonb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 31.4.3 hstore_to_json . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 31.5 插件 hstore 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 31.6 插件 hstore 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 第 32 章 http 222 32.1 插件 http 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 32.2 插件 http 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 32.3 插件 http 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 32.3.1 http.keepalive 变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 32.3.2 http.timeout_msec 变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 32.4 插件 http 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 32.4.1 数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 32.4.1.1 UTL_HTTP.req . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 32.4.1.2 UTL_HTTP.resp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 32.4.1.3 http_method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 32.4.1.4 http_header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 32.4.1.5 http_response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 32.4.1.6 http_request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 32.4.2 UTL_HTTP.BEGIN_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 32.4.3 UTL_HTTP.SET_HEADER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 32.4.4 UTL_HTTP.GET_RESPONSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 32.4.5 UTL_HTTP.READ_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 32.4.6 UTL_HTTP.READ_TEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 32.4.7 UTL_HTTP.END_RESPONSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 32.4.8 UTL_HTTP.END_REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 32.4.9 http_header 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 32.4.10 http 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 32.4.11 http_get 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 32.4.12 http_post 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 32.4.13 http_put 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 X 目 录 32.4.14 http_patch 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 32.4.15 http_delete 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 32.4.16 http_head 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 32.4.17 http_set_curlopt 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 32.4.18 http_reset_curlopt 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 32.4.19 http_list_curlopt 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 32.4.20 urlencode 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 32.5 插件 http 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 32.6 插件 http 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 第 33 章 identity_pwdexp 240 33.1 插件 identity_pwdexp 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 33.2 插件 identity_pwdexp 加载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 33.3 插件 identity_pwdexp 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 33.3.1 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 33.4 插件 identity_pwdexp 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 33.5 插件 identity_pwdexp 的卸载插件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 33.6 插件 identity_pwdexp 升级方法 第 34 章 intagg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 244 34.1 插件 intagg 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 34.2 插件 intagg 加载方式: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 34.3 插件 intagg 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 34.4 插件 intagg 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 34.4.1 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 34.5 插件 intagg 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 34.6 插件 intagg 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 第 35 章 intarray 247 35.1 插件 intarray 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 35.2 插件 intarray 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 35.3 插件 intarray 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 35.4 插件 intarray 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 35.4.1 icount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 35.4.2 sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 35.4.3 sort_asc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 35.4.4 sort_desc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 35.4.5 uniq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 35.4.6 idx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 35.4.7 subarray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 35.4.8 intset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 35.4.9 intarray 模块中支持的操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 35.5 插件 intarray 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 XI 目 录 35.6 插件 intarray 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 第 36 章 isn 252 36.1 插件 isn 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 36.2 插件 isn 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 36.3 插件 isn 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 36.4 插件 isn 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 36.4.1 数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 36.4.2 造型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 36.4.3 函数和操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 36.4.4 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 36.5 插件 isn 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 36.6 插件 isn 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 第 37 章 kbcrypto 256 37.1 插件 kbcrypto 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 37.2 插件 kbcrypto 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 37.3 插件 kbcrypto 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 37.4 插件 kbcrypto 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 37.4.1 sm3 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 37.4.1.1 sm3 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 37.4.2 sm4 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 37.4.2.1 sm4 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 37.4.2.2 sm4_ex 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 37.4.3 rc4 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 37.4.3.1 rc4 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 37.4.4 sm2 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 37.4.4.1 sm2_genkeypair 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 37.4.4.2 sm2_encrypt 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 37.4.4.3 sm2_decrypt 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 37.4.4.4 sm2_sign 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 37.4.4.5 sm2_verify 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 37.5 插件 kbcrypto 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 37.6 插件 kbcrypto 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 第 38 章 kbrowlocks 263 38.1 插件 kbrowlocks 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 38.2 插件 kbrowlocks 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 38.3 插件 kbrowlocks 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 38.4 插件 kbrowlocks 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 38.5 插件 kbrowlocks 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 38.6 插件 kbrowlocks 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 XII 目 第 39 章 kbstattuple 录 266 39.1 插件 kbstattuple 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 39.2 插件 kbstattuple 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 39.3 插件 kbstattuple 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 39.4 插件 kbstattuple 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 39.5 插件 kbstattuple 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 39.6 插件 kbstattuple 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 第 40 章 kdb_database_link 270 40.1 插件 Database Link 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270 40.1.1 Database Link 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 40.2 插件 kdb_database_link 的加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 40.3 插件 kdb_database_link 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 40.4 插件 kdb_database_link 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 40.4.1 创建 Database Link 对象 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 40.4.2 修改 Database Link 对象 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 40.4.3 删除 Database Link 对象 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 40.4.4 Database Link 的权限控制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 40.4.5 DBLink 相关的视图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 40.4.6 DATABASE LINK DML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 40.4.7 DATABASE LINK MERGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 40.4.8 DATABASE LINK 调用函数/存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 40.5 插件 kdb_database_link 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 40.6 插件 kdb_database_link 的升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 第 41 章 kdb_date_function 281 41.1 插件 kdb_date_function 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 41.2 插件 kdb_date_function 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 41.3 插件 kdb_date_function 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 41.4 插件 kdb_date_function 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 41.4.1 date_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 41.4.2 dateadd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 41.4.3 datediff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 41.4.4 date_format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 41.5 插件 kdb_date_function 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 41.6 插件 kdb_date_function 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 第 42 章 kdb_ddl 286 42.1 插件 kdb_ddl 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 42.2 插件 kdb_ddl 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 42.3 插件 kdb_ddl 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 42.4 插件 kdb_ddl 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 42.4.1 获取完整的数据库对象 DDL 脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 XIII 目 录 42.4.1.1 通过对象名获取完整的 DDL 脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 42.4.1.2 根据 OID 获取完整的 DDL 脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 42.4.2 获取数据库对象创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 42.4.2.1 通过对象名获取创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 42.4.2.1.1 包含权限处理的对象创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 42.4.2.1.2 不包含权限处理的对象创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . 293 42.4.2.2 通过 OID 获取创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 42.4.2.2.1 包含权限处理的对象创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 42.4.2.2.2 不包含权限处理的对象创建语句 . . . . . . . . . . . . . . . . . . . . . . . . . 295 42.4.3 获取数据库对象删除语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 42.4.3.1 通过对象名获取删除语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 42.4.3.2 通过 OID 获取删除语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 42.4.4 获取数据库对象授权语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 42.4.4.1 通过对象名获取授权语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 42.4.4.2 通过 OID 获取授权语句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 42.5 插件 kdb_ddl 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 42.6 插件 kdb_ddl 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 第 43 章 kdb_exists_expand 301 43.1 插件 kdb_exists_expand 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 43.2 插件 kdb_exists_expand 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 43.3 插件 kdb_exists_expand 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 43.4 插件 kdb_exists_expand 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 43.5 插件 kdb_exists_expand 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 43.6 插件 kdb_exists_expand 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 第 44 章 kdb_flashback 304 44.1 插件 kdb_flashback 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 44.2 插件 kdb_flashback 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 44.3 插件 kdb_flashback 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 44.4 插件 kdb_flashback 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 44.4.1 闪回查询 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 44.4.2 闪回版本查询 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 44.4.3 闪回表到指定时间点 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 44.4.4 闪回查询和闪回表技术的使用须知 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 44.4.5 闪回回收站 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 44.5 插件 kdb_flashback 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 44.6 插件 kdb_flashback 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 第 45 章 kdb_license 311 45.1 插件 kdb_license 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 45.2 插件 kdb_license 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 45.3 插件 kdb_license 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 XIV 目 录 45.4 插件 kdb_license 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 45.5 插件 kdb_license 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 45.6 插件 kdb_license 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 第 46 章 kdb_mysql_functions 313 46.1 插件 kdb_mysql_functions 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 46.2 插件 kdb_mysql_functions 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 46.3 插件 kdb_mysql_functions 配置参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 46.4 插件 kdb_mysql_functions 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 46.5 插件 kdb_mysql_functions 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 46.6 插件 kdb_mysql_functions 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 第 47 章 kdb_oracle_datatype 315 47.1 插件 kdb_oracle_datatype 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 47.2 插件 kdb_oracle_datatype 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 47.3 插件 kdb_oracle_datatype 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 47.4 插件 kdb_oracle_datatype 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 47.4.1 支持 blob、clob、nclob 类型导入导出和置空 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 47.4.2 bpcharbyte 类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 47.4.3 bpcharbyte 类型操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 47.4.4 bpcharbyte 类型转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 47.5 插件 kdb_oracle_datatype 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 47.6 插件 kdb_oracle_datatype 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 第 48 章 kdb_oracle_datatype_nls 319 48.1 插件 kdb_oracle_datatype_nls 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 48.2 插件 kdb_oracle_datatype_nls 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 48.3 插件 kdb_oracle_datatype_nls 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 48.4 插件 kdb_oracle_datatype_nls 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 48.4.1 操作符的支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 48.4.2 索引的支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 48.5 插件 kdb_oracle_datatype_nls 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 48.6 插件 kdb_oracle_datatype_nls 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320 第 49 章 kdb_partman 321 49.1 插件 kdb_partman 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 49.1.1 功能和发展 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 49.1.2 插入数据机制解释 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 49.1.3 插入数据的策略 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 49.1.4 partman 的设计约束和特性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 49.1.4.1 时区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 49.1.4.2 子分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 49.1.4.3 Retention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 XV 目 录 49.1.4.4 约束排除 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 49.1.4.5 自定义时间间隔注意事项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 49.1.4.6 命名长度限制 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 49.1.4.7 唯一约束和更新 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 49.1.4.8 日志记录/监控 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 49.1.4.9 后台进程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 49.2 插件 kdb_partman 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 49.3 插件 kdb_partman 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 49.4 插件 kdb_partman 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 49.4.1 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 49.4.1.1 create 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 49.4.1.2 维护函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 49.4.1.3 销毁函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 49.4.1.4 脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 49.4.1.5 编译 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 49.4.1.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 49.4.1.6.1 创建本地分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 49.4.1.6.2 10 个 id 值一个分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 49.4.1.6.3 分区一个已经存在的表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 49.4.1.6.3.1 离线分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 49.4.1.6.3.2 在线分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 49.4.1.6.3.3 撤销本地分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 49.4.1.6.4 设置触发分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 49.4.1.6.4.1 每天一个分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 49.4.1.6.4.2 10 个数一个分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 49.4.1.6.4.3 10 个数一个分区创建的空表使用 upsert 丢弃行冲突 . . . . . . . . . . 349 49.4.1.6.4.4 用 upsert 更新行冲突 . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 49.4.1.6.5 创建多级子分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 49.4.1.6.5.1 时间多级子分区 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 49.4.1.6.5.2 从触发分区迁移到本地 . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 49.4.1.6.6 迁移已有数据表到 partman . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 49.5 插件 kdb_partman 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 49.6 插件 kdb_partman 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 第 50 章 kdb_protect 373 50.1 插件 kdb_protect 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 50.2 插件 kdb_protect 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 50.3 插件 kdb_protect 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 50.4 插件 kdb_protect 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 50.4.1 kdb_protect.protect_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 50.4.2 kdb_protect.protect_add_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 50.4.3 kdb_protect.protect_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 XVI 目 录 50.4.4 kdb_protect.protect_remove_oid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 50.4.5 kdb_protect.protect_remove_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 50.4.6 kdb_protect.protect_show() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 50.4.7 kdb_protect.protect_show_detail() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 50.4.8 kdb_protect.protect_show_one() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 50.4.9 kdb_protect.protect_show_one_detail(text name, char type) . . . . . . . . . . . . . . . . . . . 377 50.5 插件 kdb_protect 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 50.6 插件 kdb_protect 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 第 51 章 kdb_raw 379 51.1 插件 kdb_raw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 51.2 插件 kdb_raw 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 51.3 插件 kdb_raw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 51.4 插件 kdb_raw 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 51.4.1 UTL_ENCODE 包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 51.4.1.1 BASE64_DECODE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 51.4.1.2 BASE64_ENCODE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 51.4.1.3 QUOTED_PRINTABLE_DECODE 函数 . . . . . . . . . . . . . . . . . . . . . . . . 381 51.4.1.4 QUOTED_PRINTABLE_ENCODE 函数 . . . . . . . . . . . . . . . . . . . . . . . . 382 51.4.2 UTL_RAW 包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 51.4.2.1 BIT_AND 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 51.4.2.2 BIT_COMPLEMENT 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 51.4.2.3 BIT_OR 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 51.4.2.4 BIT_XOR 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 51.4.2.5 CAST_FROM_BINARY_DOUBLE 函数 . . . . . . . . . . . . . . . . . . . . . . . . 385 51.4.2.6 CAST_FROM_BINARY_FLOAT 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 386 51.4.2.7 CAST_FROM_BINARY_INTEGER 函数 . . . . . . . . . . . . . . . . . . . . . . . . 386 51.4.2.8 CAST_FROM_NUMBER 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 51.4.2.9 CAST_TO_BINARY_DOUBLE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . 388 51.4.2.10 CAST_TO_BINARY_FLOAT 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 51.4.2.11 CAST_TO_BINARY_INTEGER 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 389 51.4.2.12 CAST_TO_NUMBER 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 51.4.2.13 CAST_TO_RAW 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 51.4.2.14 CAST_TO_VARCHAR2 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 51.4.2.15 COMPARE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 51.4.2.16 CONCAT 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 51.4.2.17 CONVER 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 51.4.2.18 COPIES 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 51.4.2.19 LENGTH 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 51.4.2.20 OVERLAY 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 51.4.2.21 REVERSE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 51.4.2.22 SUBSTR 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 XVII 目 录 51.4.2.23 TRANSLATE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 51.4.2.24 TRANSLITERATE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 51.4.2.25 XRANGE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 51.4.3 UTL_I18 包 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 51.4.3.1 RAW_TO_CHAR 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 51.4.3.2 STRING_TO_RAW 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 51.5 插件 kdb_raw 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 51.6 插件 kdb_raw 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 第 52 章 kdb_schedule 405 52.1 插件 kdb_schedule 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 52.2 插件 kdb_schedule 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 52.3 插件 kdb_schedule 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 52.4 插件 kdb_schedule 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 52.4.1 DBMS_JOB 模式下存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 52.4.1.1 BROKEN 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 52.4.1.2 CHANGE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 52.4.1.3 INTERVAL 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 52.4.1.4 NEXT_DATE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 52.4.1.5 REMOVE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 52.4.1.6 RUN 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 52.4.1.7 SUBMIT 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 52.4.1.8 WHAT 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 52.4.1.9 INSTANCE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 52.4.2 DBMS_SCHEDULER 模式下函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 52.4.2.1 CREATE_PROGRAM 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 52.4.2.2 DROP_PROGRAM 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 52.4.2.3 CREATE_SCHEDULE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 52.4.2.4 DROP_SCHEDULE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 52.4.2.5 EVALUATE_CALENDAR_STRING 存储过程 . . . . . . . . . . . . . . . . . . . . . 415 52.4.2.6 CREATE_JOB 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 52.4.2.7 DROP_JOB 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 52.4.2.8 RUN_JOB 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 52.4.2.9 DISABLE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 52.4.2.10 ENABLE 存储过程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 52.4.3 日历表示法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 52.5 插件 kdb_schedule 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 52.6 插件 kdb_schedule 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 第 53 章 kdb_tinyint 423 53.1 插件 kdb_tinyint 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 53.2 插件 kdb_tinyint 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 53.3 插件 kdb_tinyint 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 XVIII 目 录 53.4 插件 kdb_tinyint 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 53.4.1 conversion functions support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 53.4.2 operator functions support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 53.4.3 index suppor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 53.4.4 mathematics functions support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 53.5 插件 kdb_tinyint 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 53.6 插件 kdb_tinyint 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 第 54 章 kdb_utils_function 427 54.1 插件 kdb_utils_function 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 54.2 插件 kdb_utils_function 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 54.3 插件 kdb_utils_function 配置参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 54.4 插件 kdb_utils_function 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 54.4.1 函数列表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 54.5 插件 backtrace 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 第 55 章 kdb_xmltype 431 55.1 插件 kdb_xmltype 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 55.2 插件 kdb_xmltype 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 55.3 插件 kdb_xmltype 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 55.4 插件 kdb_xmltype 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 55.4.1 XMLTYPE 类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 55.4.1.1 输入输出 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 55.4.1.2 数据存储 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.4.1.3 操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.4.1.4 类型转换 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.4.1.5 索引 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.4.1.6 xml 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.5 XMLTYPE 成员函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.5.1 createXML 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 55.5.2 existsnode 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 55.5.3 extract 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 55.5.4 getclobval 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 55.5.5 getnumberval 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 55.5.6 getstringval 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 55.5.7 XMLSEQUENCE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 55.5.8 VALUE 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 55.6 插件 kdb_xmltype 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 55.7 插件 kdb_xmltype 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 第 56 章 kingbase_fdw 440 56.1 插件 kingbase_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 56.2 插件 kingbase_fdw 的加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 XIX 目 录 56.3 插件 kingbase_fdw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 56.3.1 连接选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 56.3.2 对象名称选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 56.3.3 代价估计选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 56.3.4 远程执行选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 56.3.5 可更新性选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 56.3.6 导入选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 56.4 插件 kingbase_fdw 的使用 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 56.5 插件 kingbase_fdw 的卸载 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 56.6 插件 kingbase_fdw 的升级 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 第 57 章 kingbase_version 446 57.1 插件 kingbase_version 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 57.2 插件 kingbase_version 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 57.3 插件 kingbase_version 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 57.4 插件 kingbase_version 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 57.4.1 bulid_version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446 57.5 插件 bulid_version 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 57.6 插件 bulid_version 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 第 58 章 ktrack 448 58.1 插件 ktrack 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 58.2 插件 ktrack 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 58.3 插件 ktrack 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 58.4 插件 ktrack 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 58.5 插件 ktrack 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 58.6 插件 ktrack 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449 第 59 章 lo 450 59.1 插件 lo 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 59.2 插件 lo 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 59.3 插件 lo 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 59.4 插件 lo 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 59.5 插件 lo 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 59.6 插件 lo 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 第 60 章 mysql_fdw 452 60.1 插件 mysql_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 60.2 插件 mysql_fdw 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 60.3 插件 mysql_fdw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 60.4 插件 mysql_fdw 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 60.4.1 连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 60.4.2 列 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 XX 目 录 60.4.3 数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453 60.4.4 CREATE SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 60.4.5 CREATE USER MAPPING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 60.4.6 CREATE FOREIGN TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 60.4.7 WHERE 条件和 ORDER BY 子句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 60.4.8 外部表之间的 JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 60.4.9 聚合函数的下推 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 60.4.10 修改外部数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 60.4.11 EXPLAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 60.4.12 支持 IMPORT FOREIGN SCHEMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 60.5 插件 mysql_fdw 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 60.6 插件 mysql_fdw 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 第 61 章 mysql_json 458 61.1 插件 mysql_json 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 61.2 插件 mysql_json 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 61.3 插件 mysql_json 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 61.4 插件 mysql_json 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 61.4.1 json_array_append 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 61.4.2 json_array_insert 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 61.4.3 json_contains 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 61.4.4 json_contains_patch 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 61.4.5 json_depth 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 61.4.6 json_extract 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 61.4.7 json_insert 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464 61.4.8 json_keys 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 61.4.9 json_length 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 61.4.10 json_length 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 61.4.11 json_merge_preserve 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 61.4.12 json_merge_preserve 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 61.4.13 json_remove 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 61.4.14 json_remove 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 61.4.15 json_search 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 61.4.16 json_set 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 61.4.17 json_type 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 61.4.18 json_unquote 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473 61.4.19 json_valid 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 61.5 插件 mysql_json 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474 61.6 插件 mysql_json 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 第 62 章 oracle_fdw 476 62.1 插件 oracle_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 62.2 插件 oracle_fdw 的加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 XXI 目 62.3 插件 oracle_fdw 的参数配置 录 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 62.3.1 Foreign data wrapper 参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 62.3.2 Foreign server 参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 62.3.3 User mapping 参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 62.3.4 Foreign table 参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 62.3.5 列参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 62.4 插件 oracle_fdw 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478 62.4.1 Oracle 权限 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 62.4.2 连接 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 62.4.3 列 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 62.4.4 数据类型 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 62.4.5 WHERE 条件和 ORDER BY 子句 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 62.4.6 外部表之间的 JOIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 62.4.7 修改外部数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 62.4.8 EXPLAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 62.4.9 ANALYZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 62.4.10 PostGIS 支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 62.4.11 支持 IMPORT FOREIGN SCHEMA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 62.4.12 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484 62.5 插件 oracle_fdw 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 62.6 插件 oracle_fdw 的升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 第 63 章 owa_util 489 63.1 插件 owa_util 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 63.2 插件 owa_util 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 63.3 插件 owa_util 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 63.4 插件 owa_util 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 63.4.1 返回过程调用者的信息 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 63.4.2 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 63.5 插件 owa_util 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 63.6 插件 owa_util 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491 第 64 章 pageinspect 492 64.1 插件 pageinspect 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 64.2 插件 pageinspect 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 64.3 插件 pageinspect 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 64.4 插件 pageinspect 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 64.4.1 通用函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492 64.4.2 堆表函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494 64.4.3 B 树索引函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 64.4.4 位图索引函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 64.5 插件 pageinspect 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 64.6 插件 pageinspect 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 XXII 目 第 65 章 passwordcheck 录 500 65.1 插件 passwordcheck 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 65.2 插件 passwordcheck 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 65.3 插件 passwordcheck 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 65.4 插件 passwordcheck 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 65.5 插件 passwordcheck 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 65.6 插件 passwordcheck 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504 第 66 章 passwordhistory 505 66.1 插件 passwordhistory 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 66.2 插件 passwordhistory 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 66.3 插件 passwordhistory 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 66.4 插件 passwordhistory 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 66.5 插件 passwordhistory 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 66.6 插件 passwordhistory 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 第 67 章 pldbgapi 508 67.1 插件 pldbgapi 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 67.2 插件 pldbgapi 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 67.3 插件 pldbgapi 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 67.4 插件 pldbgapi 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 67.4.1 pldebugger 调试流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 67.4.2 接口函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 67.4.2.1 plpgsql_oid_debug 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 67.4.2.2 pldbg_attach_to_port 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 67.4.2.3 pldbg_create_listener 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 67.4.2.4 pldbg_set_global_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 67.4.2.5 pldbg_wait_for_target 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 67.4.2.6 pldbg_set_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 67.4.2.7 pldbg_get_breakpoints 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 67.4.2.8 pldbg_drop_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 67.4.2.9 pldbg_wait_for_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 67.4.2.10 pldbg_step_into 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 67.4.2.11 pldbg_step_over 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 67.4.2.12 pldbg_continue 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 67.4.2.13 pldbg_abort_target 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515 67.4.2.14 pldbg_get_variables 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516 67.4.2.15 pldbg_deposit_value 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 67.4.2.16 pldbg_get_stack 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 67.4.2.17 pldbg_select_frame 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 67.4.2.18 pldbg_get_source 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 67.4.2.19 plsql_extend_get_proc_ddl 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 67.4.2.20 pldbg_get_proxy_info 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 XXIII 目 录 67.4.2.21 局部断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 67.4.2.22 全局断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524 67.4.2.23 修改调试时数据及删除断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 67.5 插件 pldbgapi 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 67.6 插件 pldbgapi 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 第 68 章 plsql_pldbgapi 534 68.1 插件 plsql_pldbgapi 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 68.2 插件 plsql_pldbgapi 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 68.3 插件 plsql_pldbgapi 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 68.4 插件 plsql_pldbgapi 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 68.4.1 plsql_debugger 调试流程 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 68.4.2 接口函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 68.4.2.1 plsql_oid_debug 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 68.4.2.2 plsql_oid_debug_number 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 68.4.2.3 plsql_pldbg_attach_to_port 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 68.4.2.4 plsql_pldbg_create_listener 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 68.4.2.5 plsql_pldbg_set_global_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 539 68.4.2.6 plsql_pldbg_wait_for_target 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 68.4.2.7 plsql_pldbg_set_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 68.4.2.8 plsql_pldbg_get_breakpoints 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 68.4.2.9 plsql_pldbg_drop_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 68.4.2.10 plsql_pldbg_wait_for_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 542 68.4.2.11 plsql_pldbg_step_into 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 68.4.2.12 plsql_pldbg_step_over 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 68.4.2.13 plsql_pldbg_continue 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 68.4.2.14 plsql_pldbg_step_out 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 68.4.2.15 plsql_pldbg_step_end 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 68.4.2.16 plsql_pldbg_run_to_next_exception 函数 . . . . . . . . . . . . . . . . . . . . . . . 545 68.4.2.17 plsql_pldbg_run_to_cursor_line 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . 545 68.4.2.18 plsql_pldbg_alter_breakpoint_hit_number 函数 . . . . . . . . . . . . . . . . . . . . 546 68.4.2.19 plsql_pldbg_alter_breakpoint_msg 函数 . . . . . . . . . . . . . . . . . . . . . . . . 547 68.4.2.20 plsql_pldbg_alter_breakpoint_status 函数 . . . . . . . . . . . . . . . . . . . . . . . 548 68.4.2.21 plsql_pldbg_alter_all_breakpoint_status 函数 . . . . . . . . . . . . . . . . . . . . . 549 68.4.2.22 plsql_pldbg_set_breakpoint_src 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . 550 68.4.2.23 plsql_pldbg_get_breakpoints_src 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 551 68.4.2.24 plsql_pldbg_set_exception_breakpoint_src 函数 . . . . . . . . . . . . . . . . . . . . 552 68.4.2.25 plsql_pldbg_get_exception_breakpoints_src 函数 . . . . . . . . . . . . . . . . . . . 554 68.4.2.26 plsql_pldbg_drop_exception_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . 555 68.4.2.27 plsql_pldbg_drop_all_breakpoint 函数 . . . . . . . . . . . . . . . . . . . . . . . . . 555 68.4.2.28 plsql_pldbg_abort_target 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 68.4.2.29 plsql_pldbg_get_variables 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 XXIV 目 录 68.4.2.30 plsql_pldbg_deposit_value 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 68.4.2.31 plsql_pldbg_get_stack 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 68.4.2.32 plsql_pldbg_select_frame 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 68.4.2.33 plsql_pldbg_get_source 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 68.4.2.34 plsql_extend_get_proc_ddl 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 68.4.2.35 plsql_pldbg_get_proxy_info 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 68.4.2.36 plsql_pldbg_set_connection_timeout 函数 . . . . . . . . . . . . . . . . . . . . . . . 561 68.4.2.37 plsql_pldbg_set_operation_timeout 函数 . . . . . . . . . . . . . . . . . . . . . . . . 561 68.4.2.38 局部断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 68.4.2.39 全局断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 68.4.2.40 修改调试时数据及删除断点调试示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 68.5 插件 plsql_pldbgapi 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 68.6 插件 plsql_pldbgapi 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 第 69 章 plsql_plprofiler 575 69.1 插件 plsql_plprofiler 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 69.2 插件 plsql_plprofiler 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 69.3 插件 plsql_plprofiler 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 69.4 插件 plsql_plprofiler 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 69.4.1 plsql_plprofiler 使用说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 69.4.2 接口函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 69.4.2.1 pl_profiler_set_enabled_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 69.4.2.2 pl_profiler_set_enabled_pid 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 69.4.2.3 pl_profiler_get_enabled_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 69.4.2.4 pl_profiler_get_enabled_pid 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 69.4.2.5 pl_profiler_set_enabled_global 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 69.4.2.6 pl_profiler_get_enabled_global 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . 581 69.4.2.7 pl_profiler_collect_data 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 69.4.2.8 pl_profiler_set_collect_interval 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 69.4.2.9 pl_profiler_get_collect_interval 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 69.4.2.10 pl_profiler_reset_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 69.4.2.11 pl_profiler_reset_shared 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 69.4.2.12 pl_profiler_linestats_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583 69.4.2.13 pl_profiler_linestats_shared 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 69.4.2.14 pl_profiler_func_oids_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 69.4.2.15 pl_profiler_func_oids_shared 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 69.4.2.16 pl_profiler_callgraph_local 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 69.4.2.17 pl_profiler_callgraph_shared 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 69.4.2.18 pl_profiler_get_stack 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 69.4.2.19 pl_profiler_funcs_source 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 69.4.2.20 pl_profiler_version 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 69.4.2.21 pl_profiler_versionstr 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 XXV 目 录 69.4.2.22 pl_profiler_lines_overflow 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 69.4.3 典型用例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 69.5 插件 plsql_plprofiler 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 69.6 插件 plsql_plprofiler 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 第 70 章 restricted_dba 596 70.1 插件 restricted_dba 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 70.2 插件 restricted_dba 加载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 70.3 插件 restricted_dba 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596 70.3.1 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 70.4 插件 restricted_dba 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 70.5 插件 restricted_dba 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597 70.6 插件 restricted_dba 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598 第 71 章 roledisable 599 71.1 插件 roledisable 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 71.2 插件 roledisable 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 71.2.1 查看角色状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 71.2.2 字段说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599 71.2.3 启用角色 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 71.2.4 禁用角色 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 71.2.5 被禁用角色的表现 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 71.3 插件 roledisable 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 71.4 插件 roledisable 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 71.5 插件 roledisable 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 71.6 插件 roledisable 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 第 72 章 rum 602 72.1 插件 rum 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 72.2 插件 rum 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 72.3 插件 rum 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 72.4 插件 rum 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 72.5 插件 rum 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602 72.6 插件 rum 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 第 73 章 security_utils 604 73.1 插件 security_utils 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 73.2 插件 security_utils 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 73.3 插件 security_utils 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604 73.4 插件 security_utils 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 73.4.1 口令脱敏 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 73.4.2 弱口令扫描 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606 73.5 相关函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 XXVI 目 录 73.5.1 check_guc_in_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 73.5.2 set_guc_in_cluster() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 73.5.2.1 定时任务 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 73.6 插件 security_utils 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 73.7 插件 security_utils 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610 第 74 章 seg 611 74.1 插件 seg 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 74.2 插件 seg 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 74.3 插件 seg 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 74.4 插件 seg 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611 74.5 插件 seg 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 74.6 插件 seg 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613 第 75 章 send_mails 614 75.1 插件 send_mails 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 75.2 插件 send_mails 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 75.3 插件 send_mails 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 75.4 插件 send_mails 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 75.5 插件 send_mails 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 75.6 插件 send_mails 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 第 76 章 sepapower 616 76.1 插件 sepapower 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 76.2 插件 sepapower 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 76.3 插件 sepapower 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 76.4 插件 sepapower 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 76.5 插件 sepapower 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 76.6 插件 sepapower 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 第 77 章 src_restrict 619 77.1 插件 src_restrict 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 77.2 插件 src_restrict 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 77.3 插件 src_restrict 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 77.4 插件 src_restrict 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 77.4.1 系统函数 src_restrict.add_rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 77.4.2 系统函数 src_restrict.remove_rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 77.4.3 系统视图 src_restrict.show_rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 77.4.4 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 77.5 插件 src_restrict 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 77.6 插件 src_restrict 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 第 78 章 sslinfo 624 78.1 插件 sslinfo 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 XXVII 目 录 78.2 插件 sslinfo 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 78.3 插件 sslinfo 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 78.4 插件 sslinfo 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 78.5 插件 sslinfo 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 78.6 插件 sslinfo 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 第 79 章 sso_update_user 626 79.1 插件 sso_update_user 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 79.2 插件 sso_update_user 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 79.3 插件 sso_update_user 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 79.4 插件 sso_update_user 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 79.5 插件 sso_update_user 卸载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 79.6 插件 sso_update_user 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627 第 80 章 sys_anon 628 80.1 插件 sys_anon 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 80.2 插件 sys_anon 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 80.3 插件 sys_anon 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 80.4 插件 sys_anon 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 80.5 插件 sys_anon 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 80.6 插件 sys_anon 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 第 81 章 sys_audlog 630 81.1 插件 sys_audlog 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 81.2 插件 sys_audlog 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 81.3 插件 sys_audlog 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 81.4 插件 sys_audlog 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 81.5 插件 sys_audlog 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 81.6 插件 sys_audlog 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631 第 82 章 sys_buffercache 632 82.1 插件 sys_buffercache 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 82.2 插件 sys_buffercache 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 82.3 插件 sys_buffercache 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 82.4 插件 sys_buffercache 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 82.5 插件 sys_buffercache 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 82.6 插件 sys_buffercache 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 第 83 章 sys_bulkload 635 83.1 插件 sys_bulkload 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 83.2 插件 sys_bulkload 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 83.3 插件 sys_bulkload 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 83.4 插件 sys_bulkload 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 83.5 插件 sys_bulkload 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 XXVIII 目 录 83.6 插件 sys_bulkload 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 第 84 章 sys_freespacemap 84.1 插件 sys_freespacemap 简介 637 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 84.2 插件 sys_freespacemap 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 84.3 插件 sys_freespacemap 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 84.4 插件 sys_freespacemap 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637 84.5 插件 sys_freespacemap 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 84.6 插件 sys_freespacemap 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 第 85 章 sys_jieba 639 85.1 插件 sys_jieba 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 85.2 插件 sys_jieba 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 85.3 插件 sys_jieba 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 85.4 插件 sys_jieba 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 85.5 插件 sys_jieba 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 85.6 插件 sys_jieba 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640 第 86 章 sys_kwr 641 86.1 插件 sys_kwr 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 86.2 插件 sys_kwr 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 86.3 插件 sys_kwr 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 86.4 插件 sys_kwr 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 86.4.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 86.4.2 自动快照 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 86.4.3 手动快照 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 86.4.4 生成 kwr 报告 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 86.4.5 生成 html 报告 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 86.4.6 KSH 功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 86.4.7 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 86.5 KSH 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 86.6 KSH 功能的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 86.6.1 采集数据说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 86.6.2 生成报告 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 86.7 插件 sys_kwr 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 86.8 插件 sys_kwr 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 第 87 章 sys_sqltune 648 87.1 插件 sys_sqltune 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 87.2 插件 sys_sqltune 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 87.3 插件 sys_sqltune 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 87.4 插件 sys_sqltune 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 87.4.1 概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 XXIX 目 录 87.4.2 SQL 监控概述 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 87.4.3 SQL 监控功能 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 87.4.4 SQL 监控函数接口 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 87.4.5 生成监控报告 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 87.4.6 SQL 监控视图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 87.5 插件 sys_sqltune 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 87.6 插件 sys_sqltune 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656 第 88 章 sys_prewarm 657 88.1 插件 sys_prewarm 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 88.2 插件 sys_prewarm 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 88.3 插件 sys_prewarm 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 88.4 插件 sys_prewarm 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 88.5 插件 sys_prewarm 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 88.6 插件 sys_prewarm 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659 第 89 章 sys_qualstats 660 89.1 插件 sys_qualstats 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 89.2 插件 sys_qualstats 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 89.3 插件 sys_qualstats 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 89.4 插件 sys_qualstats 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 89.4.1 sys_qualstats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 89.4.2 sys_qualstats_reset() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 89.4.3 sys_qualstats_example_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 89.4.4 sys_qualstats_names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 89.4.5 sys_qualstats_example_queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 89.4.6 sys_qualstats_pretty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 89.4.7 sys_qualstats_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 89.4.8 sys_qualstats_indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 89.4.9 sys_qualstats_by_query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 89.4.10 使用索引建议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 89.4.10.1 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 89.4.10.2 创建插件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 89.4.10.3 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 89.4.10.3.1 准备测试数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 89.4.10.3.2 查看执行计划 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 89.4.10.3.3 查看索引建议 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 89.4.10.4 根据索引建议创建索引 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 89.4.10.5 查看创建完索引后的执行计划 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 89.5 插件 sys_qualstats 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667 89.6 插件 sys_qualstats 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668 第 90 章 sys_recovery 669 XXX 目 录 90.1 插件 sys_recovery 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 90.2 插件 sys_recovery 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 90.3 插件 sys_recovery 的参数说明配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669 90.4 插件 sys_recovery 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 90.5 插件 sys_recovery 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 90.6 插件 sys_stat_statements 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 90.7 其它说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671 第 91 章 sys_spacequota 672 91.1 插件 sys_spacequota 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 91.2 插件 sys_spacequota 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 91.3 插件 sys_spacequota 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672 91.4 插件 sys_spacequota 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 91.4.1 开关及查询: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 91.4.2 remove_space_quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 91.4.3 space_quota_check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673 91.4.4 set_space_quota(oid, quota) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 91.5 插件 sys_spacequota 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 674 91.6 插件 sys_spacequota 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 第 92 章 sys_squeeze 676 92.1 插件 sys_squeeze 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 92.2 插件 sys_squeeze 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676 92.3 插件 sys_squeeze 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 92.4 插件 sys_squeeze 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677 92.5 插件 sys_squeeze 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 92.6 插件 sys_squeeze 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678 第 93 章 sys_stat_statements 679 93.1 插件 sys_stat_statements 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 93.2 插件 sys_stat_statements 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 93.3 插件 sys_stat_statements 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679 93.4 插件 sys_stat_statements 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 680 93.5 插件 sys_stat_statements 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 93.6 插件 sys_stat_statements 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684 第 94 章 sys_trgm 685 94.1 插件 sys_trgm 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 94.2 插件 sys_trgm 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 94.3 插件 sys_trgm 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 94.4 插件 sys_trgm 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 94.4.1 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685 94.4.2 操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 XXXI 目 录 94.4.3 GUC 参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 688 94.4.4 索引支持 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689 94.4.5 文本搜索集成 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691 94.5 插件 sys_trgm 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 94.6 插件 sys_trgm 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692 第 95 章 sys_visibility 693 95.1 插件 sys_visibility 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 95.2 插件 sys_visibility 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 95.3 插件 sys_visibility 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 95.4 插件 sys_visibility 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693 95.5 插件 sys_visibility 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 95.6 插件 sys_visibility 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 第 96 章 sysaudit 695 96.1 插件 sysaudit 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695 96.2 插件 sysaudit 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695 96.3 插件 sysaudit 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695 96.4 插件 sysaudit 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695 96.5 插件 sysaudit 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696 96.6 插件 sysaudit 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696 第 97 章 sysencrypt 697 97.1 插件 sysencrypt 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 97.2 插件 sysencrypt 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 97.3 插件 sysencrypt 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697 97.4 插件 sysencrypt 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 97.5 插件 sysencrypt 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 97.6 插件 sysencrypt 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 第 98 章 sysmac 699 98.1 插件 sysmac 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 98.2 插件 sysmac 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 98.3 插件 sysmac 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699 98.4 插件 sysmac 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 98.5 插件 sysmac 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 98.6 插件 sysmac 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 第 99 章 sysprivilege 701 99.1 插件 sysprivilege 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 99.2 插件 sysprivilege 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 99.3 插件 sysprivilege 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 99.4 插件 sysprivilege 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701 99.4.1 相关表和视图 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 XXXII 目 录 99.4.2 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 99.5 插件 sysprivilege 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 99.6 插件 sysprivilege 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704 第 100 章 sysreuse_residual_data 705 100.1 插件 sysreuse_residual_data 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 100.2 插件 sysreuse_residual_data 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 100.3 插件 sysreuse_residual_data 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705 100.4 插件 sysreuse_residual_data 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 100.5 插件 sysreuse_residual_data 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 100.6 插件 sysreuse_residual_data 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 第 101 章 tablefunc 707 101.1 插件 tablefunc 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 101.2 插件 tablefunc 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 101.3 插件 tablefunc 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 101.4 插件 tablefunc 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 101.5 插件 tablefunc 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 101.6 插件 tablefunc 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 第 102 章 tcn 709 102.1 插件 tcn 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 102.2 插件 tcn 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 102.3 插件 tcn 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709 102.4 插件 tcn 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 102.5 插件 tcn 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 102.6 插件 tcn 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 第 103 章 tds_fdw 712 103.1 插件 tds_fdw 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 103.2 插件 tds_fdw 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 103.3 插件 tds_fdw 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 103.3.1 外部服务器参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712 103.3.2 外部表参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714 103.3.3 外部数据包装器参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 103.3.4 导入外部模式参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 103.3.5 变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 103.4 插件 tds_fdw 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 103.4.1 创建外部服务器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 103.4.2 创建外部表 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 103.4.3 创建外部数据包装器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 103.4.4 导入外部模式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 103.4.5 变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 XXXIII 目 录 103.4.6 EXPLAIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 103.4.7 关于字符集和编译的说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 103.4.8 加密连接 MSSQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 103.5 插件 tds_fdw 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 103.6 插件 tds_fdw 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 第 104 章 tsm_system_rows 720 104.1 插件 tsm_system_rows 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 104.2 插件 tsm_system_rows 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 104.3 插件 tsm_system_rows 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 104.4 插件 tsm_system_rows 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 104.5 插件 tsm_system_rows 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 104.6 插件 tsm_system_rows 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 第 105 章 tsm_system_time 722 105.1 插件 tsm_system_time 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 105.2 插件 tsm_system_time 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 105.3 插件 tsm_system_time 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 105.4 插件 tsm_system_time 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 105.5 插件 tsm_system_time 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 105.6 插件 tsm_system_time 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 第 106 章 unaccent 724 106.1 插件 unaccent 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 106.2 插件 unaccent 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 106.3 插件 unaccent 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 106.4 插件 unaccent 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725 106.5 插件 unaccent 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 106.6 插件 unaccent 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 第 107 章 utl_file 727 107.1 插件 utl_file 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 107.2 插件 utl_file 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 107.3 插件 utl_file 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 107.4 插件 utl_file 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 107.4.1 utl_file.fopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727 107.4.2 utl_file.put_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 107.4.3 utl_file.put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 107.4.4 utl_file.fclose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 107.4.5 utl_file.fclose_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732 107.4.6 utl_file.get_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 107.4.7 utl_file.new_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 107.4.8 utl_file.fflush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 XXXIV 目 录 107.5 插件 utl_file 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 107.6 插件 utl_file 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736 第 108 章 uuid-ossp 737 108.1 插件 uuid-ossp 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 108.2 插件 uuid-ossp 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 108.3 插件 uuid-ossp 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 108.4 插件 uuid-ossp 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 108.5 插件 uuid-ossp 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738 108.6 插件 uuid-ossp 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738 第 109 章 walminer 739 第 110 章 xml2 740 110.1 插件 xml2 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 110.2 插件 xml2 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 110.3 插件 xml2 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 110.4 插件 xml2 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 110.4.1 xpath_table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 110.4.1.1 多值结果 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743 110.4.2 XSLT 函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 110.5 插件 xml2 卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 110.6 插件 xml2 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 第 111 章 zhparser 745 111.1 插件 zhparser 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 111.2 插件 zhparser 加载方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 111.3 插件 zhparser 的参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 111.4 插件 zhparser 的使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 111.5 插件 zhparser 的卸载方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748 111.6 插件 zhparser 升级方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748 版权声明 749 服务周期承诺 750 XXXV 第 1 章 前言 1 第 章 前言 本文档介绍了 KingbaseES 所有插件的功能和使用方法。 前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES 插件参考手册面向所有使用 KingbaseES 的用户，主要是数据库管理员和应用程序开发人员。 1.2 相关文档 有关更多 KingbaseES 相关的信息，请参阅 KingbaseES 数据库文档集中的以下文档： • KingbaseES 数据库管理员指南 • KingbaseES 数据库概念 • KingbaseES 数据库开发指南 • KingbaseES SQL 语言参考手册 1 第 1 章 前言 1.3 术语 1.4 手册约定 本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下： 注意: 用于突出重要/关键信息、最佳实践等。 提示: 用于突出小窍门、捷径等。 警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其 它不可预知的结果。 另请参阅: 用于突出参考、参阅等。 以下程序代码书写约定适用于本文档： 符号 说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。 斜体 表示占位符或者需要提供特定值的变量。 大写 表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按 照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以 小写形式输入。 小写 表示由用户提供的元素。 2 第2章 2 第 章 扩展插件概述 扩展插件概述 KingbaseES 开发了大量的扩展包。如：dbms_output，dbms_ddl，dbms_metadata 等。在日常使用过程中， 如果功能在 KingbaseES 中没有默认支持，可以在操作系统中进入 $KINGBASE_HOME/ Server/share/extension 目 录，搜索扩展 sql 文件来确认是否已有相应的扩展。也可以查询当前版本支持的扩展插件： select * from sys_available_extensions; 执行 \dx 查询当前已安装的扩展插件： test=# \dx 已安装扩展列表 名称 | 版本 | 架构模式 | 描述 ---------------------+------+------------+-----------------------------------------------dbms_ddl | 1.0 | sys | DBMS_DDL system package dbms_output | 1.0 | sys | DBMS_OUTPUT system package dbms_utility | 1.0 | sys | dbms_utility extension package kdb_license | 1.0 | sys_catalog| kdb_license extension kdb_oracle_datatype | 1.0 | sys | kdb_oracle_datatype extension kdb_schedule | sys | A KingbaseES job scheduler | 1.0 表 plug-TABLE 列出了 KingbaseES 所提供的扩展插件。后文为每个扩展插件的详细文档。 插件名称 用途 amcheck 让用户能验证关系逻辑结构的一致性 auth_delay 登录失败延时 auto_bmr 支持自动块修复 auto_explain 自动记录 SQL 语句的执行计划，并写入到 KingbaseES 日志文件中 backtrace 程序崩溃时获取并打印输出堆栈信息 backup_pri 允许物理备份 sys_basebackup 连接到目标数据库，执行物理备份操作 见续表 3 第2章 扩展插件概述 表 2.1 – 续表 插件名称 用途 bloom 提供了 bloom 过滤器索引 citext 支持大小写不敏感的字符串类型 citext 及其相关操作 cstore_fdw 实现列式存储及压缩 cube 实现了一种数据类型 cube 来表示多维立方体 dblink 支持在一个数据库会话中连接到其他 Kingbase 数据库 dbms_ddl 创建一个 PL/SQL 包体、函数、过程。 dbms_lob 对 CLOB/BLOB 大对象就行的操作 dbms_metadata 创建特定类型对象的 DDL 语句 dbms_mview 提供对物化视图的一些操作 dbms_obfuscation_toolkit 提供 DES 或 3DES 算法进行数据的加解密 dbms_output 提供将文本行写入缓冲区、供以后提取和显示的功能 dbms_random 提供一个随机数或者字符的生成器 dbms_session 实现对 session 中内容的操作 dbms_sql 定义了一系列的过程和函数，专门用于动态 SQL 语句的操作 dbms_utility 提供一些具有通用功能的子程序 dict_int 支持了对于数字的 text 类型搜索字典 dict_xsyn 提供一个具有附加全文搜索功能的字典模板 earthdistance 支持了与地球表面相关的数据操作 file_fdw 用来访问存储在外部文件中的数据 fix_security_hole 禁止通过 copy 执行操作系统命令 ftutilx 流版式文件内容抽取 fuzzystrmatch 提供了两个字符串之间的编辑距离的相关函数 hstore 支持 hstore 类型 http KingbaseES 的 http 客户端，允许在数据库内检索网页 见续表 4 第2章 扩展插件概述 表 2.1 – 续表 插件名称 用途 identity_pwdexp 管理和检查用户口令的有效期 intagg 提供了一个整数聚合器和一个枚举器，作为内置函数的兼容性封装器提供 intarray 为操作整数的 null-free 数组提供一些有用的函数和操作符。 isn 为国际产品编号标准提供数据类型 kbcrypto 提供如 rc4,sm3,sm4 等加密函数的访问接口 kbrowlocks 提供了一个函数来显示指定表的行级锁信息 kbstattuple 提供了多种函数来获得关系中元组的统计信息 kdb_database_link 用于访问外部数据库对象 kdb_date_function 兼容 mysql 的日期相关的函数 kdb_ddl 用于生成数据库对象 DDL 语句 kdb_exists_expand 优化 EXISTS 子链接，生成执行效率更高的执行计划 kdb_flashback 支持 flashback 技术 kdb_license 初始化内置，基本类型 kdb_mysql_functions 兼容 MySQL 函数 kdb_oracle_datatype 初始化内置，兼容 Oracle 数据类型 kdb_oracle_datatype_nls 初始化内置，兼容 Oracle 日期 date 数据类型 kdb_orafce 实现对 oracle 一些函数和包的兼容 kdbpartman 分区管理 kdb_protect 用于保护 database、schema、table 等逻辑对象不被删除 kdb_raw 实现对 raw 数据类型的操作 kdb_resource_group 实现资源组功能 kdb_schedule 基于后台进程来实现自动作业功能 kdb_tinyint 初始化内置，基本类型，支持 tinyint 类型 kdb_utils_function 工具函数, 包括 xml, 字符操作等 见续表 5 第2章 扩展插件概述 表 2.1 – 续表 插件名称 用途 kdb_xmltype Oracle 兼容 XMLTYPE 类型和相关的操作函数 kingbase_fdw 用来访问存储在外部 KingbaseES 服务器中的数据 kingbase_version 可以查询 KingbaseES 数据库的构建版本 ktrack 块级别增量备份引擎 lo 提供了触发器在引用了 lo 数据的行被修改或删除时自动调用 lo_unlink ltree 包含 ltree 和 lquery 类型的实现，为树状结构组织的数据提供索引和查询 mysql_fdw 用来访问存储在外部 Mysql 数据库中的数据 oracle_fdw 用来访问存储在外部 Oracle 数据库中的数据 owa_util 支持 OWA_UTIL 系统包中的 WHO_CALLED_ME 过程 pageinspect 提供函数可以查看数据库页面的内容 passwordcheck 管理和检查用户口令的复杂度 passwordhistory 管理用户口令历史，检查用户更新的口令 pldbgapi PG 语法调试 plsql_pldbgapi oracle 语法调试 plsql_plprofiler 收集分析器（性能）数据以提高性能或确定 PL/SQL 应用程序的代码覆盖率 repmgr 详见《金仓数据守护集群和读写分离集群使用手册》repmgr restricted_dba 实现对超级用户权限进行限制 roledisable 在本地库内使角色失效, 使失效的角色再生效 rum RUM 索引类型 security_utils 支持安全方面的功能 send_mails 审计入侵检测的邮件告警功能 seg 为程序提供 seg 数据类型的使用 sepapower 三权分立 src_restrict 来源限制 见续表 6 第2章 扩展插件概述 表 2.1 – 续表 插件名称 用途 sslinfo 来提供当前客户端提供的 SSL 证书的有关信息 sso_update_user 进一步划分安全员和管理员权限，满足特殊场景三权分立需求 sys_anon 初始化内置，数据脱敏。参见 数据脱敏 sys_audlog 账户异常登录锁定和账户登录信息显示 sys_buffercache 实时检查共享缓冲区工具 sys_bulkload 快速加载数据的命令行工具 sys_freespacemap 提供了查看 FSM 页面的方法 sys_jieba 用于全文搜索的中文分词插件 sys_kwr 负载信息记录和保存，并提供相关的性能报告 sys_sqltune 语句级调优及资源监控功能，并提供相应报告 sys_prewarm 将关系数据载入到操作系统缓冲区或者 KingbaseES 缓冲区，实现数据预热 sys_qualstats 保存 where 和 join 子句中的谓词统计信息，生成索引建议 sys_recovery 从死元组中读取数据 sys_spacequota 针对表空间限额的操作 sys_squeeze 无锁清理空闲表空间的工具 sys_stat_statements 追踪所有 SQL 语句的执行统计信息 sys_trgm 提供基于 trigram 匹配的字母数字文本相似度的函数和操作符 sys_visibility 提供了查看表的 VM 页数据和页级别可见性的函数 sysaudit 初始化内置，审计。参见 数据库审计 sysencrypt 实现数据加解密 sysmac 初始化内置，强制访问控制。参见 强制访问控制 sysprivilege 实现对数据库系统 ANY 权限的扩展 sysreuse_residual_data 资源申请和释放时清除介质上的残留信息以达到客体重用的要求 tablefunc 返回多行集合的函数 见续表 7 第2章 扩展插件概述 表 2.1 – 续表 插件名称 用途 tcn 提供了一个触发器函数，用于监听所附着表的任意改变 tds_fdw 用于连接使用 TDS 协议的数据库如 Sybase，Microsoft SQL Server tsm_system_rows 提供了表采样方法 SYSTEM_ROWS tsm_system_time 提供了表采样方法 SYSTEM_TIME unaccent 提供了一个能从词位中移除重音的文本搜索字典 utl_file 补充了一些对于文件操作的函数 uuid-ossp uuid 生成工具 walminer 提供从 WAL 日志解析 REDO/UNDO SQL 语句的功能 xml2 提供 XPath 查询和 XSLT 功能函数 zhparser 用于全文搜索的中文分词插件 memstat 在本地和所有后端中添加有关内存上下文的统计报告 一个扩展包通常需要一个包含创建该扩展的对象的 SQL 命令的脚本文件以及一个指定扩展本身的一些基本属性 的控制文件。如果扩展包括 C 代码，通常还有一个 C 代码编译而成的共享库文件。控制文件和脚本默认被放在数据 库的安装目录下的 Server/share/extension 目录中，C 编译的共享库文件则放在 Server/lib 中。 8 第 3 章 AMCHECK 3 第 章 amcheck 3.1 插件 amcheck 简介 amcheck 提供的函数可以让用户能验证关系逻辑结构的一致性，如果结构错误会报错。B 树的验证函数会检查逻 辑结构中应该满足的多种条件。 索引扫描以及其他操作的正确性依赖这些结构的正确性。例如，一些函数会验证 B 树页面中所有索引项都按照 逻辑顺序（比如 text 类型列上的 B 树索引项应该按照词典顺序）排列。 如果这个条件由于某种原因不成立，我们可以预计受影响页面上的二分搜索将无法正确的执行索引扫描，导致整 个 SQL 查询得到错误的结果。 amcheck 函数默认只能由超级用户使用。 • 插件名为 amcheck • 插件版本 V1.2 3.2 插件 amcheck 加载方式 CREATE EXTENSION amcheck; 3.3 插件 amcheck 的参数配置 无需配置任何参数 3.4 插件 amcheck 的使用方法 插件提供以下函数 9 第 3 章 AMCHECK bt_index_check(index regclass, heapallindexed boolean) returns void bt_index_check 验证指定的 B 树索引的逻辑结构正确性。 示例 SELECT bt_index_check('sys_package_oid_index', false); bt_index_check ---------------(1 row) 示例中函数执行没有报错，指定索引的逻辑结构是正确的。 bt_index_check 对目标索引及其所属的堆表加 AccessShareLock。这个锁模式和简单 SELECT 语句在关系上加 的锁模式相同。bt_index_check 不验证跨越父子关系的结构条件。在 heapallindexed 为 true 时会验证堆表的所有 元组都有对应的索引项存在。这个行为是在完整验证和减少对业务的影响间的权衡，函数可以作为快速的轻量验证使 用。 bt_index_parent_check(index regclass, heapallindexed boolean, rootdescend boolean) returns void bt_index_parent_check 验证指定的 B 树索引的逻辑结构正确性。 当 heapallindexed 参数为 true 时，函数验证堆表的所有元组都有对应的索引项存在。和 bt_index_check 不同， 函数会验证索引结构中的父子关系，会检查父节点是否有缺失的 down link。当可选参数 rootdescend 值为 true 时， 函数会通过从根页面开始搜索来查找叶节点的元组。bt_index_parent_check 执行的检查是 bt_index_check 执行检 查的超集。 bt_index_parent_check 对目标索引及其所属的堆表加 ShareLock，这个所模式会阻塞 INSERT、UPDATE 以 及 DELETE 的并发数据修改，同时防止所属堆表被 VACUUM。 注意该函数只在其运行期间而不是整个事务期间持有锁。bt_index_parent_check 的额外验证有更大可能检测到 索引结构的异常，但与 bt_index_check 不同，函数不能在开启 hot_standby 的备机上使用。 3.5 插件 amcheck 卸载方法 DROP EXTENSION amcheck; 3.6 插件 amcheck 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： 10 第 3 章 AMCHECK ALTER EXTENSION amcheck UPDATE TO '1.1'; 11 第4章 4 第 章 4.1 AUTH_DELAY auth_delay 插件 auth_delay 简介 auth_delay 是 KingbaseES 的一个扩展插件，主要用于在用户登录失败时进行延时。 • 插件名为 auth_delay • 插件版本 V1.0 4.2 插件 auth_delay 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例如下： shared_preload_libraries = 'auth_delay' 4.3 插件 auth_delay 的参数配置 auth_delay.milliseconds 当用户登录失败时，延迟显示失败的时间，单位为毫秒，取值范围为 0 至 INT_MAX/1000，缺省值为 0。 show auth_delay.milliseconds; auth_delay.milliseconds ------------------------0 (1 row) 12 第4章 AUTH_DELAY \c - system alter system set auth_delay.milliseconds = 1000; select sys_reload_conf(); show auth_delay.milliseconds; auth_delay.milliseconds ------------------------1s (1 row) 4.4 插件 auth_delay 使用方法 KingbaseES 加载 auth_delay 插件，并修改了参数后，登录失败的用户将会执行登录操作后，延迟设置的时间再 显示登录失败。 4.5 插件 auth_delay 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例如下： shared_preload_libraries = '' 4.6 插件 auth_delay 升级方法 auth_delay 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 13 第5章 5 第 章 5.1 AUTO_BMR auto_bmr 插件 auto_bmr 简介 主数据库访问系统表数据、索引、持久化用户表数据、索引时，从磁盘读取数据块至共享缓冲区，如果检测到坏 块，自动从备节点获取坏块的副本，并修复坏块。 • 插件名为 auto_bmr • 插件版本 V1.1 5.2 插件 auto_bmr 加载方式 CREATE EXTENSION auto_bmr; 5.3 插件 auto_bmr 的参数配置 1、auto_bmr.enable_auto_bmr：是否开启自动块修复功能，取值范围 0/1，默认为 1，支持 reload。 2、auto_bmr.auto_bmr_req_timeout：块自动修复的超时时间，取值范围 0 至 INT_MAX，默认为 60s，0 表 示不限制，支持 set。 3、auto_bmr.auto_bmr_sess_threshold：session 级最大块修复数量，取值范围 0 至 INT_MAX，默认为 100， 0 表示不限制，支持 set。 4、auto_bmr.auto_bmr_sys_threshold：系统级最大块修复数量，取值范围 0 至 INT_MAX，默认为 1024，0 表示不限制，支持 reload。 14 第5章 AUTO_BMR 插件 auto_bmr 的使用方法 5.4 块自动修复功能当检测到坏块和坏块修复成功时，在日志中有对应的 WARNING 提示信息。检测到坏块时提示 信息如下所示： 2021-10-12 18:59:06.264 CST [9128] WARNING: page is invalid: base/16089/16385, blockNum: 3 修复坏块成功时提示信息如下所示： 2021-10-12 18:59:06.292 CST [9128] WARNING: repair invalid page: base/16089/16385, blockNum: 3 successfully. 如果在日志中有类似如下提示： WARNING: Exec get buffer page failed,errMsg:ERROR: function public.get_lsn_reached_page(integer, integer, integer, integer, integer, integer) does not exist LINE 1: select public.get_lsn_reached_page(1663, 16832, 16881, 0, 1,... HINT: No function matches the given name and argument types. You might need to add explicit type casts. 需创建 auto_bmr 扩展插件。 test=# create extension auto_bmr; CREATE EXTENSION 如果系统修复的块数量超过系统级最大块修复数量，可通过 select reset_auto_bmr_sys_bad_blk() 重置系统块 修复数量。 test=# select reset_auto_bmr_sys_bad_blk(); reset_auto_bmr_sys_bad_blk ---------------------------(1 行记录) 如果一个 session 修复的块数量超过 session 级最大块修复数量，可通过 select reset_auto_bmr_sess_bad_blk() 重置 session 修复的块数量。 test=# select reset_auto_bmr_sess_bad_blk(); reset_auto_bmr_sess_bad_blk ----------------------------(1 行记录) 15 第5章 5.5 AUTO_BMR 插件 auto_bmr 卸载方法 DROP EXTENSION auto_bmr; 5.6 插件 auto_bmr 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION auto_bmr UPDATE TO '1.1'; 16 第 6 章 AUTO_EXPLAIN 6 第 章 auto_explain 6.1 插件 auto_explain 简介 auto_explain 是 KingbaseES 的一个扩展插件，主要用于在服务器端自动记录 SQL 语句的执行计划，写入到 KingbaseES 日志文件中。 插件在被服务程序加载后，其相关功能生效，插件在服务端程序启动时不是默认加载。 • 插件名为 auto_explain • 插件版本 V1.0 6.2 插件 auto_explain 加载方式 如需 KingbaseES 数据库启动时默认加载该插件，将其添加到 kingbase.conf 文件的 shared_preload_libraries 中。 如需在数据库启动后使用该插件，在 ksql 中使用 LOAD 命令即可。 示例： shared_preload_libraries = 'auto_explain' 6.3 插件 auto_explain 的参数配置 auto_explain.log_min_duration SQL 语句执行时间的阈值，所有时间超过这个阈值的 SQL 语句的执行计划都会被记录到日志中，单位为 毫秒，0 表示记录所有语句，-1 表示不记录 auto_explain.log_analyze 17 第 6 章 AUTO_EXPLAIN 该参数控制是否加入 analyze 功能，即除了计划外把实际执行时间等信息也打出来，注意该参数打开后会 对性能产生较大影响，默认值为 off auto_explain.log_settings 该参数控制是否打印已修改的配置选项的信息，输出中仅包含影响执行计划的配置选项，默认值为 off auto_explain.log_verbose 该参数控制是否在执行计划中打印更为详细的输出信息，默认值为 off auto_explain.log_buffers 该参数控制是否在执行计划中打印缓冲区使用的信息，默认值为 off auto_explain.log_wal 该参数控制是否打印 WAL 日志的信息，默认值为 off auto_explain.log_triggers 该参数控制是否打印触发器的统计信息，注意只有当 auto_explain.log_analyze 参数开启时，该参数才有 效，默认值为 off auto_explain.log_format 该参数用于控制执行计划的输出格式，可以是 text、xml、json、yaml，默认值为 text auto_explain.log_level 该参数用于控制 auto_explain 插件的日志级别，其值同服务器的日志级别相同，默认值为 LOG auto_explain.log_nested_statements 该参数用于控制是否支持嵌套语句（在一个函数内执行的语句）的执行计划输出，当它关闭时，只记录顶 层语句的计划，默认值为 off auto_explain.log_timing 该参数用于控制是否打印计划中每个节点的计时信息，注意只有当 auto_explain.log_analyze 参数开启 时，该参数才有效，默认值为 off auto_explain.sample_rate 该参数用于控制打印会话中语句计划的比例，默认值为 1，表示输出所有语句的计划 6.4 插件 auto_explain 的使用方法 KingbaseES 加载 auto_explain 插件后，根据其参数配置，将 SQL 语句的执行计划输出到日志文件里。 18 第 6 章 AUTO_EXPLAIN 6.5 插件 auto_explain 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 6.6 插件 auto_explain 升级方法 auto_explain 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 19 第7章 BACKTRACE 7 第 章 backtrace 7.1 插件 backtrace 简介 插件 backtrace 是 KingbaseES 的一个扩展插件。主要功能是在服务端程序崩溃时捕获宕机堆栈信息，并将 core 堆栈信息打印输出到前端或日志文件里。可用于协助分析 KingbaseES 宕机的原因。通常 release 版本的 KingbaseES 需要使用 debug 文件协助分析宕机原因。 插件 backtrace 相关功能在服务程序崩溃时自动触发，无须人为干预，插件在服务端程序启动时默认加载。 • 插件名为 backtrace • 插件版本 V1.0 7.2 插件 backtrace 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'backtrace' 7.3 插件 backtrace 的参数配置 无需配置任何参数 20 第7章 7.4 BACKTRACE 插件 backtrace 的使用方法 KingbaseES 加载 backtrace 插件后，程序崩溃时会自动捕获宕机的堆栈信息，并将 core 堆栈信息打印输出到前 端或日志文件里。 7.5 插件 backtrace 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 7.6 插件 backtrace 升级方法 backtrace 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 21 第8章 8 第 章 8.1 BACKUP_PRI backup_pri 插件 backup_pri 简介 backup_pri 是 KingbaseES 的一个扩展插件，主要用于对备份/恢复操作使用权限限制，插件增加了一个新的管 理特权，SYSBACKUP，允许物理备份 sys_basebackup 连接到目标数据库，执行物理备份操作。 • 插件名为 backup_pri • 插件版本 V1.0 8.2 插件 backup_pri 加载方式 在使用 backup_pri 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'backup_pri' 8.3 插件 backup_pri 的参数配置 backup_pri.enable_backup_pri 启用备份恢复权限功能，取值范围为 ture 或者 false，缺省为 false。 show backup_pri.enable_backup_pri; backup_pri.enable_backup_pri ------------------------------off (1 row) 22 第8章 BACKUP_PRI alter system set backup_pri.enable_backup_pri to on; select sys_reload_conf(); show backup_pri.enable_backup_pri; backup_pri.enable_backup_pri ------------------------------on (1 row) 8.4 插件 backup_pri 使用方法 8.4.1 备份恢复权限的授予与回收 在数据库初始化之后，SYSTEM 用户级 SUPERUSER 用户不具有备份恢复的权限; 但具有该权限的授予与回收 的权利，SYSTEM 用户级 SUPERUSER 用户也可以给自身赋权。 授予与回收的语法： alter user u1 sysbackup; alter user u1 nosysbackup; 同时建用户的时候可以直接授予或回收 create user u1 sysbackup; create user u1 (nosysbackup); 不带默认 nosysbackup，或者建库初始化时的用户也是默认 nosysbackup 的，想要赋予权限，可以用 alter 语句 实现。 删除用户的时候语法： drop user u1; 会自动删除这个用户的备份恢复权限，和其他系统权限一样，记录将不存在。 8.4.2 备份恢复权限流程 存储 sysbackup 权限的系统表 sys_privilege。物理备份 sys_basebackup 时，检查是否持有这个权限，若没有， 报错退出。 具体流程如下： 23 第8章 BACKUP_PRI 1. 备份恢复权限与其他普通权限一样，都是限制一些用户进行指定的操作; 2. 备份恢复权限是用户级别的，在执行备份恢复时，步骤如下： • 检查当前用户是否对要备份还原的数据库有备份恢复的权限; • 检查备份恢复权限，才可以进行备份恢复的操作; • 无备份恢复权限，SYSTEM 或 SUPERUSER 用户为其授予备份恢复权限。才可以执行备份恢复的操作。 在执行备份恢复时，增加一项备份恢复的权限检查; 8.4.3 相关系统视图 sysbackup 权限相关的三个系统视图如下： • backup_pri.dba_sys_privs 查询出所有的用户的 sysbackup 权限和其他系统权限，若用户没有 sysbackup 权限，有可能显示的是空，或者 nosysbackup 两种情况。 backup_pri.dba_sys_privs 视图的每个字段意义如下表所示： 表 8.4.1: backup_pri.dba_sys_privs 视图 列名 描述 username 用户名 userid 用户 id superuser 超级用户 inherit 继承 createrole 创建角色 createdb 创建库 canlogin 登录 replication 流复制 bypassrls 安全测试 RLS sysbackup 备份恢复 • backup_pri.user_sys_privs 查询出当前的用户的 sysbackup 权限和其他系统权限，若当前用户没有 sysbackup 权限，有可能显示的是空，或 者 nosysbackup 两种情况。 backup_pri.user_sys_privs 视图的每个字段意义如下表所示： 24 第8章 BACKUP_PRI 表 8.4.2: backup_pri.user_sys_privs 视图 列名 描述 username 用户名 userid 用户 id superuser 超级用户 inherit 继承 createrole 创建角色 createdb 创建库 canlogin 登录 replication 流复制 bypassrls 安全测试 RLS sysbackup 备份恢复 • backup_pri.role_sys_privs 查询出角色的 sysbackup 权限和其他系统权限，若角色没有 sysbackup 权限，有可能显示的是空，或者 nosysbackup 两种情况。 backup_pri.role_sys_privs 视图的每个字段意义如下表所示： 25 第8章 BACKUP_PRI 表 8.4.3: backup_pri.role_sys_privs 视图 8.5 列名 描述 rolename 角色名 roleid 角色 id superuser 超级用户 inherit 继承 createrole 创建角色 createdb 创建库 canlogin 登录 replication 流复制 bypassrls 安全测试 RLS sysbackup 备份恢复 插件 backup_pri 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例 shared_preload_libraries = '' 8.6 插件 backup_pri 升级方法 backup_pri 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 26 第 9 章 BLOOM 9 第 章 9.1 bloom 插件 bloom 简介 插件 bloom 是 KingbaseES 的一个扩展插件。bloom 提供了一种基于 bloom 过滤器的索引访问方法。 bloom 过滤器是一种节省空间的数据结构，用于测试元素是否是集合的成员。对于索引访问方法，它允许通过签 名快速排除不匹配的元组。签名的大小在索引创建是确定。 签名是索引属性的一种有损表示，并且因此容易报告误报。也就是说，当元素不在集合中时，可能会报告该元素 在集合中。因此，必须始终使用堆条目中实际属性值重新检查索引的搜索结果。更大的签名可以降低误报的机率。从 而减少无用的堆访问次数，但也会让索引更大，从而降低扫描速度。 当一个表有许多属性并且查询测试他们的任意组合时，这种类型的索引最有效，传统的 btree 索引比 bloom 索引 快，但它可能需要许多 btree 索引来支持所有可能的查询。而 bloom 索引只需要一个。请注意，bloom 索引只支持等 值查询，而 btree 索引也可以支持非等和范围查询。 • 插件名为 bloom • 插件版本 V1.0 9.2 插件 bloom 加载方式 KingbaseES 默认不加载 bloom 插件，需要用户使用示例中的命令，人为手工加载。 示例： create extension bloom; 9.3 插件 bloom 的参数配置 bloom 索引在其 WITH 子句中接受下列参数 27 第 9 章 BLOOM • length 每个签名（索引项）的长度位数，它会被圆整成为最近的 16 的倍数。默认是 80 位，最长是 4096 位。 • col1 —col32 从每一个索引列产生的位数。每个参数的名字表示它所控制的索引列的编号。默认是 2 位，最大是 4095 位。没 有实际使用的索引列的参数会被忽略。 9.4 插件 bloom 的使用方法 示例： 这是一个创建布鲁姆索引的例子。 CREATE INDEX bloomidx ON tbloom USING bloom (i1,i2,i3) WITH (length=80, col1=2, col2=2, col3=4); 该索引是用长度为 80 位的签名所创建，其中属性 i1 和 i2 被映射为 2 位，属性 i3 被映射为 4 位。我们可以省 略 length、col1 和 col2 说明，因为它们都有默认值。这里是布鲁姆索引定义和使用的更完整的例子，其中还与等效 的 btree 做了对比。布鲁姆索引比 btree 索引更小，并且效率更高。 9.5 插件 bloom 卸载方法 bloom 插件的卸载也需要用户使用示例中的命令，人为手工卸载。 示例： drop extension bloom; 9.6 插件 bloom 升级方法 bloom 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 28 第 10 章 CITEXT 10章 citext 第 10.1 插件 citext 简介 citext 定义了 citext 类型以及其相关函数。 • 插件名为 citext • 插件版本 V1.0 10.2 插件 citext 加载方式 使用时需要 create extension citext。 示例： create extension citext; 10.3 插件 citext 参数配置 无需配置任何参数 10.4 插件 citext 使用方法 10.4.1 regexp_matches regexp_matches-获得匹配的模式串集合 语法 29 第 10 章 CITEXT regexp_matches(c1 citext, c2 citext ) RETURNS SETOF TEXT[]。 regexp_matches(c1 citext, c2 citext, t1 text ) RETURNS SETOF TEXT[]。 描述 regexp_matches 会返回匹配的模式串集合。 参数 • c1 待匹配的字符串 • c2 正则表达式 • t1 匹配的模式 返回值 返回计算完成的特定的日期类型值。 注解 regexp_matches(c1 citext, c2 citext ) 相当于 regexp_matches(c1 citext, c2 citext, t1 text ) 的 t1 的值为’i’。t1 的参数为’c’ 代表大小写敏感,’g’ 允许输出多行等。 示例 SELECT regexp_matches('foobarbequebaz'::citext, '(BAR)(BEQUE)') = ARRAY[ 'bar', 'beque' ] AS t; t --t (1 row) SELECT regexp_matches('foobarbequebaz'::citext, '(BAR)(BEQUE)'::citext) = ARRAY[ 'bar', 'beque' ] AS t; t --t (1 row) 10.4.2 citext citext-将输入转换为 citext 类型并输出 语法 citext(bpchar) RETURNS citext。 citext(boolean) RETURNS citext。 citext(inet) RETURNS citext。 示例 30 第 10 章 CITEXT select citext('abc'bpchar); citext -------abc (1 行记录) 10.4.3 citext_eq citext_eq-对两个输入的 citext 类型进行比较，相等返回 true，不相等返回 false。。 语法 citext_eq(citext, citext) RETURNS bool。 示例 select citext_eq('as','ab'); citext_eq ----------f (1 行记录) 10.4.4 citext_ne(citext, citext) 与 citext_ne 的功能相反 10.4.5 citext_hash citext_hash-将输入的 citext 转换为 hash 值并输出。 语法 citext_hash(citext) RETURNS int4。 示例 select citext_hash('ab'); citext_hash ------------1718550461 (1 行记录) 31 第 10 章 CITEXT 10.4.6 支持两个 citext 类型 �,�,>,<, ＝,!= 等操作符的操作 示例 TEST=# select 'abd'::citext != 'abs'::citext; ?column? ---------t (1 行记录) TEST=# select 'abd'::citext = 'abs'::citext; ?column? ---------f (1 行记录) TEST=# select 'abd'::citext > 'abs'::citext; ?column? ---------f (1 行记录) TEST=# select 'abd'::citext >= 'abs'::citext; ?column? ---------f (1 行记录) TEST=# select 'abd'::citext >= 'abd'::citext; ?column? ---------t (1 行记录) 10.5 插件 citext 卸载方法 不需要 citext 插件只需要卸载插件即可。 示例： drop extension citext; 32 第 10 章 CITEXT 10.6 插件 citext 升级方法 citext 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 33 第 11 章 CSTORE_FDW 第 11.1 11章 cstore_fdw 插件 cstore_fdw 简介 cstore_fdw 是一款列存扩展插件。列存储在数据批量导入的分析场景能够提供更好的性能。cstore_fdw 通过只 读取磁盘上相关的列数据来提升性能。 同时，由于每列的数据来自同一个域，因此更利于数据压缩，cstore_fdw 提供 6~10 倍的数据压缩能力，从而减 小了对磁盘存储的需求。 cstore_fdw 采用 Optimized Row Columnar (ORC) 格式作为其数据的物理存储格式。ORC 优化了 Facebook 的 RCFile 存储格式，并具有以下优点： • 压缩 (Compression) - 大约减少了 2~4 倍的内存和磁盘存储空间。易于扩展以支持不同的编码。 • 列投影 (Column Projections) - 仅仅读取与该查询有关的数据列，提高了 I/O 效率。 • 跳跃索引 (Skip Indexes) - 为每个行组 (Row Groups) 存储其最大值和最小值，并利用他们来跳过不相关的数据 行。 KingbaseES 中通过 cstore_fdw 插件来实现列式存储及压缩。 • 插件名为 cstore_fdw • 插件版本 V1.7 11.2 插件 cstore_fdw 加载方式 启动 KingbaseES 数据库后执行 SQL 命令创建插件。 示例： CREATE EXTENSION cstore_fdw; 34 第 11 章 CSTORE_FDW 11.3 插件 cstore_fdw 的参数配置 无需配置任何参数 11.4 插件 cstore_fdw 的使用方法 以下四个选项可以在创建 cstore 外部表的时候指定： • filename (可选) 该参数存放列存表数据的绝对路径，如果没有指定该选项，那么 cstore_fdw 则采用默认的 $PGHOME/ cstore_fdw 来存储列存表数据。如果为该参数指定了值，则使用该值作为前缀来存储列存表数据信息。例如，当指 定的 filename 值为 /cstore_fdw/my_table，那么 cstore_fdw 将使用 /cstore_fdw/my_table 来存储列存表用户数 据，同时，使用 /cstore_fdw/my_table.footer 来存储列存表的元数据信息。 • compression (可选) 该 参 数 用 于 指 定 用 户 数 据 的 压 缩 算 法， 支 持 none，pglz，zstd（Zstandard 压 缩， 可 通 过 cstore_fdw.zstd_compression_level 设置压缩级别，级别范围 0~9，默认级别 1）和 dict（字典压缩）四个值， 默认值为 none。 • stripe_row_count (可选) 该参数指定每个 stripe 中行记录数，默认值为 150000。该值越小，加载数据或者查询时使用的内存也就越小， 相反，其性能也就越低。 • block_row_count (可选) - 该参数指定每个列数据块 (column block) 中的行记录数，默认为 10000。cstore_fdw 压缩数据、创建跳跃索引以及磁盘读取时都是以块 (block) 为最小单元。该值越大，则利用数据压缩，并可以减 少磁盘读取的次数量，然而，这将影响到跳过不相关的数据块的概率。 cstore_fdw 提供了两种方式用于向其导入数据： • 使用 COPY 命令将文件、程序或者标准输入中导入数据； • 使用 INSERT INTO cstore_table SELECT ... 语法从其他表导入数据。 我们可以使用 ANALYZE 命令收集列存表的统计信息，从而帮助优化器选择最优的查询计划。 注意: 1. cstore_fdw 目前并不支持使用 UPDATE 或 DELETE 命令来对表进行更新。同样，他也不支持单条记录的插 入，这是由于每次导入数据都会形成至少一个数据块，若是支持单条记录插入，那么每个 INSERT 命令插入一 条记录，将导致数据块过多从而影响性能，为此，cstore_fdw 不支持单条记录的插入。 2. cstore_fdw 目前不支持创建字段约束。如果在创建 cstore 外部表时定义了约束，该创建语句不会报错，但约束 条件无效。 35 第 11 章 CSTORE_FDW 11.4.1 示例 -- 安装 cstore_fdw CREATE EXTENSION cstore_fdw; CREATE SERVER cstore_server FOREIGN DATA WRAPPER cstore_fdw; -- 加载参数 LOAD 'cstore_fdw'; -- 查看当前 zstd 压缩级别参数值 show cstore_fdw.zstd_compression_level; cstore_fdw.zstd_compression_level ----------------------------------1 (1 row) -- 设置 zstd 压缩级别 SET cstore_fdw.zstd_compression_level = 3; show cstore_fdw.zstd_compression_level; cstore_fdw.zstd_compression_level ----------------------------------3 (1 row) -- 创建无压缩列式存储外部表并指定存储文件 CREATE FOREIGN TABLE contestant (handle TEXT, birthdate DATE, rating INT, percentile FLOAT, country CHAR(3), achievements TEXT[]) SERVER cstore_server OPTIONS(filename '/home/test/data/contestant.cstore'); -- 创建基于 pglz 压缩的列式存储外部表 CREATE FOREIGN TABLE contestant_compressed (handle TEXT, birthdate DATE, rating INT, percentile FLOAT, country CHAR(3), achievements TEXT[]) SERVER cstore_server OPTIONS(compression 'pglz'); -- 创建基于 zstd 压缩算法的列式存储外部表 CREATE FOREIGN TABLE contestant_zstd (handle TEXT, birthdate DATE, rating INT, percentile FLOAT, country CHAR(3), achievements TEXT[]) SERVER cstore_server OPTIONS(compression 'zstd'); -- 创建字典压缩算法的列式存储外部表 CREATE FOREIGN TABLE contestant_dict (handle TEXT, birthdate DATE, rating INT, percentile FLOAT, country CHAR(3), achievements TEXT[]) 36 第 11 章 CSTORE_FDW SERVER cstore_server OPTIONS(compression 'dict'); -- 导入数据 -- 从文件导入 COPY contestant FROM '/home/test/input/data/contestants.1.csv' WITH CSV; -- 从程序导入 COPY contestant FROM PROGRAM 'cat /home/test/input/data/contestants.2.csv' WITH CSV; --从标准输入导入 copy contestant (handle, birthdate, rating, percentile, country, achievements) from STDIN WITH CSV; c,1988-11-01,2907,99.4,XB ,"{w,y}" d,1985-05-05,2314,98.3,XB ,{} e,1995-05-05,2236,98.2,XC ,{a} \. -- 解析 ANALYZE contestant; --卸载 --卸载 cstore_fdw 之前，需要删除所有的 cstore 列存表、server 和扩展 DROP FOREIGN TABLE contestant; DROP FOREIGN TABLE contestant_compressed; DROP SERVER cstore_server; DROP EXTENSION cstore_fdw; 注意: cstore_fdw 会自动的创建目录来存储列存相关的数据，我们可以执行下面的命令来删除： $ rm -rf $KESDATA/cstore_fdw 上面给出的是 cstore_fdw 的默认路径，若在建表的时候指定了 filename，其位置可能不同。另外还需要移除 kingbase.conf 文件中 shared_preload_libraries 中的 cstore_fdw。 11.4.2 升级 cstore 表在使用 sys_upgrade 工具升级默认行为如下： • 传输模式为拷贝（copy） 用户指定 filename：在指定文件目录下，拷贝一份与成原文件相同的文件，文件名为加 _upg。新库继续使用原 文件。 用户不指定 filename：使用默认位置将旧库的数据目录下的 cstroe_fdw 目录下的数据文件拷贝到新库数据目录 37 第 11 章 CSTORE_FDW 下 cstore_fdw 目录下，新库使用新文件。 • 传输模式为克隆（clone） 用户指定 filename：在指定文件目录下，克隆一份与成原文件相同的文件，文件名为加 _upg。新库继续使用原 文件。 用户不指定 filename，使用默认位置将旧库的数据目录下的 cstroe_fdw 目录下的数据文件克隆到新库数据目录 下 cstore_fdw 目录下，新库使用新文件。 • 传输模式为连接（link） 用户指定 filename：在指定文件目录下，连接一份与成原文件相同的文件，文件名为加 _upg。新库继续使用原 文件。这里要注意，由于是连接，upg 文件也将随原文件一起变更。 用户不指定 filename：使用默认位置将旧库的数据目录下的 cstroe_fdw 目录下的数据文件连接到新库数据目录 下 cstore_fdw 目录下，新库使用新文件，这里要注意，由于是连接，新旧文件相互影响。 11.5 插件 cstore_fdw 卸载方法 在数据库中执行 SQL 命令卸载插件。 DROP EXTENSION cstore_fdw; 11.6 插件 cstore_fdw 升级方法 cstore_fdw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 38 第 12 章 CUBE 12章 cube 第 12.1 插件 cube 简介 这个模块实现了一种数据类型 cube 来表示多维立方体。 • 插件名为 cube • 插件版本 V1.4 12.2 插件 cube 加载方式 create extension cube; 12.3 插件 cube 的参数配置 无需配置任何参数 12.4 插件 cube 的使用方法 12.4.1 外部表示 在 表 12.4.1 展示了 cube 类型有效的外部表示。x、y 等表示浮点数。 39 第 12 章 CUBE 表 12.4.1: 立方体外部表示 外部语法 含义 x 一个一维点（或者长度为零的一维区间） (x) 同上 x1,x2,...,xn n-维空间中的一个点，内部表示为一个零容积立方体 (x1,x2,...,xn) 同上 (x),(y) 开始于 x 并且结束于 y 的一个一维区间，反之亦然。顺序并不重要 [(x),(y)] 同上 (x1,...,xn),(y1,...,yn) 一个 n-维立方体，用它的对角顶点对表示 [(x1,...,xn),(y1,...,yn)] 同上 一个立方体的对角录入的顺序无关紧要。如果需要创建一种统一的“左下—右上”的内部表示，cube 函数会自 动地交换值。当角重合时，cube 只存储一个角和一个“is point”标志，这样避免浪费空间。 输入中的空白空间会被忽略，因此 [(x),(y)] 与 [ ( x ), ( y ) ] 相同。 12.4.2 精度 值在内部被存储为 64 位浮点数。这意味着超过 16 位有效位的数字将被截断。 12.4.3 操作符 在 表 12.4.2 展示了为类型 cube 提供的操作符。 表 12.4.2: 立方体操作符 操作符 结果 描述 a=b boolean 立方体 a 和 b 相同。 a && b boolean 立方体 a 和 b 重叠。 a @> b boolean 立方体 a 包含立方体 b。 a <@ b boolean 立方体 a 被包含在立方体 b 中。 ab boolean 立方体 a 大于立方体 b。 a >= b boolean 立方体 a 大于或者等于立方体 b。 a <> b boolean 立方体 a 不等于立方体 b。 a -> n float8 得到立方体的第 n 个坐标（从 1 开始数）。 a ~> n float8 以下列方式获取多维数据集的第 n 个坐标 n = 2 * k - 1 表示第 k 维度的下限，n = 2 * k 表示第 k 维度的上限。负的 n 表示相应正坐标的倒数值。 此运算符专为 KNN-GiST 支持而设计。 标量排序操作符（<、>= 等）除了用来排序之外没有什么实际用途。这些操作符首先比较第一个坐标，如果它 们相等再比较第二个坐标等等。它们主要为支持 cube 的 b-树索引操作符类而存在，这类操作符对支持 cube 列上的 UNIQUE 约束等很有用。 cube 模块也为 cube 值提供了一个 GiST 索引操作符类。cube GiST 索引可以被用于在 WHERE 子句中通过 =、 &&、@>以及<@ 操作符来搜索值。 此外，cube GiST 索引可以被用在 ORDER BY 子句中通过度量操作符 <->、<#>和<=> 来查找最近邻。例 如，3-D 点 (0.5, 0.5, 0.5) 的最近邻可以用下面的查询很快地找到： create table test (c cube); insert into test values(cube(array[2,2,2])),(cube(array[3,3,3])); SELECT c FROM test ORDER BY c <-> cube(array[0.5,0.5,0.5]) LIMIT 1; c ----------(2, 2, 2) (1 row) 也可以用这种方式使用 ~> 操作符来高效地检索通过选定坐标排序后的前几个值。例如，可以用下面的查询得到 通过第一个坐标（左下角）升序排列后的前几个立方体： SELECT c FROM test ORDER BY c ~> 1 LIMIT 5; c ----------(2, 2, 2) (3, 3, 3) (2 rows) 41 第 12 章 CUBE 以及得到通过右上角第一个坐标降序排列后的二维立方体： SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; c ----------(3, 3, 3) (2, 2, 2) (2 rows) 12.4.4 函数 表 12.4.3 显示了可用的函数： 表 12.4.3: 立方体函数 函数 结果 描述 例子 cube(float8) cube 制造一个一维立方体，坐标都是 cube(1) == ’(1)’ 相同的。 cube(float8, float8) cube 制造一个一维立方体。 cube(1,2) == ’(1),(2)’ cube(float8[]) cube 使用数组定义的坐标制造一个零 cube(ARRAY[1,2]) == ’(1,2)’ 容积的立方体。 cube(float8[], float8[]) cube 用由两个数组定义的右上和左下 cube(ARRAY[1,2], ARRAY[3,4]) 坐标制造一个立方体，两个数组 == ’(1,2),(3,4)’ 必须等长。 cube(cube, float8) cube 在一个现有的立方体上增加一维 cube(’(1,2), (3,4)’::cube, 5) == 来制造一个新立方体，对新坐标 ’(1,2,5),(3,4,5)’ 的各个端点都采用相同的值。这 可以用于从计算得到的值逐渐地 构建立方体。 cube(cube, float8, float8) cube 在一个现有的立方体上增加一维 cube(’(1,2),(3,4)’::cube, 5, 6) == 来制造一个新立方体。这可以用 ’(1,2,5),(3,4,6)’ 于从计算得到的值逐渐地构建立 方体。 cube_dim(cube) integer 返回该立方体的维数 cube_dim(’(1,2),(3,4)’) == ’2’ cube_ll_coord(cube, inte- float8 返回一个立方体的左下角的第 n cube_ll_coord(’(1,2), (3,4)’, 个坐标值 == ’2’ ger) 2) 见续表 42 第 12 章 CUBE 表 12.4.3 – 续表 函数 结果 描述 例子 cube_ur_coord(cube, in- float8 返回一个立方体的右上角的第 n cube_ur_coord(’(1,2), (3,4)’, 个坐标值 == ’4’ teger) cube_is_point(cube) boolean 2) 如果一个立方体是一个点则返回 真，也就是两个定义点相同。 cube_distance(cube, float8 返回两个立方体之间的距离。如 果两个都是点，这就是普通距离 cube) 函数。 cube_subset(cube, inte- cube ger[]) 从一个现有的立方体制造一个新 cube_subset(cube(’(1,3,5), 立方体，使用来自于一个数组的 (6,7,8)’), ARRAY[2]) == ’(3), 维索引列表。它可以被用来抽取 (7)’ 一个单一维度的端点，或者它可 (6,7,8)’), 以被用来去除维度，或者按照需 ’(5,3,1,1),(8,7,6,6)’ cube_subset(cube(’(1,3,5), ARRAY[3,2,1,1]) == 要对它们重新排序。 cube_union(cube, cube) cube 产生两个立方体的并 cube_inter(cube, cube) cube 产生两个立方体的交 cube 用一个指定的半径 r 在至少 n cube_enlarge(’(1,2),(3,4)’, 0.5, 3) 个维度上增加立方体的尺寸。如 == ’(0.5,1.5,-0.5),(3.5,4.5,0.5)’ cube_enlarge(c cube, double, n integer) r 果该半径是负值，则该立方体会 收缩。这有助于围绕一个点创建 一个外包盒来搜索附近点。所有 已定义的维度都会按照半径 r 被 改变。左下坐标按照 r 被减小并 且右上坐标按照 r 被增加。如果 一个左下坐标被增加得超过对应 的右上坐标（这只会发生在 r< 0 时），则两个坐标会被设置为 它们的均值。如果 n 大于已定义 的维度数并且该立方体被增加（r >= 0），则额外的维度会被加入 以让维度数达到 n，对于额外的 坐标将使用 0 作为初始值。这个 函数可用来创建围绕一个点的外 包盒以搜索临近点。 43 第 12 章 CUBE 12.4.5 默认值 以下为并操作： select cube_union('(0,5,2),(2,3,1)', '0'); cube_union ------------------(0, 0, 0),(2, 5, 2) (1 row) 以下为交操作： select cube_inter('(0,-1),(1,1)', '(-2),(2)'); cube_inter ------------(0, 0),(1, 0) (1 row) 在所有不同维度立方体的二元操作中，我假定低纬度的那一个要做笛卡尔投影，即为字符串表示中被省略的坐标 取零。上面的例子等同于： cube_union('(0,5,2),(2,3,1)','(0,0,0),(0,0,0)'); cube_inter('(0,-1),(1,1)','(-2,0),(2,0)'); 下列包含谓词使用点语法，不过实际上第二个参数在内部被表示为一个盒体。这种语法让我们不必定义一种单独 的点类型以及用于（盒体, 点）谓词的函数。 select cube_contains('(0,0),(1,1)', '0.5,0.5'); cube_contains -------------t (1 row) 注意: 用法的例子可见回归测试 sql/cube.sql。为了不容易出问题，对于立方体的维度数有 100 的限制。如果你想要 更大的立方体，可以在 cubedata.h 中修改。 12.5 插件 cube 的卸载方法 drop extension cube; 44 第 12 章 CUBE 12.6 插件 cube 升级方法 cube 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 45 第 13 章 DBLINK 13章 dblink 第 13.1 插件 dblink 简介 dblink 是 KingbaseES 的一个扩展插件，支持在一个数据库会话中连接到其他 Kingbase 数据库的模块。 还可以参考kingbase_fdw，它以一种更现代和更加兼容标准的架构提供了相同的功能。 • 插件名为 dblink • 插件版本 V1.2 13.2 插件 dblink 加载方式 CREATE EXTENSION dblink; 13.3 插件 dblink 的参数配置 无需配置任何参数。 13.4 插件 dblink 使用方法 13.4.1 dblink_connect dblink_connect —打开一个到远程数据库的持久连接 语法 46 第 13 章 DBLINK dblink_connect(text connstr) 返回 text dblink_connect(text connname, text connstr) 返回 text 描述 dblink_connect() 建立一个到远程 KingbaseES 数据库的连接。要连接的服务器和数据库通过一个标准的 libpq 连接串来标识。可以选择将一个名字赋予给该连接。多个命名的连接可以被一次打开，但是一次只允许一个未命名连 接。连接将会持续直到被关闭或者数据库会话结束。 连接串也可以是一个现存外部服务器的名字。在使用外部服务器时，推荐使用外部数据包装器 dblink_fdw。见 下面的例子，以及 CREATE SERVER 和 CREATE USER MAPPING。 参数 connname 要用于这个连接的名字。如果被忽略，将打开一个未命名连接并且替换掉任何现有的未命名连接。 connstr libpq-风格的连接信息串，例如 hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd。此外，还可以是一个外部服务器的名字。 返回值 返回状态，它总是 OK（因为任何错误会导致该函数抛出一个错误而不是返回）。 注解 如果不可信用户能够访问一个没有采用安全方案使用模式的数据库，应该在开始每个会话时从 search_path 中移 除公共可写的方案。例如，可以把 options=-csearch_path= 增加到 connstr。这种考虑不是特别针对 dblink，它适用 于每一种执行任意 SQL 命令的接口。 只 有 超 级用 户能 够 使 用 dblink_connect 来创建 无 口 令 认证 连 接。 如果 非超 级 用户需 要 这 种能 力， 使 用 dblink_connect_u。 选择包含等号的连接名是不明智的，因为这会产生与在其他 dblink 函数中的连接信息串混淆的风险。 示例 SELECT dblink_connect('hostaddr=127.0.0.1 port=54321 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_connect('myconn', 'hostaddr=127.0.0.1 port=54321 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) 47 第 13 章 DBLINK -- FOREIGN DATA WRAPPER functionality -- 注意: local connection must require password authentication for this to work properly -- Otherwise, you will receive the following error from dblink_connect(): -- ---------------------------------------------------------------------- -- ERROR: password is required -- DETAIL: Non-superuser cannot connect if the server does not request a password. -- HINT: Target server's authentication method must be changed. CREATE SERVER fdtest FOREIGN DATA WRAPPER dblink_fdw OPTIONS (hostaddr '127.0.0.1', dbname 'contrib_regression'); CREATE USER regress_dblink_user WITH PASSWORD 'secret'; CREATE USER MAPPING FOR regress_dblink_user SERVER fdtest OPTIONS (user 'regress_dblink_user', password 'secret'); GRANT USAGE ON FOREIGN SERVER fdtest TO regress_dblink_user; GRANT SELECT ON TABLE foo TO regress_dblink_user; \set ORIGINAL_USER :USER \c - regress_dblink_user SELECT dblink_connect('myconn', 'fdtest'); dblink_connect ---------------OK (1 row) SELECT * FROM dblink('myconn','SELECT * FROM foo') AS t(a int, b text, c text[]); a | b | c ----+---+--------------0 | a | {a0,b0,c0} 1 | b | {a1,b1,c1} 2 | c | {a2,b2,c2} 3 | d | {a3,b3,c3} 4 | e | {a4,b4,c4} 5 | f | {a5,b5,c5} 6 | g | {a6,b6,c6} 7 | h | {a7,b7,c7} 8 | i | {a8,b8,c8} 9 | j | {a9,b9,c9} 10 | k | {a10,b10,c10} (11 rows) 48 第 13 章 DBLINK \c - :ORIGINAL_USER REVOKE USAGE ON FOREIGN SERVER fdtest FROM regress_dblink_user; REVOKE SELECT ON TABLE foo FROM regress_dblink_user; DROP USER MAPPING FOR regress_dblink_user SERVER fdtest; DROP USER regress_dblink_user; DROP SERVER fdtest; 13.4.2 dblink_connect_u dblink_connect_u —不安全地打开一个到远程数据库的持久连接 语法 dblink_connect_u(text connstr) 返回 text dblink_connect_u(text connname, text connstr) 返回 text 描述 dblink_connect_u() 和 dblink_connect() 一样，不过它将允许非超级用户使用任意认证方式来连接。 如果远程服务器选择了一种不涉及口令的认证方式，那么可能发生模仿以及后续的扩大权限，因为该会话看起来 像由运行 KingbaseES 的用户发起的。此外，即使远程服务器不要求一个口令，也可能从服务器环境提供该口令，例 如一个属于服务器用户的 ~/.kbpass 文件。这带来的不只是模仿的风险，而且还有将口令暴露给不可信的远程服务器 的风险。因此，dblink_connect_u() 最初是用所有从 PUBLIC 撤销的特权安装的，这让它只能被超级用户调用。在 某些情况中，为 dblink_connect_u() 授予 EXECUTE 权限给可信的指定用户是合适的，但是必须小心。我们也推荐 任何属于服务器用户的 ~/.kbpass 文件不能包含任何指定了一个通配符主机名的记录。 详见 dblink_connect()。 13.4.3 dblink_disconnect dblink_disconnect —关闭一个到远程数据库的持久连接 语法 dblink_disconnect() 返回 text dblink_disconnect(text connname) 返回 text 描述 dblink_disconnect() 关闭一个之前被 dblink_connect() 打开的连接。不带参数的形式关闭一个未命名连接。 参数 connname 要被关闭的命名连接的名字。 49 第 13 章 DBLINK 返回值 它总是 OK（因为任何错误会导致该函数抛出一个错误而不是返回）。 示例 SELECT dblink_disconnect(); dblink_disconnect ------------------OK (1 row) SELECT dblink_disconnect('myconn'); dblink_disconnect ------------------OK (1 row) 13.4.4 dblink dblink —在一个远程数据库中执行一个查询 语法 dblink(text connname, text sql [, bool fail_on_error]) 返回记录集 dblink(text connstr, text sql [, bool fail_on_error]) 返回记录集 dblink(text sql [, bool fail_on_error]) 返回记录集 描述 dblink 在一个远程数据库中执行一个查询（通常是一个 SELECT，但是也可以是任意返回行的 SQL 语句）。 当给定两个 text 参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被 执行。如果没有找到，第一个参数被视作一个用于 dblink_connect 的连接信息字符串，并且被指出的连接只是在这 个命令的持续期间被建立。 参数 connname 要使用的连接名。忽略这个参数将使用未命名连接。 connstr 如之前为 dblink_connect 所描述的一个连接信息字符串。 sql 希望在远程数据库中执行的 SQL 查询，例如 select * from foo。 fail_on_error 50 第 13 章 DBLINK 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数不返回行。 返回值 该函数返回查询产生的行。因为 dblink 能与任何查询一起使用，它被声明为返回 record，而不是指定任意特定 的列集合。这意味着你必须指定在调用的查询中所期待的列集合，否则 KingbaseES 将不知道会得到什么。这里是一 个例子 SELECT * FROM dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd', 'select proname, prosrc from sys_proc') AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; FROM 子句的“alias”部分必须指定函数将返回的列名及类型（在一个别名中指定列名实际上是标准 SQL 语 法，但是指定列类型是一种 KingbaseES 扩展）。这允许系统在尝试执行该函数之前就理解 * 将展开成什么，以及 WHERE 子句中的 proname 指的什么。在运行时，如果来自远程数据库的实际查询结果和 FROM 子句中显示的列数 不同，将会抛出一个错误。不过，列名不需要匹配，并且 dblink 并不坚持精确地匹配类型。只要被返回的数据字符 串是 FROM 子句中声明的列类型的合法输入，它就将会成功。 注解 一种将预定义查询用于 dblink 的方法是创建一个视图。这允许列类型信息被埋藏在该视图中，而不是在每一个 查询中都拼写出来。例如 CREATE VIEW myremote_sys_proc AS SELECT * FROM dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd', 'select proname, prosrc from sys_proc') AS t1(proname name, prosrc text); SELECT * FROM myremote_sys_proc WHERE proname LIKE 'bytea%'; 示例 SELECT * FROM dblink('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd', 'select proname, prosrc from sys_proc') AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; proname | prosrc ------------+-----------byteacat | byteacat byteaeq | byteaeq bytealt | bytealt byteale | byteale byteagt | byteagt byteage | byteage 51 第 13 章 DBLINK byteane | byteane byteacmp | byteacmp bytealike | bytealike byteanlike | byteanlike byteain | byteain byteaout | byteaout (12 rows) SELECT dblink_connect('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT * FROM dblink('select proname, prosrc from sys_proc') AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; proname | prosrc ------------+-----------byteacat | byteacat byteaeq | byteaeq bytealt | bytealt byteale | byteale byteagt | byteagt byteage | byteage byteane | byteane byteacmp | byteacmp bytealike | bytealike byteanlike | byteanlike byteain | byteain byteaout | byteaout (12 rows) SELECT dblink_connect('myconn', 'hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT * FROM dblink('myconn', 'select proname, prosrc from sys_proc') AS t1(proname name, prosrc text) WHERE proname LIKE 'bytea%'; proname | prosrc ------------+-----------bytearecv | bytearecv byteasend | byteasend byteale | byteale 52 第 13 章 DBLINK byteagt | byteagt byteage | byteage byteane | byteane byteacmp | byteacmp bytealike | bytealike byteanlike | byteanlike byteacat | byteacat byteaeq | byteaeq bytealt | bytealt byteain | byteain byteaout | byteaout (14 rows) 13.4.5 dblink_exec dblink_exec —在一个远程数据库中执行一个命令 语法 dblink_exec(text connname, text sql [, bool fail_on_error]) returns text dblink_exec(text connstr, text sql [, bool fail_on_error]) returns text dblink_exec(text sql [, bool fail_on_error]) returns text 描述 dblink_exec 在一个远程数据库中执行一个命令（也就是，任何不返回行的 SQL 语句）。 当给定两个 text 参数时，第一个被首先作为一个持久连接的名称进行查找；如果找到，该命令会在该连接上被 执行。如果没有找到，第一个参数被视作一个用于 dblink_connect 的连接信息字符串，并且被指出的连接只是在这 个命令的持续期间被建立。 参数 connname 要使用的连接名。忽略这个参数将使用未命名连接。 connstr 如之前为 dblink_connect 所描述的一个连接信息字符串。 sql 希望在远程数据库中执行的 SQL 命令，例如 insert into foo values(0,’a’,’{”a0”,”b0”,”c0”}’)。 fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为 ERROR。 53 第 13 章 DBLINK 返回值 返回状态，可能是命令的状态字符串或 ERROR。 示例 SELECT dblink_connect('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_exec('insert into foo values(21,''z'',''{"a0","b0","c0"}'');'); dblink_exec ----------------INSERT 943366 1 (1 row) SELECT dblink_connect('myconn', 'hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_exec('myconn', 'insert into foo values(21,''z'',''{"a0","b0","c0"}'');'); dblink_exec -----------------INSERT 6432584 1 (1 row) SELECT dblink_exec('myconn', 'insert into sys_class values (''foo'')',false); NOTICE: sql error DETAIL: ERROR: null value in column "relnamespace" violates not-null constraint dblink_exec ------------ERROR (1 row) 13.4.6 dblink_open dblink_open —在一个远程数据库中打开一个游标 语法 54 第 13 章 DBLINK dblink_open(text cursorname, text sql [, bool fail_on_error]) 返回 text dblink_open(text connname, text cursorname, text sql [, bool fail_on_error]) 返回 text 描述 dblink_open() 在一个远程数据库中打开一个游标。该游标能够随后使用 dblink_fetch() 和 dblink_close() 进行 操纵。 参数 connname 要使用的连接名。忽略这个参数将使用未命名连接。 cursorname 要赋予给这个游标的名称。 sql 希望在远程数据库中执行的 SELECT 语句，例如 select * from sys_class。 fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为 ERROR。 返回值 返回状态，OK 或者 ERROR。 注解 因为一个游标只能在一个事务中持续，如果远端还没有在一个事务中，dblink_open 会在远端开始一个显式 事务块（BEGIN）。当匹配的 dblink_close 被执行时，这个事务将再次被关闭。注意如果你使用 dblink_exec 在 dblink_open 和 dblink_close 之间改变数据，并且接着发生了一个错误或者你在 dblink_close 之前使用了 dblink_disconnect，你的更改将被丢失，因为事务将被中止。 示例 SELECT dblink_connect('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_open('foo', 'select proname, prosrc from sys_proc'); dblink_open ------------OK (1 row) 55 第 13 章 DBLINK 13.4.7 dblink_fetch dblink_fetch —从一个远程数据库中的打开的游标返回行 语法 dblink_fetch(text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合 dblink_fetch(text connname, text cursorname, int howmany [, bool fail_on_error]) 返回 record 集合 描述 dblink_fetch 从一个之前由 dblink_open 建立的游标中取得行。 参数 connname 要使用的连接名。忽略这个参数将使用未命名连接。 cursorname 要从中取数据的游标名。 howmany 要检索的最大行数。从当前游标位置向前的接下来 howmany 个行会被取出。一旦该游标已经到达了它的 末端，将不会产生更多行。 fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为 ERROR。 返回值 该函数返回从游标中取出的行。要使用这个函数，你将需要指定想要的列集合，如前面 dblink 中所讨论的。 注解 当 FROM 子句中指定的返回列的数量和远程游标返回的实际列数不匹配时，将抛出一个错误。在这个事件中， 远程游标仍会被前进错误没发生时应该前进的行数。对于远程 FETCH 完成之后在本地查询中发生的任何其他错误， 情况也是一样。 示例 SELECT dblink_connect('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_open('foo', 'select proname, prosrc from sys_proc where proname like ''bytea%'''); 56 第 13 章 DBLINK dblink_open ------------OK (1 row) SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source ----------+---------byteacat | byteacat byteacmp | byteacmp byteaeq | byteaeq byteage | byteage byteagt | byteagt (5 rows) SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source -----------+----------byteain | byteain byteale | byteale bytealike | bytealike bytealt | bytealt byteane | byteane (5 rows) SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source ------------+-----------byteanlike | byteanlike byteaout | byteaout (2 rows) SELECT * FROM dblink_fetch('foo', 5) AS (funcname name, source text); funcname | source ----------+-------(0 rows) 13.4.8 dblink_close dblink_close —关闭一个远程数据库中的游标 语法 57 第 13 章 DBLINK dblink_close(text cursorname [, bool fail_on_error]) 返回 text dblink_close(text connname, text cursorname [, bool fail_on_error]) 返回 text 描述 dblink_close 关闭一个之前由 dblink_open 打开的游标。 参数 connname 要使用的连接名。忽略这个参数将使用未命名连接。 cursorname 要关闭的游标名。 fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数的返回值被设置为 ERROR。 返回值 返回状态，OK 或者 ERROR。 注解 如果 dblink_open 开始了一个显式事务块，并且这是这个连接中最后一个保持打开的游标，dblink_close 将发出 匹配的 COMMIT。 示例 SELECT dblink_connect('hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) SELECT dblink_open('foo', 'select proname, prosrc from sys_proc'); dblink_open ------------OK (1 row) SELECT dblink_close('foo'); dblink_close -------------OK (1 row) 58 第 13 章 DBLINK 13.4.9 dblink_get_connections dblink_get_connections —返回所有打开的命名 dblink 连接的名称 语法 dblink_get_connections() 返回 text[] 描述 dblink_get_connections 返回一个数组，其中是所有打开的命名 dblink 连接的名称。 返回值 返回一个连接名称的文本数组，如果没有则为 NULL。 示例 SELECT dblink_get_connections(); 13.4.10 dblink_error_message dblink_error_message —得到在命名连接上的最后一个错误消息 语法 dblink_error_message(text connname) 返回 text 描述 dblink_error_message 为一个给定连接取得最近的远程错误消息。 参数 connname 要使用的连接名。 返回值 返回最后一个错误消息，如果在这个连接上没有错误则返回一个 OK。 注解 当异步查询由 dblink_send_query 启动时，与连接相关的错误消息可能不会得到更新，直到服务器的响应消息被 用掉。这通常意味着 dblink_is_busy 或 dblink_get_result 应在 dblink_error_message 之前被调用，以使得异步查 询产生的任何错误都是可见的。 示例 SELECT dblink_error_message('dtest1'); 59 第 13 章 DBLINK 13.4.11 dblink_send_query dblink_send_query —发送一个异步查询到远程数据库 语法 dblink_send_query(text connname, text sql) 返回 int 描述 dblink_send_query 发送一个要被异步执行的查询，也就是不需要立即等待结果。在该连接上不能有还在处理中 的异步查询。 在成功地派送一个异步查询后，可以用 dblink_is_busy 检查完成状态，并且结果最终由 dblink_get_result 收 集。也可以使用 dblink_cancel_query 尝试取消一个活动中的异步查询。 参数 connname 要使用的连接名。 sql 希望在远程数据库中执行的 SQL 语句，例如 select * from sys_class。 返回值 如果查询被成功地派送返回 1，否则返回 0。 示例 SELECT dblink_send_query('dtest1', 'SELECT * FROM foo WHERE f1 < 3'); 13.4.12 dblink_is_busy dblink_is_busy —检查连接是否正在忙于一个异步查询 语法 dblink_is_busy(text connname) 返回 int 描述 dblink_is_busy 测试是否一个异步查询正在进行中。 参数 connname 要检查的连接名。 60 第 13 章 DBLINK 返回值 如果连接正忙则返回 1，如果不忙则返回 0。如果这个函数返回 0，dblink_get_result 将被保证不会阻塞。 示例 SELECT dblink_is_busy('dtest1'); 13.4.13 dblink_get_notify dblink_get_notify —在一个连接上检索异步通知 语法 dblink_get_notify() 返回 (notify_name text, be_pid int, extra text) 集合 dblink_get_notify(text connname) 返回 (notify_name text, be_pid int, extra text) 集合 描述 dblink_get_notify 在一个未命名连接或者一个指定的命名连接上检索通知。要通过 dblink 接收通知，首先必须 使用 dblink_exec 发出 LISTEN。详见 LISTEN 和 NOTIFY。 参数 connname 要在其上得到通知的命名连接的名称。 返回值 返回 (notify_name text, be_pid int, extra text) 集合，或者一个空集。 示例 SELECT dblink_exec('LISTEN virtual'); dblink_exec ------------LISTEN (1 row) SELECT * FROM dblink_get_notify(); notify_name | be_pid | extra -------------+--------+------(0 rows) NOTIFY virtual; NOTIFY SELECT * FROM dblink_get_notify(); 61 第 13 章 DBLINK notify_name | be_pid | extra -------------+--------+------virtual | 1229 | (1 row) 13.4.14 dblink_get_result dblink_get_result —得到一个异步查询结果 语法 dblink_get_result(text connname [, bool fail_on_error]) 返回 record 集合 描述 dblink_get_result 收集之前 dblink_send_query 发送的一个异步查询的结果。如果该查询还没有完成， dblink_get_result 将等待直到它完成。 参数 connname 要使用的连接名。 fail_on_error 如果为真（忽略时的默认值），那么在连接的远端抛出的一个错误也会导致本地抛出一个错误。如果为 假，远程错误只在本地被报告为一个 NOTICE，并且该函数不返回行。 返回值 对于一个异步查询（也就是一个返回行的 SQL 语句），该函数返回查询产生的行。要使用这个函数，你将需要 指定所期待的列集合，如前面为 dblink 所讨论的那样。 对于一个异步命令（也就是一个不返回行的 SQL 语句），该函数返回一个只有单个文本列的单行，其中包含了 该命令的状态字符串。仍必须在调用的 FROM 子句中指定结果将具有一个单一文本行。 注解 如果 dblink_send_query 返回 1，这个函数就必须被调用。对每一个已发送的查询都必须调用一次这个函数，且 在连接再次可用之前还要多调用一次来得到一个空结果集。 当使用 dblink_send_query 和 dblink_get_result 时，在将结果集中的任何一行返回给本地查询处理器之前， dblink 将取得整个远程查询结果。如果该查询返回大量的行，这可能会导致本地会话中短暂的内存膨胀。最好将这样 的一个查询用 dblink_open 打开成一个游标并且接着每次取得数量可管理的行。也可以使用简单的 dblink()，它会避 免缓冲大型结果集到磁盘上导致的内存膨胀。 示例 62 第 13 章 DBLINK contrib_regression=# SELECT dblink_connect('dtest1', 'hostaddr=127.0.0.1 port=5432 dbname=mydb user=myname password=mypasswd'); dblink_connect ---------------OK (1 row) contrib_regression=# SELECT * FROM contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 < 3') AS t1; t1 ---1 (1 row) contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); f1 | f2 | f3 ----+----+-----------0 | a | {a0,b0,c0} 1 | b | {a1,b1,c1} 2 | c | {a2,b2,c2} (3 rows) contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); f1 | f2 | f3 ----+----+---(0 rows) contrib_regression=# SELECT * FROM contrib_regression-# dblink_send_query('dtest1', 'select * from foo where f1 < 3; select * from foo where f1 > 6') AS t1; t1 ---1 (1 row) contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); f1 | f2 | f3 ----+----+-----------0 | a | {a0,b0,c0} 1 | b | {a1,b1,c1} 2 | c | {a2,b2,c2} 63 第 13 章 DBLINK (3 rows) contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); f1 | f2 | f3 ----+----+--------------7 | h | {a7,b7,c7} 8 | i | {a8,b8,c8} 9 | j | {a9,b9,c9} 10 | k | {a10,b10,c10} (4 rows) contrib_regression=# SELECT * FROM dblink_get_result('dtest1') AS t1(f1 int, f2 text, f3 text[]); f1 | f2 | f3 ----+----+---(0 rows) 13.4.15 dblink_cancel_query dblink_cancel_query —在命名连接上取消任何活动查询 语法 dblink_cancel_query(text connname) 返回 text 描述 dblink_cancel_query 尝试取消命名连接上正在进行的任何查询。注意这不一定会成功（例如，远程查询可能 已经结束）。一个取消请求仅仅提高了该查询将很快失败的几率。你仍必须完成通常的查询协议，例如通过调用 dblink_get_result。 参数 connname 要使用的连接名。 返回值 如果取消请求已经被发送，则返回 OK；如果失败，则返回一个错误消息的文本。 示例 SELECT dblink_cancel_query('dtest1'); 64 第 13 章 DBLINK 13.4.16 dblink_get_pkey dblink_get_pkey —返回一个关系的主键域的位置和域名称 语法 dblink_get_pkey(text relname) 返回 dblink_pkey_results 集合 描述 dblink_get_pkey 提供有关于本地数据库中一个关系的主键的信息。这有时候有助于生成要被发送到远程数据库 的查询。 参数 relname 一个本地关系的名称，例如 foo 或者 myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要 包括双引号，例如”FooBar”；如果没有引号，字符串将被折叠到小写形式。 返回值 为每一个主键域返回一行，如果该关系没有主键则不返回行。结果行类型被定义为 CREATE TYPE dblink_pkey_results AS (position int, colname text); position 列值可以从 1 到 N，它是该域在主键中的编号，而不是在表列中的编号。 示例 CREATE TABLE foobar ( f1 int, f2 int, f3 int, PRIMARY KEY (f1, f2, f3) ); SELECT * FROM dblink_get_pkey('foobar'); position | colname ----------+--------1 | f1 2 | f2 3 | f3 (3 rows) 13.4.17 dblink_build_sql_insert dblink_build_sql_insert —使用一个本地元组构建一个 INSERT 语句，将主键域值替换为提供的值 65 第 13 章 DBLINK 语法 dblink_build_sql_insert(text relname, int2vector primary_key_attnums, integer num_primary_key_atts, text[] src_pk_att_vals_array, text[] tgt_pk_att_vals_array) 返回 text 描述 dblink_build_sql_insert 在选择性地将一个本地表复制到一个远程数据库时很有用。它基于主键从本地表选择一 行，并且接着构建一个复制该行的 INSERT 命令，但是其中主键值被替换为最后一个参数中的值（要创建该行的一 个准确拷贝，只要为最后两个参数指定相同的值）。 参数 relname 一个本地关系的名称，例如 foo 或者 myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要 包括双引号，例如”FooBar”；如果没有引号，字符串将被折叠到小写形式。 primary_key_attnums 主键域的属性号（从 1 开始），例如 1 2。 num_primary_key_atts 主键域的数量。 src_pk_att_vals_array 要被用来查找本地元组的主键域值。每一个域都被表示为文本形式。如果没有行具有这些主键值，则抛出 一个错误。 tgt_pk_att_vals_array 要被替换到结果 INSERT 命令中的主键域值。每一个域被表示为文本形式。 返回值 将要求的 SQL 语句返回为文本。 注解 自 KingbaseES 9.0 开始，primary_key_attnums 中的属性号被解释为逻辑列号，对应于列在 SELECT * FROM relname 中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删 除，这两种解释就有区别。 示例 SELECT dblink_build_sql_insert('foo', '1 2', 2, '{"1", "a"}', '{"1", "b''a"}'); dblink_build_sql_insert -------------------------------------------------- 66 第 13 章 DBLINK INSERT INTO foo(f1,f2,f3) VALUES('1','b''a','1') (1 row) 13.4.18 dblink_build_sql_delete dblink_build_sql_delete —使用所提供的主键域值构建一个 DELETE 语句 语法 描述 dblink_build_sql_delete 在选择性地将一个本地表复制到一个远程数据库时很有用。它构建一个 SQL DELETE 命令用来删除具有给定主键值的行。 参数 relname 一个本地关系的名称，例如 foo 或者 myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要 包括双引号，例如”FooBar”；如果没有引号，字符串将被折叠到小写形式。 primary_key_attnums 主键域的属性号（从 1 开始），例如 1 2。 num_primary_key_atts 主键域的数量。 tgt_pk_att_vals_array 要用在结果 DELETE 命令中的主键域值。每一个域都被表示为文本形式。 返回值 将要求的 SQL 语句返回为文本。 注解 自 KingbaseES 9.0 开始，primary_key_attnums 中的属性号被解释为逻辑列号，对应于列在 SELECT * FROM relname 中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删 除，这两种解释就有区别。 示例 SELECT dblink_build_sql_delete('"MyFoo"', '1 2', 2, '{"1", "b"}'); dblink_build_sql_delete --------------------------------------------DELETE FROM "MyFoo" WHERE f1='1' AND f2='b' (1 row) 67 第 13 章 DBLINK 13.4.19 dblink_build_sql_update dblink_build_sql_update —使用一个本地元组构建一个 UPDATE 语句，将主键域值替换为提供的值 语法 dblink_build_sql_update(text relname, int2vector primary_key_attnums, integer num_primary_key_atts, text[] src_pk_att_vals_array, text[] tgt_pk_att_vals_array) 返回 text 描述 dblink_build_sql_update 在选择性地将一个本地表复制到一个远程数据库时很有用。它从本地表基于主键选择 一行，并且接着构建一个 SQL UPDATE 命令来复制该行，但是其中的主键值被替换为最后一个参数中的值（要创建 该行的一个准确拷贝，只要为最后两个参数指定相同的值）。UPDATE 命令总是为该行的所有域赋值—这个函数与 dblink_build_sql_insert 之间的主要区别是它假定目标行已经存在于远程表中。 参数 relname 一个本地关系的名称，例如 foo 或者 myschema.mytab。如果该名称是大小写混合的或包含特殊字符，要 包括双引号，例如”FooBar”；如果没有引号，字符串将被折叠到小写形式。 primary_key_attnums 主键域的属性号（从 1 开始），例如 1 2。 num_primary_key_atts 主键域的数量。 src_pk_att_vals_array 要被用来查找本地元组的主键域值。每一个域都被表示为文本形式。如果没有行具有这些主键值，则抛出 一个错误。 tgt_pk_att_vals_array 要用在结果 UPDATE 命令中的主键域值。每一个域都被表示为文本形式。 返回值 将要求的 SQL 语句返回为文本。 注解 自 KingbaseES 9.0 开始，primary_key_attnums 中的属性号被解释为逻辑列号，对应于列在 SELECT * FROM relname 中的位置。之前的版本将属性号解释为物理列位置。如果指示出的列的左边有任意列在该表的生存期内被删 除，这两种解释就有区别。 示例 68 第 13 章 DBLINK SELECT dblink_build_sql_update('foo', '1 2', 2, '{"1", "a"}', '{"1", "b"}'); dblink_build_sql_update ------------------------------------------------------------UPDATE foo SET f1='1',f2='b',f3='1' WHERE f1='1' AND f2='b' (1 row) 13.5 插件 dblink 卸载方法 DROP EXTENSION dblink; 13.6 插件 dblink 升级方法 ALTER EXTENSION dblink UPDATE; 69 第 14 章 DBMS_DDL 14章 dbms_ddl 第 14.1 插件 dbms_ddl 简介 插件 dbms_ddl 是 KingbaseES 的一个扩展插件。插件 dbms_ddl 功能是提供 dbms_ddl 系统包。使用 DBMS_DDL 包可以在存储过程、函数、触发器等 PL/SQL 命名块和匿名块中执行 DDL 语句，以及执行一些 DDL 语句的加密操作。 • 插件名为 dbms_ddl • 插件版本 V1.0 14.2 插件 dbms_ddl 加载方式 该插件为初始化数据库实例时默认创建。 14.3 插件 dbms_ddl 的参数配置 dbms_ddl 扩展插件无需配置任何参数。 14.4 插件 dbms_ddl 使用方法 14.4.1 DBMS_DDL.WRAP 功能描述 只加密不执行语句。 函数 WRAP 以 CREATE [ OR REPLACE ] 语句作为输入，指定创建包体、函数、过程。并返回 CREATE [ OR REPLACE ] 语句的加密语句。 70 第 14 章 DBMS_DDL 语法格式 DBMS_DDL.WRAP（ddl VARCHAR2）RETURN VARCHAR2; 参数说明 ddl 指定用于创建一个包体、函数、过程的 CREATE [ OR REPLACE ] 语句。 返回值 返回 32k 字节以内已加密的字符串。 注意事项 • 任何试图调用该子程序的语句都应使用标准的包名 SYS.DBMS_DDL 以避免与本地定义的 DBMS_DDL 同 义。 • 不能对 trigger 进行加密，如果需要对 trigger 进行加密请直接加密函数，然后通过触发器去调用该函数即可。 • 支持 $$...$$ 的 pg 语法加密。可以加密使用 $$..$$ 的 pg 语法的 plsql 对象或 plpgsql 对象。 异常说明 如果不是 CREATE [ OR REPLACE ] 指定的语句，则报错“向 DBMS_DDL.WRAP 输入的内容不是合法的 PL/SQL 单元”。 示例 为 PL/SQL 语句和 PL/pgSQL 语句加密，用例如下。 \set SQLTERM / select dbms_ddl.wrap( 'create or replace function func4 return int is begin NULL; return 3; end;'); / wrap -------------------------------------------------------------create or replace function func4 return int is WRAPPED+ htpt6DqPHq8uEHewSse+kc8myKyoI7I9f5mTI2Ob72I= + END; (1 row) \set SQLTERM / select dbms_ddl.wrap( 'CREATE OR replace function func_test() returns int AS $$ BEGIN return 1; 71 第 14 章 DBMS_DDL END $$language plpgsql;'); / wrap -----------------------------------------------------------------CREATE OR replace function func_test() returns int AS $$ WRAPPED+ EmUKDO9/8ueGxdvzZRYwU3o6X3YY9jZ6FeYIauqV+oM= + END; + $$language plpgsql; (1 row) 14.4.2 DBMS_DDL.CREATE_WRAPPED 功能描述 加密并执行语句。 过程 CREATE_WRAPPED 的功能是创建一个包体、函数、过程。它的实现流程是将输入参数的 CREATE [ OR REPLACE ] 语句转换为加密后的 CREATE [ OR REPLACE ] 语句，并执行转换后语句。实际上，该过程将加 密与创建语句合为一体。 语法格式 DBMS_DDL.CREATE_WRAPPED（ddl VARCHAR2）； 参数说明 ddl 指定用于创建一个 PL/SQL 包体、函数、过程的 CREATE [ OR REPLACE ] 语句。 注意事项 • 任何试图调用这些 PL/SQL 代码都应使用标准的包名 SYS.DBMS_DDL 以避免与本地定义的 DBMS_DDL 同 义。 • CREATE_WRAPPED 过程与 WRAP 函数一次只能输入单条 PL/SQL 或 PL/pgSQL 语句。 • 不能对 trigger 进行加密，如果需要对 trigger 进行加密请先加密函数，然后通过触发器去调用该函数。 • 支持 $$...$$ 的 pg 语法加密。可以加密使用 $$..$$ 的 pg 语法的 PL/SQL 对象或 PL/pgSQL 对象。 异常说明 如果不是 CREATE [ OR REPLACE ] 指定的 PL/SQL 语句，则报错“向 DBMS_DDL.WRAP 输入的内容不是 合法的 PL/SQL 单元”。 示例 以下用例为使用 create_wrapped 子程序创建加密的 PL/SQL 对象和 PL/pgSQL 对象。 \set SQLTERM / exec dbms_ddl.create_wrapped( 72 第 14 章 DBMS_DDL 'create or replace function func4 return int is begin NULL; return 3; end;'); / \set SQLTERM / exec dbms_ddl.create_wrapped( 'CREATE OR replace function func_test() returns int AS $$ BEGIN return 1; END $$language plpgsql;'); / 14.5 插件 dbms_ddl 卸载方法 无法卸载。 14.6 插件 dbms_ddl 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.0 升级到 1.1 ALTER EXTENSION dbms_ddl UPDATE TO '1.1'; 73 第 15 章 DBMS_LOB 15章 dbms_lob 第 15.1 插件 dbms_lob 简介 dbms_lob 是 KingbaseES 的一个扩展插件，它定义了一套对于 CLOB/BLOB 大对象的操作。 15.2 插件 dbms_lob 的加载方式 在使用 dbms_lob 之前，我们需要将它添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启数据 库。 此插件需要在 kdb_raw 插件加载之后才可以成功创建。 shared_preload_libraries = 'dbms_lob' # (change requires restart) create extension dbms_lob; 不需要使用时 drop extension dbms_lob 即可。 15.3 插件 dbms_lob 的参数配置 无需配置任何参数 15.4 插件 dbms_lob 的使用方法 15.4.1 dbms_lob.createtemporary dbms_lob.createtemporary 创建一个空的 CLOB 或者 BLOB。 语法 74 第 15 章 DBMS_LOB createtemporary(lob_loc IN OUT CLOB, cache IN BOOLEAN, dur IN integer DEFAULT 1); createtemporary(lob_loc IN OUT BLOB, cache IN BOOLEAN, dur IN integer DEFAULT 1); 参数 lob_loc 目前该参数是 OUT cache 所有的临时大对象都在内存中 dur 目前都是 SESSION 级别的 返回值 无返回值。 注解 无 示例 \set SQLTERM / create or replace function test0010() return CLOB AS declare myclob CLOB ; begin dbms_lob.createtemporary( myclob, true, dbms_lob.SESSION); return myclob; end; / \set SQLTERM ; select test0010(); test0010 ---------(1 row) 15.4.2 dbms_lob.istemporary dbms_lob.istemporary 该函数判断一个 CLOB/BLOB 对象是否是临时的 语法 istemporary(lob_loc IN CLOB) 返回 bool 类型; istemporary(lob_loc IN BLOB) 返回 bool 类型; 参数 75 第 15 章 DBMS_LOB lob_loc 该参数是一个传入的 CLOB/BLOB 大对象。 返回值 如果传入参数是 NULL 则返回 NULL 如果入参大对象是临时的则返回 TRUE 否则返回 FALSE。 注解 无 示例 \set SQLTERM / create or replace function test0020() return BOOL AS declare myclob CLOB ; declare bval BOOL; begin dbms_lob.createtemporary( myclob, true, dbms_lob.SESSION); bval = dbms_lob.istemporary( myclob ); return bval; end; / \set SQLTERM ; select test0020(); test0020 ---------f (1 row) 15.4.3 dbms_lob.freetemporary dbms_lob.freetemporary 释放临时的 CLOB/BLOB 大对象。 语法 freetemporary(lob_loc IN CLOB); freetemporary(lob_loc IN BLOB); 参数 lob_loc 该参数是一个传入的 CLOB/BLOB 大对象。 返回值 无返回值。 注解 76 第 15 章 DBMS_LOB 无 示例 -- dbms_lob.substr \set SQLTERM / CREATE OR REPLACE FUNCTION test0050() RETURNS VARCHAR AS DECLARE V1 CLOB; DECLARE V3 VARCHAR; DECLARE integer; i BEGIN dbms_lob.createtemporary(V1,true); dbms_lob.append(V1,'hello world'::CLOB); V3= dbms_lob.substr(V1); dbms_lob.freetemporary(V1); return V3; END; / \set SQLTERM ; select * from test0050(); test0050 ------------hello world (1 row) 15.4.4 dbms_lob.append dbms_lob.append 该函数给出两个大对象 dest_lob 和 src_lob 把 src_lob 追加到 dest_lob。 语法 append( dest_lob IN OUT CLOB, src_lob IN CLOB ); append( dest_lob IN OUT NOCOPY BLOB, src_lob IN BLOB ); 参数 dest_lob 该参数是一个传入的 CLOB/BLOB 大对象要把另外一个大对象 src_lob 追加到其后。 src_lob 该参数是一个传入的 CLOB/BLOB 大对象要把该对象追加到 dest_lob。 返回值 无返回值。 注解 无 77 第 15 章 DBMS_LOB 示例 \set SQLTERM / create or replace function test0060() return CLOB as DECLARE myclob CLOB; begin dbms_lob.createtemporary( myclob, true); dbms_lob.append(myclob,'hello'::CLOB ); return myclob; end; / \set SQLTERM ; select test0060(); test0060 ---------hello 15.4.5 dbms_lob.substr dbms_lob.substr 该函数从一个 CLOB 对象中提取一个子串用子串构建并返回一个新的 VARCHAR 对象。 语法 dbms_lob.substr(lob_loc CLOB, amount INT DEFAULT 32767 , offsets INT DEFAULT 1 ) RETURNS VARCHAR; 参数 lob_loc 该参数是一个传入的 CLOB 大对象要从这个 CLOB 对象中提取子串。 amount 从 lob_loc 提取多少个字符默认值是 32767。 offsets 从 dest_lob 的第几个字符开始提取子串 1 表示第一个字符默认值是 1。 返回值 返回提取出来的子串。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0051() RETURNS INTEGER AS DECLARE v1 CLOB := 'hello 人大金仓 database'; 78 第 15 章 DBMS_LOB DECLARE v3 CLOB; BEGIN v3= DBMS_LOB.SUBSTR(v1,0, 7); RETURN DBMS_LOB.GETLENGTH(v3); END; / \set SQLTERM ; SELECT * FROM test0051(); test0051 ---------(1 row) 15.4.6 dbms_lob.writeappend dbms_lob.writeappend 该函数把 VARCHAR 或 RAW 类型 buffer 中一定数量的字符串或字节串追加到 CLOB 或 BLOB 对象后。 语法 writeappend(lob_loc IN OUT CLOB, amount IN INTEGER, buffer IN VARCHAR); writeappend(lob_loc IN OUT BLOB, amount IN INTEGER, buffer IN RAW); 参数 lob_loc 该参数是一个传入的 CLOB 或 BLOB 大对象要向这个 CLOB 或 BLOB 对象追加字符串或字节串。 amount 向 lob_loc 追加多少个字符或字节。 offsets 把 buffer 中一定数量的字符串或字节串追加到 lob_loc 中。 返回值 无返回值。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0070() RETURNS CLOB AS DECLARE V1 CLOB := 'hello'; DECLARE V2 VARCHAR := 'world'; BEGIN 79 第 15 章 DBMS_LOB dbms_lob.writeappend(V1,2,V2); return V1; END; / \set SQLTERM ; select test0070(); test0070 ---------hellowo (1 row) 15.4.7 dbms_lob.instr dbms_lob.instr 给定两个 CLOB 对象以及各自的起始字符位置比较一定数量的字符串片断。 语法 instr(lob_loc CLOB, pattern VARCHAR, offsets INT default 1, nth INT default 1) return integer; 参数 lob_loc 该参数是一个传入的 CLOB 大对象要在这个 CLOB 中搜索模式。 pattern 要在 CLOB lob_loc 中搜索该模式。 offset 从 CLOB lob_loc 中的第几个字符开始搜索 1 表示从第 1 个字符开始搜索。 nth 在 CLOB lob_loc 中搜索第 nth 个匹配 1 表示第 1 个。 返回值 返回整数表示第 nth 个匹配的字符位置如果 nth 匹配没有找到则返回 0。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0080() RETURNS INT AS DECLARE V1 CLOB := 'hello world world'; DECLARE V2 VARCHAR := 'world'; DECLARE V3 INT :=1 ; BEGIN V3 = dbms_lob.instr(V1,V2,1,3); return V3; END; 80 第 15 章 DBMS_LOB / \set SQLTERM ; select * from test0080(); test0080 ---------0 (1 row) 15.4.8 dbms_lob.compare dbms_lob.compare 给定两个 CLOB 对象以及各自的起始字符位置，比较一定数量的字符串片断。 语法 compare(lob_loc1 CLOB, lob_loc2 CLOB, amount INT, offset1 INT default 1, offset2 INT default 1) return integer; 参数 lob_loc 传入的两个 CLOB 大对象。 amount 比较这么多数量的字符。 offset 分别是 lob_loc1 和 lob_loc2 的起始字符位置 1 表示从第 1 个字符开始比较。 返回值 返回整数 0 表示相等非 0 表示不相等。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0090() RETURNS INT AS DECLARE V1 CLOB := '你好'; DECLARE V2 CLOB := '你好吗'; DECLARE V3 INT :=1 ; BEGIN V3=dbms_lob.compare(V2,V1,1,1,1); return V3; END; / \set SQLTERM ; 81 第 15 章 DBMS_LOB select * from test0090(); test0090 ---------0 (1 row) 15.4.9 dbms_lob.getlength dbms_lob.getlength 给定的 CLOB 或 BLOB 对象，返回其中包含的字符长度或字节长度。 语法 getlength(lob_loc CLOB) return int4; getlength(lob_loc BLOB) return int4; 参数 lob_loc 传入的 CLOB 或 BLOB 大对象。 返回值 返回整数表示 CLOB 中字符长度或 BLOB 中的字节长度。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0100() RETURNS INT AS DECLARE V1 CLOB := 'abcd 1234'; DECLARE V3 INT :=1 ; BEGIN select dbms_lob.getlength(V1) into V3; return V3; END; / \set SQLTERM ; select * from test0100(); test0100 ---------9 (1 row) 82 第 15 章 DBMS_LOB 15.4.10 dbms_lob.trim dbms_lob.trim 截取 CLOB 或 BLOB 对象指定长度的子串。 语法 trim(lob_loc IN OUT CLOB, newlen INT); trim(lob_loc IN OUT BLOB, newlen INT); 参数 lob_loc 传入的 CLOB 或 BLOB 大对象。 newlen 截取后长度。 返回值 • 如果 lob_loc 为 NULL，抛出异常。 � - 如果 newlen 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 否则 lob_loc 返回截取后的 CLOB 或 BLOB 对象。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0110() RETURNS CLOB AS DECLARE v1 CLOB := 'abcd'; DECLARE v3 INT :=1 ; BEGIN DBMS_LOB.TRIM(v1,v3); RETURN v1; END; / \set SQLTERM ; SELECT * FROM test0110(); test0110 ---------a (1 row) 83 第 15 章 DBMS_LOB 15.4.11 dbms_lob.erase dbms_lob.erase 擦除 CLOB 或 BLOB 对象对象中指定的部分子串。CLOB 擦除部分用空格填充，BLOB 擦除部 分用 0 填充。如果指定长度超出了 CLOB 或 BLOB 对象结尾，则实际擦除截止到 CLOB 或 BLOB 对象结尾，实际 擦除长度通过 amount 参数返回。 语法 erase(lob_loc IN OUT CLOB, amount IN OUT INT, start_offset IN INT default 1); erase(lob_loc IN OUT BLOB, amount IN OUT INT, start_offset IN INT default 1); 参数 • lob_loc 传入的 CLOB 或 BLOB 大对象。 • amount 输入要擦除的子串长度。 • start_offset 要擦除的起始位置，默认值为 1。开头位置为 1。 返回值 • 如果 lob_loc, amout, start_offset 任一输入为 NULL，抛出异常。 • 如果 amount 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 如果 start_offset 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 否则 lob_loc 返回擦除后的 BLOB 对象，amount 返回实际擦除的字节长度。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0120() RETURNS CLOB AS DECLARE v1 CLOB := 'abcd'; DECLARE v2 INT :=1 ; DECLARE v3 INT :=2 ; BEGIN DBMS_LOB.ERASE(v1,v2,v3); RETURN v1; END; / \set SQLTERM ; SELECT * FROM test0120(); test0120 ---------- 84 第 15 章 DBMS_LOB a cd (1 row) 15.4.12 dbms_lob.copy dbms_lob.copy 拷贝源 CLOB 或 BLOB 对象中指定的部分子串，到目标 CLOB 或 BLOB 对象的指定位置，替 换目标对象起始位置和长度指定的子串部分。如果目标对象指定拷贝的起始位置超出其原始长度，则在目标对象之后 的起始位置附加源对象子串。原目标对象结尾和附加子串起始位置之间 CLOB 用空格填充，BLOB 用 0 填充。 语法 copy(dest_lob IN OUT CLOB, src_lob IN CLOB, amount IN INT, dest_offset IN INT default 1, src_offset IN INT default 1); copy(dest_lob IN OUT BLOB, src_lob IN BLOB, amount IN INT, dest_offset IN INT default 1, src_offset IN INT default 1); 参数 • dest_lob 目标 CLOB 或 BLOB 大对象。 • src_lob 源 CLOB 或 BLOB 大对象。 • amount 要拷贝的字符或字节长度。 • dest_offset 目标对象要开始拷贝替换的起始位置，默认值为 1。开头位置以 1 开始计数。 • src_offset 源对象要开始拷贝读取的起始位置，默认值为 1。开头位置以 1 开始计数。 返回值 • 如果 dest_lob, src_lob amout, dest_offset, src_offset 任一输入为 NULL，抛出异常。 • 如果 amount 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 如果 dest_offset 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 如果 src_offset 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 否则 dest_lob 返回复制后的 CLOB 或 BLOB 对象。 注解 无 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0130() RETURNS CLOB AS DECLARE v1 CLOB := '一二三四'; DECLARE v2 CLOB := 'abcd'; 85 第 15 章 DBMS_LOB DECLARE v3 INT :=1 ; DECLARE v4 INT :=2 ; DECLARE v5 INT :=1 ; BEGIN dbms_lob.copy(v2,v1,v4,v3,v5); RETURN v2; END; / \set SQLTERM ; SELECT * FROM test0130(); test0130 ---------一二 cd (1 row) 15.5 dbms_lob.read dbms_lob.read 读取 CLOB 或 BLOB 对象中指定部分到缓冲区对象。 语法 read(lob_loc IN CLOB, amount IN OUT INT, start_offset IN INT, buffer OUT VARCHAR2); read(lob_loc IN BLOB, amount IN OUT INT, start_offset IN INT, buffer OUT RAW); 参数 • lob_loc 传入的 CLOB 或 BLOB 对象。 • amount 输入要读取的字节长度。 • start_offset 要读取的起始位置。开头位置以 1 开始计数。 返回值 • 如果 lob_loc,amout, start_offset 任一输入为 NULL，抛出异常。 • 如果 amount 小于 1 或大于 32767，抛出异常。 • 如果 start_offset 小于 1 或大于 MAXLOBSIZE（1073741824），抛出异常。 • 否则 buffer 返回读取的 BLOB 子串；amount 返回实际读取的子串长度，如果 start_offset 超出原对象长度， 则 amount 返回 0。 注解 无 示例 86 第 15 章 DBMS_LOB \set SQLTERM / CREATE OR REPLACE FUNCTION test0140() RETURNS VARCHAR2 AS DECLARE v2 CLOB := 'abcd'; DECLARE v3 INT :=1 ; DECLARE v5 INT :=1 ; DECLARE buffer VARCHAR2; BEGIN DBMS_LOB.READ(v2,v3,v5,buffer); RETURN buffer; END; / \set SQLTERM ; SELECT * FROM test0140(); test0140 ---------a (1 row) 15.6 插件 dbms_lob 卸载方法 不需要插件时执行 drop extension dbms_lob 即可。 15.7 插件 dbms_lob 升级方法 dbms_lob 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 87 第 16 章 DBMS_METADATA 16章 dbms_metadata 第 16.1 插件 dbms_metadata 简介 DBMS_METADATA 包是 KingbaseES 数据库中提供的从数据库字典中以 XML 或者 DDL 语句形式检索元数据 的一系列函数。 使用时需要 create extension dbms_metadata，不需要时 drop extension dbms_metadata 即可。 • 插件名为 dbms_metadata • 插件版本 V1.0 16.2 插件 dbms_metadata 加载方式 CREATE EXTENSION dbms_metadata; 16.3 插件 dbms_metadata 的参数配置 无需配置任何参数。 16.4 插件 dbms_metadata 使用方法 16.4.1 DBMS_METADATA.GET_DDL 功能 KingbaseES 兼容 ORACLE 的 DBMS_METADATA.GET_DDL() 函数。该函数用于创建特定类型对象的 DDL 语句。 88 第 16 章 DBMS_METADATA 目前可支持获取以下类型对象的 DDL • TABLE • VIEW • INDEX • FUNCTION • PROCEDURE • TRIGGER • SEQUENCE • DBLINK • SYNONYM 语法格式 使用该函数前需要先创建 DBMS_METADATA 扩展。 DBMS_METADATA.GET_DDL( OBJTYPE VARCHAR2(63), OBJNAME VARCHAR2(63), SCHEMA VARCHAR2(63) DEFAULT NULL, VERSION VARCHAR2(63) DEFAULT NULL, MODEL VARCHAR2(63) DEFAULT NULL, TRANSFORM VARCHAR2(63) DEFAULT NULL); 参数说明 表 16.4.1: DBMS_METADATA.GET_DDL 参数 参数名称 描述 OBJTYPE 指定对象的数据类型 OBJNAME 指定对象名 SCHEMA 指定对象的模式名，默认值是 NULL VERSION 指定元数据的版本，默认值是 NULL MODEL 指定要使用的对象的模型，默认值是 NULL TRANSFORM 指定输出转换的名称，默认值是 NULL 注意: 89 第 16 章 DBMS_METADATA 1. VERSION，MODEL，TRANSFORM 这三个参数值在目前的 KingbaseES 中暂时不做处理。 2. 参数内容大小写不敏感。 返回值类型 以 TEXT 返回指定对象的 DDL 语句。暂不支持指定输出转换类型。 1. 对于 TABLE 类型的对象，该函数的返回值包含以下内容 • SCHEMA 名； • TABLE 名； • 列名，列的数据类型，默认值，约束； • FOREIGN KEY；（如果存在） • PARTITION 类型和字段；（如果存在） 2. 返回 TEXT 内容全为大写。 权限 DBA 创建 DBMS_METADATA 扩展后，允许其他用户执行该扩展下的 GET_DDL 函数，暂不支持跨模式调 用。 示例 --TABLE CREATE TABLE test_tab1( a smallserial, b int, c text, d text default 'KB', e text ) PARTITION BY HASH(a,c,e); SELECT dbms_metadata.get_ddl('table', 'test_tab1'); get_ddl --------------------------------CREATE TABLE PUBLIC.TEST_TAB1( + A SMALLSERIAL NOT NULL, + B INTEGER, + C TEXT, + D TEXT DEFAULT 'KB'::TEXT, + E TEXT + ) + PARTITION BY HASH (A, C, E) + (1 row) 90 第 16 章 DBMS_METADATA --FUNCTION CREATE FUNCTION test_func1(text, date) RETURNS bool LANGUAGE 'sql' AS 'SELECT $1 = ''abcd'' AND $2 > ''200101-01'''; SELECT dbms_metadata.get_ddl('FUNCTION', 'TEST_FUNC1'); get_ddl --------------------------------------------------------------------CREATE OR REPLACE FUNCTION PUBLIC.TEST_FUNC1(TEXT, PG_CATALOG.DATE)+ RETURNS BOOLEAN + LANGUAGE SQL + AS $FUNCTION$SELECT $1 = 'ABCD' AND $2 > '2001-01-01'$FUNCTION$ + (1 row) --INDEX CREATE TABLE test_tab5(a varchar(32), b varchar(32)); CREATE INDEX idx5 ON test_tab5((a||' '||b)); SELECT dbms_metadata.get_ddl('INDEX', 'idx5'); get_ddl -------------------------------------------------------------------------------------- --------- CREATE INDEX IDX5 ON PUBLIC.TEST_TAB5 USING BTREE (((((A)::TEXT || ' '::TEXT) || (B) ::TEXT)))+ (1 row) 16.5 插件 dbms_metadata 卸载方法 DROP EXTENSION dbms_metadata; 16.6 插件 dbms_metadata 升级方法 ALTER EXTENSION dbms_metadata UPDATE; 91 第 17 章 DBMS_MVIEW 17章 dbms_mview 第 插件 dbms_mview 简介 17.1 插件 dbms_mview 是 KingbaseES 的一个扩展插件。插件 dbms_mview 功能是提供 dbms_mview 系统包。 dbms_mview 包可以对物化视图进行一些功能操作。 插件 dbms_mview 加载方式 17.2 启动 KingbaseES 数据库后执行 SQL 命令创建 dbms_mview 插件。 示例 CREATE EXTENSION dbms_mview; 插件 dbms_mview 使用方法 17.3 17.3.1 REFRESH 存储过程 功能描述 刷新不是同一刷新组的一或多个物化视图。 语法格式 DBMS_MVIEW.REFRESH ( list method IN VARCHAR2, IN rollback_seg VARCHAR2 DEFAULT NULL,, IN push_deferred_rpc VARCHAR2 IN refresh_after_errors DEFAULT NULL, BOOLEAN IN DEFAULT TRUE, BOOLEAN DEFAULT FALSE, 92 第 17 章 DBMS_MVIEW purge_option IN INTEGER DEFAULT 1, parallelism IN INTEGER DEFAULT 0, heap_size IN BINTEGER DEFAULT 0, atomic_refresh nested IN IN BOOLEAN BOOLEAN out_of_place IN DEFAULT TRUE, DEFAULT FALSE, BOOLEAN DEFAULT FALSE); 参数说明 list VARCHAR2 类型，待刷新的物化视图名称。 method VARCHAR2 类型，默认值为 null 。刷新物化视图的方式 c(只支持完全刷新)，否则会报错。 注意: 目前实现 “list“ 和 method 参数功能，其他参数暂时只支持语法。 示例 CREATE TABLE matview (id INT,name TEXT); CREATE MATERIALIZED VIEW mymatview AS SELECT * FROM matview; CALL DBMS_MVIEW.REFRESH ('mymatview', 'c'); 17.4 插件 dbms_mview 卸载方法 在数据库中执行 SQL 命令卸载插件。 DROP EXTENSION dbms_mview; 17.5 插件 dbms_mview 升级方法 dbms_mview 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 93 第 18 章 DBMS_OBFUSCATION_TOOLKIT 第 18.1 18章 dbms_obfuscation_toolkit 插件 dbms_obfuscation_toolkit 简介 dbms_obfuscation_toolkit 系统包可以提供 DES 或 3DES 算法进行数据的加解密。同时，该包也提供了数据的 MD5 计算接口。 • 插件名为 dbms_obfuscation_toolkit • 插件版本 V1.0 18.2 插件 dbms_obfuscation_toolkit 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'dbms_obfuscation_toolkit' 18.3 插件 dbms_obfuscation_toolkit 的参数配置 无 94 第 18 章 DBMS_OBFUSCATION_TOOLKIT 18.4 插件 dbms_obfuscation_toolkit 使用方法 18.4.1 限制 1. DBMS_OBFUSCATION_TOOLKIT 包函数目前支持 bytea 格式数据输入。对于带有转义字符的数据源，解 析时会按转义字符进行处理，使用时需要注意数据的实际长度。 2. DES/3DES 加解密接口对于数据和密钥长度有限制。 a）输入的数据或密钥长度为空时，报错 28231 - ”Invalid input to Obfuscation toolkit” b）输入的数据长度必须为 8 的倍数，否则报错 28232 - ”Invalid input size for Obfuscation toolkit.” c）密钥长度缺失或者小于 8 时，报错 28234 - ”Key length too short.” d）3DES 加解密接口的 which 参数目前支持取值 1，否则报错 28236 - ”Invalid Triple DES mode” 18.4.2 启用 语法格式 CREATE EXTENSION DBMS_OBFUSCATION_TOOLKIT; 功能描述 加载插件，启用 DBMS_OBFUSCATION_TOOLKIT 包。 18.4.3 禁用 语法格式 DROP EXTENSION DBMS_OBFUSCATION_TOOLKIT; 功能描述 卸载插件，禁用 DBMS_OBFUSCATION_TOOLKIT 包。 18.4.4 DBMS_OBFUSCATION_TOOLKIT 系统包子函数接口 18.4.4.1 DES3ENCRYPT 语法格式 95 第 18 章 DBMS_OBFUSCATION_TOOLKIT des3encrypt(input_string IN bytea, key_string IN bytea, which IN integer) RETURNS bytea; des3encrypt(input_string IN bytea, key_string IN bytea, which IN integer, iv_string IN bytea) RETURNS bytea; 功能描述 使用 3DES 算法对数据进行加密。 参数说明 input_string 待加密数据。 key_string 用于加密数据的密钥。 which 使用的加解密密钥方式。取值 1，表示 3DES 密钥。 iv_string 仅当使用 CBC 加密方式时使用，初始 IV 值。 返回值说明 返回加密后的数据。 示例 参见 DES3DECRYPT。 18.4.4.2 DES3DECRYPT 语法格式 des3decrypt(input_string IN bytea, key_string IN bytea, which IN integer) RETURNS bytea; des3decrypt(input_string IN bytea, key_string IN bytea, which IN integer, iv_string IN bytea) RETURNS bytea; 功能描述 使用 3DES 算法对数据进行解密。 参数说明 input_string 待解密数据。 key_string 用于解密数据的密钥。 which 使用的加解密密钥方式。取值 1，表示 3DES 密钥。 iv_string 仅当使用 CBC 加密方式时使用，初始 IV 值。 返回值说明 返回解密后的数据。 示例 96 第 18 章 DBMS_OBFUSCATION_TOOLKIT \c - system set bytea_output to escape; select DBMS_OBFUSCATION_TOOLKIT.des3decrypt(DBMS_OBFUSCATION_TOOLKIT.des3encrypt('0123456789abcdef', '0123456789abcdef87654321', 1), '0123456789abcdef87654321', 1); des3decrypt -----------------0123456789abcdef (1 行记录) select DBMS_OBFUSCATION_TOOLKIT.des3decrypt(DBMS_OBFUSCATION_TOOLKIT.des3encrypt('0123456789abcdef', '0123456789abcdef87654321', 1, '12345678'), '0123456789abcdef87654321', 1, '12345678'); des3decrypt -----------------0123456789abcdef (1 行记录) 18.4.4.3 DESENCRYPT 语法格式 desencrypt(input_string IN bytea, key_string IN bytea) RETURNS bytea; 功能描述 使用 DES 算法对数据进行加密。 参数说明 input_string 待加密数据。 key_string 用于加密数据的密钥。 返回值说明 返回加密后的数据。 示例 参见 DESDECRYPT。 18.4.4.4 DESDECRYPT 语法格式 desdecrypt(input_string IN bytea, key_string IN bytea) RETURNS bytea 功能描述 97 第 18 章 DBMS_OBFUSCATION_TOOLKIT 使用 DES 算法对数据进行解密。 参数说明 input_string 待解密数据。 key_string 用于解密数据的密钥。 返回值说明 返回解密后的数据。 示例 select DBMS_OBFUSCATION_TOOLKIT.desdecrypt(DBMS_OBFUSCATION_TOOLKIT.desencrypt('0123456789abcdef', '012345678'), '012345678'); desdecrypt -----------------0123456789abcdef (1 行记录) 18.4.4.5 MD5 语法格式 md5(input_string IN bytea) RETURNS bytea; 功能描述 实现数据的 MD5 哈希值计算，生成的哈希值为 128-bits 的数据摘要。 参数说明 input_string 待计算 hash 的数据。 返回值说明 返回生成的 hash 值。 示例 \c - system set bytea_output to hex; select DBMS_OBFUSCATION_TOOLKIT.MD5('123456#$'); md5 -----------------------------------\xd9aa3f4d907b5d633b78e9e1d699cf96 (1 行记录) 98 第 18 章 DBMS_OBFUSCATION_TOOLKIT 18.5 插件 dbms_obfuscation_toolkit 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 18.6 插件 dbms_obfuscation_toolkit 升级方法 dbms_obfuscation_toolkit 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些 插件。 99 第 19 章 DBMS_OUTPUT 19章 dbms_output 第 19.1 插件 dbms_output 简介 插件 dbms_output 是 KingbaseES 的一个扩展插件。插件 dbms_output 功能是提供 dbms_output 系统包。 DBMS_OUTPUT 系统包可以将提供的文本行写入缓冲区，供以后提取和显示的功能。主要用于调试 PL/SQL 程序，或者在 Ksql 客户端命令中显示信息和报表，譬如我们可以写一个简单的匿名 pl/sql 程序块，而该块出于某种 目的可以使用此包来显示一些信息。 • 插件名为 dbms_output • 插件版本 V1.0 19.2 插件 dbms_output 加载方式 该插件为初始化数据库实例时默认创建。 19.3 插件 dbms_output 的参数配置 dbms_output 扩展插件无需配置任何参数。 19.4 插件 dbms_output 使用方法 19.4.1 限制 DBMS_OUTPUT 行和缓冲区大小的限制： a. 最大行大小为 32767 字节。 100 第 19 章 DBMS_OUTPUT b. 默认缓冲区大小为 20000 字节。最小为 2000 字节，最大是无限的。 19.4.2 启用 语法格式 DBMS_OUTPUT.ENABLE(buffer_size IN INTEGER DEFAULT 20000); 功能描述 这个过程允许调用 PUT、PUT_LINE、NEW_LINE、GET_LINE 和 GET_LINES 等过程。 参数说明 buffer_size: 缓冲区最大尺寸为 1000000 字节，最小为 2000 字节，默认为 20000 字节。将 buffer_size 设置为 null，缓冲区大小将没有限制。 使用说明 a. 如果没有激活 DBMS_OUTPUT 包，对这些过程的调用将被忽略。 b. 如果有多个调用要启用，那么 buffer_size 是最后调用者指定的值。 c. 当 set serveroutput on 开启时可以不用调用 enable 和 disable 过程。 d. 缓存区设定大小的范围为 2000 至 1000000，如果 buffer_size 的值小于 2000，则为 2000；如果 buffer_size 的 值超过 1000000，则为 1000000；如果输入缓存区的数据大小超过缓存区设定的最大值，将直接报错。 示例 输入参数不同，启用缓冲区大小也不同，示例如下： call dbms_output.enable(); call dbms_output.enable(NULL); call dbms_output.enable(3000); 19.4.3 禁用 语法格式 DBMS_OUTPUT.DISABLE(); 功能描述 此过程禁用对 PUT、PUT_LINE、NEW_LINE、GET_LINE 和 GET_LINES 等过程的调用，并清空缓冲 区。 使用说明 101 第 19 章 DBMS_OUTPUT a. 如果该 DBMS_OUTPUT 包被禁用了，那么所有对其子程序 (subprogram) 的调用都将被忽略。这样用户可以 设计应用程序，仅在客户端程序能够处理这些信息的时候启用这些子程序。 b. 如果 set serveroutput off 时调用了 disable 过程，下次调用其他过程前，必须先调用 enable 过程。 19.4.4 DBMS_OUTPUT 系统包支持向缓冲区输入信息 19.4.4.1 向缓冲区中追加内容 语法格式 DBMS_OUTPUT.PUT(item IN VARCHAR2); 功能描述 该过程用来追加部分内容到 Buffer 中的最后一行。 参数说明 item: 追加的字符串。 使用说明 a. 当追加内容时可以使用 put 过程输入，如需整行方式输入最好使用 put_line 过程。 b. 若单行长度超过限制那么将报错，或输入数据超过缓存区设定值将报错。 c. 注意在调用 PUT 或 PUT_LINE 的 PL/SQL 程序单元结束之前，对 PUT 或 PUT_LINE 指定的内容不会输 出。 d. 当调用 PUT_LINE 过程时将自动加入换行符，若使用 PUT 来构建行，那么必须手动使用 NEW_LINE 过程 来加入换行符。GET_LINE 和 GET_LINES 过程不会返回没有以换行符终结的一行。 示例 向缓冲区追加内容，示例如下： set serveroutput on \set SQLTERM / begin dbms_output.put('test1'); dbms_output.new_line(); dbms_output.put('test2'); end; / 19.4.4.2 向缓冲区追加单行信息 语法格式 102 第 19 章 DBMS_OUTPUT DBMS_OUTPUT.PUT_LINE(item IN VARCHAR2); 功能描述 该存储过程用来向 Buffer 中新添一行信息。 参数说明 item: 追加的字符串。 使用说明 a. 输入数据超过缓存区设定值将报错。 b. GET_LINE 和 GET_LINES 不返回未使用换行符终止的行。 示例 向缓冲区追加单行信息，示例如下： set serverout on \set SQLTERM / call dbms_output.put_line('hi' || chr(10) || 'hello'||chr(10) || ' world'); / 19.4.4.3 向缓冲区追加新行 语法格式 DBMS_OUTPUT.NEW_LINE(); 功能描述 该存储过程向缓冲区添加一个换行符，产生新一行。 使用说明 每调用一次生成一次新行。 示例 向缓冲区追加新行，示例如下： set serverout on \set SQLTERM / begin dbms_output.put('test1'); dbms_output.new_line(); dbms_output.put('test2'); dbms_output.new_line(); 103 第 19 章 DBMS_OUTPUT dbms_output.new_line(); dbms_output.put_line('test3'); end; / 19.4.5 DBMS_OUTPUT 系统包支持从缓冲区中获取信息 19.4.5.1 获取首行信息 语法格式 DBMS_OUTPUT.GET_LINE(line OUT VARCHAR2, status OUT INTEGER); 功能描述 该过程从 buffer 中获取单行信息，先加入的信息先获取，获取后 buffer 中的此信息将被删除。 参数说明 a. line 将获取 buffer 中的一行信息，但不包括最后的换行符。 b. status 若调用成功则返回 0，调用失败则返回 1。 使用说明 调用 GET_LINE 成功获取内容后，在下一次调用 PUT，PUT_LINE 或 NEW_LINE 过程前没有被获取的缓存 都将被丢弃，以避免误会。 示例 获取首行信息，示例如下： set serverout on \set SQLTERM / declare line varchar2(120); status integer; begin dbms_output.put('hello'); dbms_output.put_line('world'); dbms_output.get_line(line, status); dbms_output.put_line(line || status); end; / 104 第 19 章 DBMS_OUTPUT 19.4.5.2 获取多行信息 语法格式 PROCEDURE get_lines(lines OUT CHARARR, numlines IN OUT integer); PROCEDURE get_lines(lines OUT DBMSOUTPUT_LINESARRAY, numlines IN OUT integer); 功能描述 该存储过程用以从 Buffer 中获取一个多行的数组，获取后 buffer 中的此信息将被删除。 参数说明 a. CHARARR(包内类型)TYPE CHARARR IS TABLE OF VARCHAR2(32767) INDEX BY INT; b. DBMSOUTPUT_LINESARRAY(包外类型)TYPE DBMSOUTPUT_LINESARRAY IS VARRAY(2147483647) OF VARCHAR2(32767); c. lines 返回缓冲信息的行数组。数组中每一行的最大长度为 32767 字节。 d. numlines 当缓存区行数多于或等于检索的行数时，返回检索行数；当缓存区行数少于检索的行数时，返回缓存 区行数。 使用说明 a. 在获取信息之后，若下次调用输入过程，则没有检索到的任何行都将被丢弃，以避免与下一条消息混淆。 b. CHARARR 类型 numlines 参数当不指定参数或此参数小于等于 0，不获取内容，并返回 numlines 为 0；当此 参数大于 0，如果缓存区行数多于或等于检索的行数时，返回检索行数；如果缓存区行数少于检索的行数时， 返回缓存区行数。 c. DBMSOUTPUT_LINESARRAY 类型 numlines 参数当不指定参数，默认获取全部内容，并返回 numlines 为 获取行数；当此参数小于 0，将报错；当参数大于等于 0 时，如果缓存区行数多于或等于检索的行数时，返回 检索行数，当缓存区行数少于检索的行数时，返回缓存区行数。 示例 get_lines 有多种重载方式，示例如下： set serverout on \set SQLTERM / DECLARE v_data dbms_output.chararr; numlines integer := 2; BEGIN dbms_output.put_line('TEST 1'); dbms_output.put_line('TEST 2'); dbms_output.put_line('TEST 3'); dbms_output.get_lines(v_data, numlines); dbms_output.put_line(v_data(1)); dbms_output.put_line(v_data(2)); 105 第 19 章 DBMS_OUTPUT end; / DECLARE v_data dbmsoutput_linesarray; numlines integer := 2; BEGIN dbms_output.put_line('TEST 1'); dbms_output.put_line('TEST 2'); dbms_output.get_lines(v_data, numlines); dbms_output.put_line(numlines); dbms_output.put_line(v_data(1)); dbms_output.put_line(v_data(2)); end; / 19.4.6 DBMS_OUTPUT 系统包支持客户端显示缓冲区信息 19.4.6.1 客户端命令启动输出功能 语法格式 set serverout[put] on[;] 功能描述 a. 启用 DBMS_OUTPUT 系统包功能。 b. 缓存大小设为不限制大小。 c. 能代替 enable 过程，即可以不需要 enable 过程。 d. 客户端输出缓存区消息。 使用说明 set serverout[put] 跟‘on’或‘on;’，当输入无关命令时会提示命令错误。 示例 通过在 ksql 客户端设置 set serveroutput on 命令，即可显示缓冲区信息，示例如下： set serverout on \set SQLTERM / create or replace procedure protest_A_1 is begin dbms_output.put_line('....test1'); dbms_output.put_line('....test2'); 106 第 19 章 DBMS_OUTPUT end; / declare v_status integer := 0; v_data varchar2(100); begin protest_A_1(); dbms_output.put_line('test3'); dbms_output.get_line(v_data, v_status); dbms_output.put_line('v_data: ' ||v_data || 'v_status: ' ||v_status); dbms_output.put_line('test4'); end; / 19.4.6.2 客户端命令禁用输出功能 语法格式 set serverout[put] off[;] 功能描述 a. 禁用 DBMS_OUTPUT 系统包功能。 b. 清除缓存。 c. 能代替 disable 过程，即可以不需要 disable 过程。 使用说明 set serverout[put] 跟‘off’或‘off;’，当输入无关命令时会提示命令错误。 示例 通过在 ksql 客户端工具设置 set serveroutput off 命令，即可禁用 dbms_output 输出功能。示例如下： set serverout off \set SQLTERM / call dbms_output.put_line('hi' || chr(10) || 'hello'||chr(10) || ' world'); / 19.5 插件 dbms_output 卸载方法 无法卸载。 107 第 19 章 DBMS_OUTPUT 19.6 插件 dbms_output 升级方法 dbms_output 插件随着 KingbaseES 安装包一并升级。通常，用户无须单独升级该插件。 108 第 20 章 DBMS_RANDOM 20章 dbms_random 第 20.1 插件 dbms_random 简介 dbms_random 是 KingbaseES 的一个扩展插件，主要提供一组函数产生随机数或者随机字符。 插件需要手动创建，在服务端程序启动时没有默认加载。 • 插件名为 dbms_random • 插件版本 V1.0 20.2 插件 dbms_random 加载方式 启动 KingbaseES 数据库后执行 SQL 命令创建插件。 示例 create extension dbms_random; 20.3 插件 dbms_random 的参数配置 无需配置任何参数 20.4 插件 dbms_random 的使用方法 创建插件后提供一组函数来产生随机数或随机字符。 下表列出了 dbms_random 系统包并简要的表述了它们。 109 第 20 章 DBMS_RANDOM 表 20.4.1: dbms_random 软件包子程序和函数 子程序/函数 描述 INITIALIZE Procedure 使用一个种子值来初始化包 NORMAL Function 产生标准的正态分布函数 RANDOM Function 产生一个随机整数 SEED Procedure 重置随机数种子 STRING Function 产生一个随机字符串 TERMINATE Procedure 提供语法上的兼容不执行任何操作 VALUE Function 产生指定范围的随机数 20.4.1 INITIALIZE Procedure 使用一个种子值来初始化 dbms_random 包，默认情况下，dbms_random 包是根据用户、时间、会话来初始 化。Initialize 这个函数已经过时，虽然目前受到支持，但考虑历史遗留原因和兼容性保留此初始化方式。 语法格式 dbms_random.initialize(init INTEGER); 参数说明 表 20.4.2: initialize 参数 参数 描述 init 随机数种子值 返回值说明 VOID 示例 CALL dbms_random.initialize(8); 20.4.2 NORMAL Function 产生标准的正态分布函数，此正态分布的标准差为 1，期望值为 0。 110 第 20 章 DBMS_RANDOM 语法格式 dbms_random.normal(); 参数说明 无参 返回值说明 DOUBLE 示例 SELECT dbms_random.normal(); 20.4.3 RANDOM Function 产生一个随机整数，这个函数已经过时了，虽然目前还支持，但不应该使用它，考虑兼容性保留此函数。 语法格式 dbms_random.random(); 参数说明 无参 返回值说明 INTEGER 示例 CALL dbms_random.random(); 20.4.4 SEED Procedure 重置种子，类似于 initialize 函数，initialize 函数已经被淘汰。seed 函数同时支持数值和字符作为种子值，而 initialize 只支持数值。 语法格式 dbms_random.seed(i INTEGER); dbms_random.seed(t TEXT); 参数说明 111 第 20 章 DBMS_RANDOM 表 20.4.3: seed 参数 参数 描述 i 随机数种子值 t 随机数字符种子值 返回值说明 表 20.4.4: seed 返回值 函数 类型 seed(i INTEGER) VOID seed(t TEXT) VOID 示例 CALL dbms_random.seed(8); CALL dbms_random.seed('test'); 20.4.5 STRING Function 获取一个随机字符串，第一个参数是字符串的格式，第二个参数是指字符串的长度。长度最大为 5000，参数如 果超过 5000 会自动以 5000 处理。 语法格式 dbms_random.string(type TEXT,len INTEGER); 参数说明 表 20.4.5: string 参数 参数 描述 type 产生字符串的类型 len 产生字符串的长度 112 第 20 章 DBMS_RANDOM 表 20.4.6: type 参数对应含义 值 描述 ’u’,’U’ 返回大写字母的字符串 ’l’,’L’ 返回小写字母的字符串 ’a’,’A’ 返回大小写字母混合的字符串 ’x’,’X’ 返回大写字母和数字的字符串 ’p’,’P’ 返回任何可打印字符的字符串 返回值说明 TEXT 示例 SELECT dbms_random.string('U',5); SELECT dbms_random.string('P',2); SELECT dbms_random.string('x',4); SELECT dbms_random.string('a',2); SELECT dbms_random.string('l',3); 20.4.6 TERMINATE Procedure 原功能为使用完 dbms_random 包的时候执行此函数，但是现在此函数不执行任何功能，为了语法兼容保留。 语法格式 dbms_random.terminate(); 参数说明 无参 返回值说明 VOID 示例 CALL dbms_random.terminate(); 113 第 20 章 DBMS_RANDOM 20.4.7 VALUE Function 第一种无参的使用方式是获取一个大于或者等于 0 且小于 1 的随机数，精度为 16 位的小数。 第二种使用方式可以指定最小值和最大值，返回值的范围大于或者等于 low，小于 high，精度同为 16 位小数。 语法格式 dbms_random.value(); dbms_random.value(low INTEGER,high INTEGER); 参数说明 表 20.4.7: value 参数 参数 描述 low 产生的随机数最小值 high 产生的随机数最大值 返回值说明 表 20.4.8: value 返回值 函数 类型 value() VOID value(low INTEGER,high INTEGER) VOID 示例 SELECT dbms_random.value(); SELECT dbms_random.value(10,15); 20.5 插件 dbms_random 卸载方法 在数据库中执行 SQL 命令卸载插件。 drop extension dbms_random; 114 第 20 章 20.6 DBMS_RANDOM 插件 dbms_random 升级方法 dbms_random 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 115 第 21 章 DBMS_SESSION 21章 dbms_session 第 21.1 插件 dbms_session 简介 dbms_session 系统包可以用来访问或者设置会话信息。定义了对于 session 的一套操作，使用前需创建扩展 dbms_session。 • 插件名为 dbms_session • 插件版本 V1.0 21.2 插件 dbms_session 加载方式 启动 KingbaseES 数据库后执行 SQL 命令创建插件。 示例： create extension dbms_session; 21.3 插件 dbms_session 的参数配置 无需配置任何参数 21.4 插件 dbms_session 的使用方法 在使用 dbms_session 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 116 第 21 章 DBMS_SESSION shared_preload_libraries = 'dbms_session' 使用时需要 create extension dbms_session。 不需要使用时 drop extension dbms_session 即可。 21.4.1 DBMS_SESSION 系统包子程序 DBMS_SESSION 系统包包含的子程序及简介如下表所示： 表 21.4.1: DBMS_SESSION 包子程序 子程序 简介 CLEAR_ALL_CONTEXT 过程 清理当前会话的指定 namespace 的所有上下文。 CLEAR_CONTEXT 过程 清除 namespace 中的 attribute 值。 LIST_CONTEXT 过程 返回当前会话所有上下文属性和值。 SET_CONTEXT 过程 设置上下文 namespace 的属性和值。 21.4.2 CLEAR_ALL_CONTEXT 过程 清理当前会话的指定 namespace 的所有上下文。该过程需通过 namespace 关联的 package 调用。 语法 DBMS_SESSION.CLEAR_ALL_CONTEXT(namespace VARCHAR2(63)); 参数 表 21.4.2: CLEAR_ALL_CONTEXT 参数 参数名称 描述 namespace 应用程序上下文信息的名称。最大长度 63bytes。 注意: 示例见 SET_CONTEXT 过程。 117 第 21 章 DBMS_SESSION 21.4.3 CLEAR_CONTEXT 过程 清除 namespace 中的 attribute 值。该过程需通过上下文 namespace 关联的 package 调用。 语法 DBMS_SESSION.CLEAR_CONTEXT(namespace VARCHAR2(63),client_identifier VARCHAR2(30),attribute VARCHAR2(128)); 参数 表 21.4.3: CLEAR_CONTEXT 参数 参数名称 描述 namespace 要清除上下文信息的名称。最大长度 63bytes，不区分大小写。 client_identifier 用于全局访问的 client 标识，不起作用，如果指定，则忽略。 attribute 要清除的上下文的属性名，不区分大小写。若为 null，则清除 namespace 下所有 key-value。 注意: 示例见 SET_CONTEXT 过程。 21.4.4 LIST_CONTEXT 过程 返回当前会话所有上下文属性和值。 语法 TYPE AppCtxRecTyp IS RECORD( namespace VARCHAR2(63), attribute VARCHAR2(128), value VARCHAR2(4000) ); TYPE AppCtxTabTyp IS TABLE OF AppCtxRecTyp INDEX BY BINARY_INTEGER; DBMS_SESSION.LIST_CONTEXT( list OUT AppCtxTabTyp, size OUT NUMBER ); 参数 118 第 21 章 DBMS_SESSION 表 21.4.4: LIST_CONTEXT 参数 参数名称 描述 list 输出参数，类型为索引表。 size 输出参数，该索引表中元素的总数。 示例 \set SQLTERM / DECLARE lcontext DBMS_SESSION.APPCTXTABTYP; lsize NUMBER; BEGIN DBMS_SESSION.LIST_CONTEXT (lcontext, lsize); FOR k IN 1 .. (lcontext.COUNT) LOOP DBMS_OUTPUT.PUT_LINE('Namespace: ' || lcontext(k).namespace || ' Attribute: ' || lcontext(k). attribute || ' Value: ' || lcontext(k).value); END LOOP; DBMS_OUTPUT.PUT_LINE('num: '|| lsize); END; / \set SQLTERM ; 21.4.5 SET_CONTEXT 过程 设置上下文 namespace 的属性和值。此过程必须由受信任包直接或间接调用。 语法 DBMS_SESSION.SET_CONTEXT ( namespace VARCHAR（63）, attribute VARCHAR（128）, value VARCHAR（4000）, username VARCHAR（128）, client_id VARCHAR（64） ); 参数 119 第 21 章 DBMS_SESSION 表 21.4.5: SET_CONTEXT 参数 参数名称 描述 namespace 要设置的 context 名。 attribute 要设置的 context 属性名。 value 要设置的 context 属性值。 username 不起作用，如果指定，则忽略。 client_id 不起作用，如果指定，则忽略。 注意: attribute 不可为空，value 可以为空。设置 set ora_input_emptystr_isnull=off; 示例 第一步 创建 package CREATE EXTENSION dbms_session; set ora_input_emptystr_isnull=off; create schema context_schema1; grant usage on schema context_schema1 to public; grant all on schema context_schema1 to public; create or replace context context1 using context_schema1.test_package; \set SQLTERM / CREATE OR REPLACE PACKAGE context_schema1.test_package as procedure set_context(ts_name varchar, key varchar, value varchar); procedure clear_context(ts_name varchar,client_identifier varchar, key varchar); procedure clear_all_context(ts_name varchar); end test_package; / 120 第 21 章 DBMS_SESSION CREATE or replace PACKAGE BODY context_schema1.test_package as procedure set_context(ts_name varchar, key varchar, value varchar) as begin dbms_session.set_context(ts_name, key,value); end; procedure clear_context(ts_name varchar,client_identifier varchar, key varchar) as begin dbms_session.clear_context(ts_name,client_identifier, key); end; procedure clear_all_context(ts_name varchar) as begin dbms_session.clear_all_context(ts_name); end; end test_package; / \set SQLTERM ; 第二步 创建 context create or replace context c_user01 using context_schema1.test_package; 第三步 设置 namespace 的 key-value call context_schema1.test_package.set_context('c_user01', 'u_k2', 'u_v2'); 第四步 查询 select sys_context('c_user01', 'u_k2'); sys_context --------------------------------------------------u_v2 第五步 修改 u_k2 的值并查询 121 第 21 章 DBMS_SESSION call context_schema1.test_package.set_context('c_user01', 'u_k2', 'u_v2222'); select sys_context('c_user01', 'u_k2'); sys_context --------------------------------------------------u_v2222 第六步 增加新的属性值 u_k3 并查询 call context_schema1.test_package.set_context('c_user01', 'u_k3', 'u_v3'); select sys_context('c_user01', 'u_k3'); sys_context ------------------------------------------------u_v3 第七步 清除上下文 c_user01 属性 u_k2 的值并再次查询 call context_schema1.test_package.clear_context('c_user01', null,'u_k2'); select sys_context('c_user01', 'u_k2'); sys_context ------------(1 行记录) select sys_context('c_user01', 'u_k3'); sys_context ------------u_v3 (1 行记录) 第八步 清除上下文 c_user01 call context_schema1.test_package.clear_all_context('c_user01'); select sys_context('c_user01', 'u_k3'); sys_context ------------(1 行记录) 21.5 插件 dbms_session 卸载方法 在数据库中执行 SQL 命令卸载插件。 drop extension dbms_session; 122 第 21 章 21.6 DBMS_SESSION 插件 dbms_session 升级方法 dbms_session 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 123 第 22 章 DBMS_SQL 22章 dbms_sql 第 22.1 插件 dbms_sql 简介 dbms_sql 是 KingbaseES 的 plsql 扩展插件提供的系统包。 DBMS_SQL 包内定义了一系列的过程和函数，专门用于动态 SQL 语句的操作。 • 插件名为 plsql • 插件版本 V1.0 22.2 插件 dbms_sql 加载方式 plsql 插件为初始化数据库实例时默认创建，因此 dbms_sql 系统包为系统内置包。 22.3 插件 dbms_sql 的参数配置 无需配置任何参数。 124 第 22 章 22.4 DBMS_SQL 插件 dbms_sql 使用方法 22.4.1 DBMS_SQL 包预定义类型 22.4.1.1 DBMS_SQL 常量 Name Type Value Description NATIVE INTEGER 1 兼容性常量，仅语法兼容 V6 INTEGER 0 兼容性常量，仅语法兼容 V7 INTEGER 2 兼容性常量，仅语法兼容 FOREIGN_SYNTAX INTEGER -1 兼容性常量，仅语法兼容 22.4.1.2 DBMS_SQL 集合类型 TYPE bfile_table IS TABLE OF BFILE INDEX BY BINARY_INTEGER; TYPE desc_tab IS TABLE OF desc_rec INDEX BY BINARY_INTEGER; TYPE binary_double_table IS TABLE OF BINARY_DOUBLE INDEX BY BINARY_INTEGER; TYPE binary_float_table IS TABLE OF BINARY_FLOAT INDEX BY BINARY_INTEGER; TYPE blob_table IS TABLE OF BLOB INDEX BY BINARY_INTEGER; TYPE clob_table IS TABLE OF CLOB INDEX BY BINARY_INTEGER; TYPE date_table IS TABLE OF DATE INDEX BY BINARY_INTEGER; TYPE number_table IS TABLE OF NUMBER INDEX BY BINARY_INTEGER; TYPE time_table IS TABLE OF TIME_UNCONSTRAINED INDEX BY BINARY_INTEGER; TYPE time_with_time_zone_table IS TABLE OF TIME_TZ_UNCONSTRAINED INDEX BY BINARY_INTEGER; TYPE timestamp_table IS TABLE OF TIMESTAMP_UNCONSTRAINED INDEX BY BINARY_INTEGER; TYPE timestamp_with_ltz_table IS TABLE OF TIMESTAMP_LTZ_UNCONSTRAINED INDEX BY BINARY_INTEGER; 125 第 22 章 DBMS_SQL TYPE timestamp_with_time_zone_table IS TABLE OF TIMESTAMP_TZ_UNCONSTRAINED INDEX BY BINARY_INTEGER; TYPE varchar2_table IS TABLE OF VARCHAR2(2000) INDEX BY BINARY_INTEGER; TYPE varchar2a IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER; TYPE varchar2s IS TABLE OF VARCHAR2(256) INDEX BY BINARY_INTEGER; 22.4.2 DBMS_SQL 包子程序 22.4.2.1 打开新游标 语法格式 DBMS_SQL.OPEN_CURSOR ( treat_as_client BOOL DEFAULT FALSE) RETURN INTEGER; 功能描述 打开一个新游标，返回游标的 ID。 参数说明 treat_as_client 如果为 TRUE，则允许过程将自己设置为客户端；如果为 FALSE，将返回结果返回给客户端应 用程序。该语句的执行结果可以通过 GET_NEXT_RESULT 方法获取。 返回值 返回新游标的游标 ID 号。 使用说明 当不再需要此游标时，必须通过调用 close_cursor 过程来显式关闭它。可以使用游标来重复运行相同的 SQL 语 句。当重用游标时，在解析新的 SQL 语句时重用相应的游标数据区域的内容。在重用游标之前，没有必要关闭和重 新打开它。 示例 \set SQLTERM / DECLARE c integer; BEGIN c := dbms_sql.open_cursor(); dbms_sql.close_cursor(c); END; / 126 第 22 章 DBMS_SQL -----------------ANONYMOUS BLOCK 22.4.2.2 解析语句 语法格式 DBMS_SQL.PARSE ( handle INTEGER, query TEXT, flag INTEGER); DBMS_SQL.PARSE ( handle INTEGER, query CLOB, flag INTEGER); DBMS_SQL.PARSE ( handle INTEGER, query VARCHAR2A, lb INTEGER, ub INTEGER, lfflag BOOLEAN, flag INTEGER); DBMS_SQL.PARSE ( handle INTEGER, query VARCHAR2S, lb INTEGER, ub INTEGER, lfflag BOOLEAN, flag INTEGER); 功能描述 对游标中的语句进行解析。DDL 语句在解析的同时立即执行。 参数说明 127 第 22 章 参数 描述 handle 解析语句的游标 ID query 要进行解析的 SQL 语句 flag 指定 SQL 语句的行为 DBMS_SQL 使用说明 使用 DBMS_SQL 动态运行 DDL 语句可能会导致程序停止响应。例如，对包中的过程的调用会导致包被锁定， 直到执行返回到用户端为止。任何导致锁冲突的操作（例如在第一个锁被释放之前动态的尝试删除包）都会停止程序 的运行。 使用不同 flag 参数，则存在不同的数据库行为。 query 的类型可以是 TEXT,CLOB,VARCHAR2A,VARCHAR2S(参考 DBMS_SQL 预定义集合类型) 示例 parse 接口有多个重载方式，如可传入 text 或集合，示例如下: \set SQLTERM / DECLARE c integer; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'create table if not exists dbmssql_table1(i int, J TEXT)', dbms_sql.native); dbms_sql.close_cursor(c); END; / select count(*) from sys_class where relname='dbmssql_table1'; / -------------------ANONYMOUS BLOCK count ------1 (1 row) \set SQLTERM / DECLARE c integer; sql_string dbms_sql.varchar2s; BEGIN c := dbms_sql.open_cursor(); sql_string(1) := 'create table if not exists '; 128 第 22 章 DBMS_SQL sql_string(2) := 'dbmssql_table2(i int, J TEXT)'; dbms_sql.parse(c, sql_string, 1 ,2, true, dbms_sql.native); dbms_sql.close_cursor(c); END; / select count(*) from sys_class where relname='dbmssql_table2'; / -------------------ANONYMOUS BLOCK count ------1 (1 row) 22.4.2.3 22.4.2.3.1 绑定变量 绑定到游标的基本数据类型 语法格式 DBMS_SQL.BIND_VARIABLE ( handle INTEGER, pos INTEGER, val ANYELEMENT [,out_value_size IN INTEGER]); DBMS_SQL.BIND_VARIABLE ( handle placeholder val INTEGER, TEXT, ANYELEMENT [,out_value_size IN INTEGER]); 功能描述 将一个值或一个集合与游标定义中的占位符绑定，可以通过占位符的位置绑定，也可以通过占位符的名称绑定。 参数说明 129 第 22 章 参数 描述 handle 游标 ID pos 绑定变量的位置 val 与游标中的变量绑定的值或本地变量。 DBMS_SQL ADT (user-defined object types) BINARY_DOUBLE BINARY_FLOAT BFILE BLOB BOOLEAN CLOB DATE DSINTERVAL_UNCONSTRAINED NESTED table NUMBER OPAQUE types REF TIME_UNCONSTRAINED TIME_TZ_UNCONSTRAINED TIMESTAMP_LTZ_UNCONSTRAINED TIMESTAMP_TZ_UNCONSTRAINED TIMESTAMP_UNCONSTRAINED UROWID VARCHAR2 VARRAY YMINTERVAL_UNCONSTRAINED out_value_size 如果没有给定大小，则使用当前值的长度。只有当 val 类型为 char，varchar，text 时能指定该参数。 使用说明 如果变量是 IN 或 IN/OUT 变量或 IN 集合，则给定的绑定值必须对该变量或数组类型有效。OUT 变量的值将 被忽略。 SQL 语句的绑定变量或集合由它们的名称标识。当将值绑定到变量或绑定数组时，语句中标识它的字符串必须 包含一个前导冒号，如下所示 select emp_name from emp where sal > :x; 对于本例，对应的 bind 调用类似于 130 第 22 章 DBMS_SQL bind_variable(cursor_name, ':1', 3500); or bind_variable(cursor_name, 1, 3500); 示例 通过参数位置和参数名称两种绑定方式，来对一个 DML 语句做动态 sql 操作，示例如下: \set SQLTERM / create table if not exists dbmssql_table1(i int, J TEXT); / insert into dbmssql_table1 values (1, 'bbbb'); / DECLARE c integer; r int; x int := 1; y varchar2(100) := 'bbbb'; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'delete from dbmssql_table1 where i = :xx and j = :yy', dbms_sql.native); --通过参数位置绑定 dbms_sql.bind_variable(c, 1, x); dbms_sql.bind_variable(c, 2, y); r := dbms_sql.execute(c); dbms_sql.close_cursor(c); raise notice 'd%', c; END; / ---------------------------NOTICE: d ANONYMOUS BLOCK \set SQLTERM / create table if not exists dbmssql_table1(i int, J TEXT); / insert into dbmssql_table1 values (1, 'bbbb'); / DECLARE c integer; r int; x int := 1; y varchar2(100) := 'bbbb'; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'delete from dbmssql_table1 where i = :xx and j = :yy', dbms_sql.native); 131 第 22 章 DBMS_SQL --通过参数名称绑定 (可以加':'，也可以不加) dbms_sql.bind_variable(c, 'xx', x); dbms_sql.bind_variable(c, ':yy', y); r := dbms_sql.execute(c); dbms_sql.close_cursor(c); raise notice 'd%', c; END; / ---------------------------NOTICE: d ANONYMOUS BLOCK 22.4.2.3.2 绑定到游标的 CHAR 类型 语法格式 DBMS_SQL.BIND_VARIABLE_CHAR ( handle INTEGER, pos INTEGER, val ANYELEMENT, out_value_size IN INTEGER); DBMS_SQL.BIND_VARIABLE_CHAR ( handle placeholder val INTEGER, TEXT, ANYELEMENT, out_value_size IN INTEGER); 功能描述 将一个值或一个集合与游标定义中的占位符绑定，可以通过占位符的位置绑定，也可以通过占位符的名称绑定。 参数说明 132 第 22 章 参数 描述 handle 游标 ID pos 绑定变量的位置 val 与游标中的变量绑定的值或本地变量。 DBMS_SQL ADT (user-defined object types) BINARY_DOUBLE BINARY_FLOAT BFILE BLOB BOOLEAN CLOB DATE DSINTERVAL_UNCONSTRAINED NESTED table NUMBER OPAQUE types REF TIME_UNCONSTRAINED TIME_TZ_UNCONSTRAINED TIMESTAMP_LTZ_UNCONSTRAINED TIMESTAMP_TZ_UNCONSTRAINED TIMESTAMP_UNCONSTRAINED UROWID VARCHAR2 VARRAY YMINTERVAL_UNCONSTRAINED out_value_size 如果没有给定大小，则使用当前值的长度。只有当 val 类型为 char，varchar，text 时能指定该参数。 使用说明 该函数只能绑定字符串类型的变量，且必须指定长度；如果指定长度大于实际长度，则取实际长度，否则取指定 长度。 示例 调用 BIND_VARIABLE_CHAR 子程序，且指定字符串长度的示例如下: \set SQLTERM / create table if not exists dbmssql_table1(i int, J TEXT); 133 第 22 章 DBMS_SQL / insert into dbmssql_table1 values (1, 'bbbb'); / DECLARE c integer; r int; x int := 1; y varchar2(100) := 'bbbbaaaa'; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'delete from dbmssql_table1 where i = :xx and j = :yy', dbms_sql.native); --通过参数位置绑定 dbms_sql.bind_variable(c, 1, x); dbms_sql.bind_variable_char(c, 2, y, 4); r := dbms_sql.execute(c); raise notice 'r = % ', 1; dbms_sql.close_cursor(c); raise notice 'd%', c; END; / ---------------------------NOTICE: r = 1 NOTICE: d ANONYMOUS BLOCK \set SQLTERM / create table if not exists dbmssql_table1(i int, J TEXT); / insert into dbmssql_table1 values (1, 'bbbb'); / DECLARE c integer; r int; x int := 1; y varchar2(100) := 'bbbbaaaa'; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'delete from dbmssql_table1 where i = :xx and j = :yy', dbms_sql.native); --通过参数名称绑定 (可以加':'，也可以不加) dbms_sql.bind_variable(c, 'xx', x); dbms_sql.bind_variable_char(c, ':yy', y, 4); r := dbms_sql.execute(c); dbms_sql.close_cursor(c); raise notice 'd%', c; END; 134 第 22 章 DBMS_SQL / ---------------------------NOTICE: d ANONYMOUS BLOCK 22.4.2.3.3 绑定到游标的关联数组类型 语法格式 DBMS_SQL.BIND_ARRAY ( handle INTEGER, pos INTEGER, val ANYELEMENT); DBMS_SQL.BIND_ARRAY ( handle placeholder val INTEGER, TEXT, ANYELEMENT); 功能描述 将 dbms_sql 预定义的关联数组与游标定义中的占位符绑定，可以通过占位符的位置绑定，也可以通过占位符的 名称绑定。 dbms_sql 将拆分出关联数组中的元素，以所有元素的值作为参数批量执行 dml 语句。 参数说明 135 第 22 章 参数 描述 handle 游标 ID pos 绑定变量的位置 val 与游标中的变量绑定的值或本地变量。 DBMS_SQL datatype clob_table binary_float_table binary_double_table blob_table bfile_table date_table number_table varchar2_table time_table time_with_time_zone_table timestamp_table timestamp_with_ltz_table timestamp_with_time_zone_table index1 集合元素索引值的下限 index2 集合元素索引值的上限 使用说明 为了绑定范围，表必须包含指定范围的元素——tab(index1) 和 tab(index2)，但是范围不必是密集的。Index1 必 须小于等于 index2。在绑定中使用 tab(index1) 和 tab(index2) 之间的所有元素。 如果没有在 bind 调用中指定索引，并且语句中的两个不同绑定指定包含不同数量元素的表，然后实际使用的元 素数量是所有表之间的最小数量。如果指定索引，也会出现这种情况——为所有表选择两个索引之间的最小范围。 不是查询中的所有绑定变量都必须是数组绑定。有些可以是常规绑定，在表达式求值中对集合的每个元素使用相 同的值。 批量 select, insert, update 和 delete 可以通过将多个调用绑定到一个调用来提高应用程序的性能。此过程允许使 用 DBMS_SQL 包预定义的 PL/SQL TABLE 类型。 示例 使用 bind_array 接口来做批量 insert 操作，示例如下: \set SQLTERM / create table if not exists dbmssql_table1(i int, J TEXT); / 136 第 22 章 DBMS_SQL DECLARE c integer; r int; x dbms_sql.number_table; y dbms_sql.varchar2_table; BEGIN c := dbms_sql.open_cursor(); x(1) := 1; x(2) := 2; x(3) := 3; x(4) := 4; y(1) := 'aaaa'; y(2) := 'bbbb'; y(3) := 'cccc'; y(4) := 'dddd'; dbms_sql.parse(c, 'insert into dbmssql_table1 values (:a, :b);', dbms_sql.native); dbms_sql.bind_array(c, 'a', x); dbms_sql.bind_array(c, 'b', y); r := dbms_sql.execute(c); dbms_sql.close_cursor(c); raise notice 'd%', c; END; / ---------------------------NOTICE: d ANONYMOUS BLOCK select * from dbmssql_table1; / ---------------------------i | j ---+-----1 | aaaa 2 | bbbb 3 | cccc 4 | dddd (4 rows) 22.4.2.3.4 绑定到游标的包中类型 语法格式 DBMS_SQL.BIND_VARIABLE_PKG ( handle INTEGER, pos INTEGER, 137 第 22 章 val DBMS_SQL ANYELEMENT); DBMS_SQL.BIND_VARIABLE_PKG ( handle INTEGER, placeholder val TEXT, ANYELEMENT); 功能描述 同 BIND_VARIABLE，BIND_VARIABLE 和 BIND_VARIABLE_PKG 都可以用来绑定包中或者非包中定义 的类型。 22.4.2.4 定义类型接收列值 22.4.2.4.1 定义基本数据类型接收单行列值 语法格式 DBMS_SQL.DEFINE_COLUMN ( handle IN INTEGER, pos IN INTEGER, val ANYELEMENT [,column_size IN INTEGER]); 功能描述 为 select 游标定义被选择的列，定义后可通过 column_value 取出对应列的值。 参数说明 138 第 22 章 DBMS_SQL 参数 描述 handle 游标 ID pos 列在定义行中的相对位置。语句在第一列位置为 1。 val 定义的列的值。此值的类型决定了所定义列的类型。 BINARY_DOUBLE BINARY_FLOAT BFILE BLOB CLOB DATE DSINTERVAL_UNCONSTRAINED NUMBER TIME_UNCONSTRAINED TIME_TZ_UNCONSTRAINED TIMESTAMP_LTZ_UNCONSTRAINED TIMESTAMP_TZ_UNCONSTRAINED TIMESTAMP_UNCONSTRAINED UROWID YMINTERVAL_UNCONSTRAINED ADT(user-defined object types) COLLECTIONS (varrays and nested tables) REFS OPAQUE TYPES column_size 类型为 CHAR,VARCHAR2,TEXT 的列的预期列值的 最大字节大小 示例 define_column 接口在 parse 接口后调用，为 select 游标定义被选择的列，如下所示: \set SQLTERM ; drop table t2; create table t2(id int,name int); insert into t2 values (1,2); \set SQLTERM / DECLARE c integer; n int; 139 第 22 章 DBMS_SQL result int; dc int; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select * from t2', dbms_sql.native); dbms_sql.define_column(c, 1, n); dbms_sql.define_column(c, 2, result); dbms_sql.close_cursor(c); END; / ---------------------------ANONYMOUS BLOCK \set SQLTERM ; drop table t2; create table t2(id int,name text); insert into t2 values (1,'zs'); --define_column 接口可以定义预期列值的最大字节大小 \set SQLTERM / DECLARE c integer; n int; result text; dc int; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select * from t2', dbms_sql.native); dbms_sql.define_column(c, 1, n); dbms_sql.define_column(c, 2, result, 2); dbms_sql.close_cursor(c); END; / ---------------------------ANONYMOUS BLOCK 22.4.2.4.2 定义 CHAR 类型接收单行列值 语法格式 DBMS_SQL.DEFINE_COLUMN ( handle IN INTEGER, pos IN INTEGER, val ANYELEMENT, column_size IN INTEGER); 140 第 22 章 DBMS_SQL 功能描述 为 select 游 标 定 义 被 选 择 的 列， 定 义 后 可 通 过 column_value 取 出 对 应 列 的 值， 其 中 列 类 型 必 须 是 CHAR,VARCHAR,TEXT。 参数说明 参数 描述 handle 游标 ID pos 列在定义行中的相对位置。语句在第一列位置为 1。 val 定义的列的值。此值的类型决定了所定义列的类型。 CHAR VARCHAR TEXT column_size 类型为 CHAR,VARCHAR2,TEXT 的列的预期列值的 最大字节大小 示例 define_column_char 可以指定预期列值的最大字节大小，如下所示: \set SQLTERM ; drop table t2; create table t2(id int,name text); insert into t2 values (1,'zs'); \set SQLTERM / DECLARE c integer; n int; result varchar2(10); dc int; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select * from t2', dbms_sql.native); dbms_sql.define_column(c, 1, n); dbms_sql.define_column_char(c, 2, result, 2); dbms_sql.close_cursor(c); END; / 141 第 22 章 DBMS_SQL ---------------------------ANONYMOUS BLOCK 22.4.2.4.3 定义关联数组类型接收单行列值 语法格式 DBMS_SQL.DEFINE_ARRAY ( handle IN INTEGER, pos IN INTEGER, val IN ANYELEMENT, cnt IN INTEGER, lower_bnd IN INTEGER); 功能描述 定义一个集合类型接收某一列的值。这个过程允许您从单个 SELECT 语句批量提取行。FETCH_ROWS 调用 后，会将许多行存入 PL/SQL 聚合对象中。当你获取这些行时，它们将被赋值到 DBMS_SQL 缓存区中，直到运行 一个 COLUMN_VALUE 调用，这时这些行将被复制到作为参数传递给 COLUMN_VALUE 调用的表中。 参数说明 142 第 22 章 DBMS_SQL 参数 描述 handle 游标 ID pos 列在定义行中的相对位置。语句在第一列位置为 1。 val 定义的列的值。此值的类型决定了所定义列的类型。 datatype clob_table binary_float_table binary_double_table blob_table bfile_table date_table number_table varchar2_table time_table time_with_time_zone_table timestamp_table timestamp_with_ltz_table timestamp_with_time_zone_table cnt 必须提取的行数 lower_bnd 从下限索引开始，将结果复制到集合中 示例 define_array 接口定义关联数组类型接收单行列值，如下所示: \set SQLTERM ; drop table t2; create table t2(id int,name text); insert into t2 values (1,'zs'); \set SQLTERM / DECLARE c integer; n dbms_sql.number_table; result dbms_sql.varchar2_table; dc int; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select * from t2', dbms_sql.native); dbms_sql.define_array(c, 1, n, 1, 1); 143 第 22 章 DBMS_SQL dbms_sql.define_array(c, 2, result, 1, 1); dbms_sql.close_cursor(c); END; / ---------------------------ANONYMOUS BLOCK 22.4.2.5 执行游标 语法格式 DBMS_SQL.EXECUTE ( handle INTEGER) RETURN INTEGER; 功能描述 执行给定的游标，返回已处理的行数（仅对 INSERT、UPDATE 和 DELETE 语句，其他类型的语句返回值是 不确定的）。 参数说明 参数 描述 handle 游标 ID 返回值 返回已处理的行数。 使用说明 TO_CURSOR_NUMBER 函数返回的 DBMS_SQL 游标的执行方式与已经执行的 DBMS_SQL 游标相同。 示例： \set SQLTERM / declare c NUMBER; r NUMBER; BEGIN c := DBMS_SQL.OPEN_CURSOR(); DBMS_SQL.PARSE(c, 'create table if not exists tx (i int)', DBMS_SQL.NATIVE); r := DBMS_SQL.EXECUTE(c); DBMS_SQL.close_cursor(c); 144 第 22 章 DBMS_SQL END; / 22.4.2.6 检索游标 语法格式 DBMS_SQL.FETCH_ROWS ( handle INTEGER) RETURN INTEGER; 功能描述 从给定游标中获取数据，并且返回实际获取的行数。只要还有行需要提取，就可以重复调用 FETCH_ROWS。 这 些 行 被 检 索 到 缓 冲 区 中， 如 果 需 要 读 取 数 据 则 需 要 调 用 COLUMN_VALUE 函 数 来 读 取。 不 能 采 用 NO_DATA_FOUND 或游标属性%NOTFOUND 判断是否检索到数据。 参数说明 参数 描述 handle 游标 ID 返回值 返回实际获取的行数。 使用说明 如果该游标不是关联 select 语句，调用该方法则报错“fetch out of sequence”。 示例 FETCH_ROWS 接口用于检索游标，如下所示: set serverout on \set SQLTERM / drop table t1; / create table t1(i int); / insert into t1 values(1),(2),(3); / declare c NUMBER; d NUMBER; begin 145 第 22 章 DBMS_SQL c := DBMS_SQL.OPEN_CURSOR; DBMS_SQL.PARSE(c, 'SELECT * FROM t1', DBMS_SQL.NATIVE); d := DBMS_SQL.EXECUTE_AND_FETCH(c); dbms_output.put_line('d:'||d); d := DBMS_SQL.FETCH_ROWS(c); dbms_output.put_line('d:'||d); DBMS_SQL.CLOSE_CURSOR(c); end; / ----------------------ANONYMOUS BLOCK d:1 d:1 22.4.2.7 执行游标，并检索游标 语法格式 DBMS_SQL.EXECUTE_AND_FETCH ( handle INTEGER, exact BOOL DEFAULT FALSE) RETURN INTEGER; 功能描述 执行游标，检索数据，返回实际检索行的数量。 参数说明 参数 描述 handle 游标 ID exact 设置为 TRUE，如果当查询行的数量与检索行的数量不 同，则抛出异常。 返回值 返回指定的行数。 示例 参照 FETCH_ROWS 示例。 146 第 22 章 22.4.2.8 22.4.2.8.1 DBMS_SQL 返回游标中指定类型列值 返回游标基础数据类型的列值 语法格式 DBMS_SQL.COLUMN_VALUE ( handle INTEGER, pos INTEGER, val IN OUT ANYELEMENT ); 功能描述 用于访问给定游标，给定位置，指定为基本数据类型的列值。此过程用于获取 fetch_rows 调用后的数据。 参数说明 参数 描述 handle 游标 ID pos 列在定义行中的相对位置。语句在第一列位置为 1。 val 返回指定列处的值。 BINARY_DOUBLE BINARY_FLOAT BFILE BLOB CLOB DATE DSINTERVAL_UNCONSTRAINED NUMBER TIME_TZ_UNCONSTRAINED TIME_UNCONSTRAINED TIMESTAMP_LTZ_UNCONSTRAINED TIMESTAMP_TZ_UNCONSTRAINED TIMESTAMP_UNCONSTRAINED UROWID VARCHAR2 YMINTERVAL_UNCONSTRAINED ADT(user-defined object types) COLLECTIONS (varrays and nested tables) REFS OPAQUE TYPES 147 第 22 章 DBMS_SQL 示例 使用 dbms_sql 接口函数从 dbmssql_table1 表中获取结果集，示例如下: \set SQLTERM / create table if not exists dbmssql_table1 (i int, j TEXT); / insert into dbmssql_table1 values (1, 'foo'); insert into dbmssql_table1 values (2, 'bar'); / DECLARE c integer; n int; i int; j text := 'who'; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select i, j from dbmssql_table1', dbms_sql.native); dbms_sql.define_column(c, 1, i); dbms_sql.define_column(c, 2, j); n := dbms_sql.execute(c); LOOP exit when dbms_sql.fetch_rows(c) <= 0; dbms_sql.column_value(c, 1, i); dbms_sql.column_value(c, 2, j); raise notice 'i = %, j = %', i, j; raise notice 'last_row_count = %', dbms_sql.last_row_count(); END LOOP; dbms_sql.close_cursor(c); END; / --------------------------NOTICE: i = 1, j = foo NOTICE: last_row_count = 1 NOTICE: i = 2, j = bar NOTICE: last_row_count = 2 ANONYMOUS BLOCK 22.4.2.8.2 返回游标关联数组类型的列值 语法格式 DBMS_SQL.COLUMN_VALUE ( handle INTEGER, pos INTEGER, val IN OUT ANYELEMENT ); 148 第 22 章 DBMS_SQL 功能描述 用于访问给定游标，给定位置，指定为关联数组类型的列值。此过程用于获取 fetch_rows 调用后的数据。 参数说明 参数 描述 handle 游标 ID pos 列在定义行中的相对位置。语句在第一列位置为 1。 val 返回指定列处的值。类型为 clob_table binary_float_table binary_double_table blob_table bfile_table date_table number_table varchar2_table time_table time_with_time_zone_table timestamp_table timestamp_with_ltz_table timestamp_with_time_zone_table 示例 使用 dbms_sql 接口函数从 dbmssql_table1 表中获取结果集，并将结果集赋值到关联数组中，示例如下: \set SQLTERM / create table if not exists dbmssql_table1 (i int, j TEXT); / insert into dbmssql_table1 values (1, 'foo'); insert into dbmssql_table1 values (2, 'bar'); / DECLARE c integer; n int; i dbms_sql.number_table; j dbms_sql.varchar2_table; r int; 149 第 22 章 DBMS_SQL BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select i, j from dbmssql_table1', dbms_sql.native); dbms_sql.define_array(c, 1, i, 3, 1); dbms_sql.define_array(c, 2, j, 3, 1); n := dbms_sql.execute(c); n := dbms_sql.fetch_rows(c); dbms_sql.column_value(c, 1, i); dbms_sql.column_value(c, 2, j); for r in i.first..i.last LOOP raise notice 'i(%) = %, j(%) = %', r, i(r), r, j(r); END LOOP; dbms_sql.close_cursor(c); END; / --------------------------NOTICE: i(1) = 1, j(1) = foo NOTICE: i(2) = 2, j(2) = bar ANONYMOUS BLOCK 22.4.2.8.3 返回游标 CHAR 类型的列值 语法格式 DBMS_SQL.COLUMN_VALUE_CHAR ( handle INTEGER, pos INTEGER, val IN OUT ANYELEMENT ); 功能描述 同 COLUMN_VALUE，COLUMN_VALUE 和 COLUMN_VALUE_CHAR 都可以用来返回 CHAR 类型或者 非 CHAR 的类型的值。 22.4.2.9 22.4.2.9.1 返回游标中给定变量的值 返回游标基础数据类型的变量值 语法格式 150 第 22 章 DBMS_SQL DBMS_SQL.VARIABLE_VALUE ( handle IN INTEGER, pos IN INTEGER, val IN OUT ANYELEMENT); 功能描述 这个过程返回给定游标的命名变量的值，它用于返回 PL/SQL 块或带有 RETURNING 短语的 DML 语句中绑定 变量的值。 参数说明 参数 描述 handle 游标 ID pos 需要返回值的占位符的位置 val 返回指定位置的变量的值。 BINARY_DOUBLE BINARY_FLOAT BFILE BLOB CLOB DATE DSINTERVAL_UNCONSTRAINED NUMBER TIME_TZ_UNCONSTRAINED TIME_UNCONSTRAINED TIMESTAMP_LTZ_UNCONSTRAINED TIMESTAMP_TZ_UNCONSTRAINED TIMESTAMP_UNCONSTRAINED UROWID VARCHAR2 YMINTERVAL_UNCONSTRAINED ADT(user-defined object types) COLLECTIONS (varrays and nested tables) REFS OPAQUE TYPES 示例 使用 variable_value 接口函数获取绑定变量的值，示例如下: 151 第 22 章 DBMS_SQL \set SQLTERM / create table if not exists dbmssql_table1 (i int, j TEXT); / insert into dbmssql_table1 values (1, 'foo'); insert into dbmssql_table1 values (2, 'bar'); / DECLARE c integer; r int; x text := 'bar'; y varchar2; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select * from dbmssql_table1 where j = :xx', dbms_sql.native); dbms_sql.bind_variable(c, 1, x); r := dbms_sql.execute(c); dbms_sql.variable_value(c, 1, y); raise notice 'y1 = %', y; dbms_sql.close_cursor(c); END; / --------------------------NOTICE: y1 = bar ANONYMOUS BLOCK 22.4.2.9.2 返回游标关联数组类型的变量值 语法格式 DBMS_SQL.VARIABLE_VALUE ( handle IN INTEGER, pos IN INTEGER, val IN OUT ANYELEMENT); 功能描述 这个过程返回给定游标的命名变量的值，它用于返回 PL/SQL 块或带有 RETURNING 短语的 DML 语句中绑定 变量的值。 参数说明 152 第 22 章 参数 描述 handle 游标 ID pos 需要返回值的占位符的位置 val 数组选项返回指定位置的变量的值。 DBMS_SQL clob_table binary_float_table binary_double_table blob_table bfile_table date_table number_table varchar2_table time_table time_with_time_zone_table timestamp_table timestamp_with_ltz_table timestamp_with_time_zone_table 示例 使用 variable_value 接口函数获取绑定变量的值，示例如下: \set SQLTERM / create table if not exists dbmssql_table1 (i int, j TEXT); / insert into dbmssql_table1 values (1, 'foo'); insert into dbmssql_table1 values (2, 'bar'); / DECLARE c integer; r int; i int; x dbms_sql.varchar2_table; y dbms_sql.varchar2_table; BEGIN c := dbms_sql.open_cursor(); x(1) := 'foo'; x(2) := 'bar'; dbms_sql.parse(c, 'select * from dbmssql_table1 where j = :xx', dbms_sql.native); dbms_sql.bind_array(c, 1, x); r := dbms_sql.execute(c); 153 第 22 章 DBMS_SQL dbms_sql.variable_value(c, 1, y); for i in y.first..y.last LOOP raise notice 'y(%) = %', i, y(i); END LOOP; dbms_sql.close_cursor(c); END; / --------------------------NOTICE: y(1) = foo NOTICE: y(2) = bar ANONYMOUS BLOCK 22.4.2.9.3 返回游标 CHAR 类型的变量值 语法格式 DBMS_SQL.VARIABLE_VALUE_CHAR ( handle IN INTEGER, pos IN INTEGER, val IN OUT ANYELEMENT); 功能描述 同 VARIABLE_VALUE，VARIABLE_VALUE 和 VARIABLE_VALUE_CHAR 都可以用来返回 CHAR 类型 或者非 CHAR 的类型的值。 22.4.2.9.4 返回游标包中类型的变量值 语法格式 DBMS_SQL.VARIABLE_VALUE_PKG ( handle IN INTEGER, pos IN INTEGER, val IN OUT ANYELEMENT); 功能描述 同 VARIABLE_VALUE，VARIABLE_VALUE 和 VARIABLE_VALUE_PKG 都可以用来返回包中类型或者 非包中类型的值。 22.4.2.10 获取查询项的描述信息 22.4.2.10.1 获取查询项的描述信息，为 DESC_TAB 类型 语法格式 154 第 22 章 DBMS_SQL DBMS_SQL.DESCRIBE_COLUMNS ( handle INTEGER, col_cnt OUT INTEGER, desc_t OUT DBMS_SQL.DESC_TAB); 功能描述 这个过程返回描述查询列表的所有列信息，需要经过调用 DBMS_SQL 包中 OPEN_CURSOR 过程和 PARSE 过程。 参数说明 参数 描述 handle 被描述列的游标 ID 号 col_cnt select 语句中列表中的列数 desc_t 返回描述表，表中记录了查询列表中每个列的描述 示例 对 select 语句做 PARSE 操作后，可以使用 DESCRIBE_COLUMNS 接口函数获取相关表的表结构信息，示例 如下: set serverout on \set SQLTERM ; drop table t1; create table t1(id int,name varchar(50)); \set SQLTERM / CREATE OR REPLACE PROCEDURE pr1 IS v3 DBMS_SQL.DESC_TAB; v4 int; col_num int; cursor_id int; BEGIN cursor_id :=DBMS_SQL.OPEN_CURSOR; DBMS_SQL.PARSE(cursor_id, 'SELECT * FROM t1', DBMS_SQL.NATIVE); DBMS_SQL.DESCRIBE_COLUMNS(cursor_id,v4,v3); col_num := v3.first; dbms_output.put_line('col_num:'||col_num); WHILE col_num IS NOT NULL LOOP dbms_output.put_line(v3(col_num).col_max_len); col_num := v3.next(col_num); dbms_output.put_line('col_num:'||col_num); END LOOP; DBMS_SQL.CLOSE_CURSOR(cursor_id); 155 第 22 章 DBMS_SQL END; / call pr1(); / ------------------------------CALL col_num:1 4 col_num:2 50 col_num: 22.4.2.11 关闭游标 语法格式 DBMS_SQL.CLOSE_CURSOR ( handle IN OUT INTEGER); 功能描述 用于关闭游标 ID，并释放占用的内存空间。 参数说明 参数 模式 描述 handle IN 游标 ID handle OUT 游标被设置为 NULL。 在 调 用 CLOSE_CURSOR 后， 分 配 给 游 标 的内存被释放，您不能再从该游标中获 取数据。 示例 参照 OPEN_CURSOR 示例。 22.4.2.12 判断游标是否打开 语法格式 156 第 22 章 DBMS_SQL DBMS_SQL.IS_OPEN ( c IN INTEGER) RETURN BOOLEAN; 功能描述 检查指定的游标是否已经打开。 参数说明 参数 模式 描述 c IN 游标 ID 返回值说明 对于已打开但未关闭的任何游标编号返回 TRUE， 对 于 NULL 游标编号返回 FALSE， 请 注 意， CLOSE_CURSOR 过程会将传递给它的游标变量设为 NULL。 示例 is_open 接口用于判断游标是否打开，如下所示: \set SQLTERM ; create table if not exists dbmssql_table1(i int, J TEXT); \set SQLTERM / DECLARE c integer; r int; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'select i, j from dbmssql_table1', dbms_sql.native); if dbms_sql.is_open(c) then dbms_sql.close_cursor(c); raise notice 'A opened, now close it'; end if; END; / ----------------------------------NOTICE: A opened, now close it ANONYMOUS BLOCK 22.4.2.13 返回累计检索出来的行的数量 语法格式 157 第 22 章 DBMS_SQL DBMS_SQL.LAST_ROW_COUNT RETURN INTEGER; 功能描述 这个函数返回所获取的行数的累计计数。 返回值说明 返回所获取的行数的累计计数。 使用说明 在 FETCH_ROWS 或 EXECUTE_AND_FETCH 调用之后调用这个函数。如果在 EXECUTE 调用之后马上 调用此函数，则返回的值为 0。 示例 通过 last_row_count 接口可以获取当前处理的行数，示例如下: set serverout on \set SQLTERM ; drop table t2; create table t2(id int,name int); \set SQLTERM / DECLARE c integer; r int; a int := 10; b int := 20; BEGIN c := dbms_sql.open_cursor(); dbms_sql.parse(c, 'insert into t2 values (:1, :2)', dbms_sql.native); dbms_sql.bind_variable(c, '1', a); dbms_sql.bind_variable(c, '2', b); r := dbms_sql.execute(c); dbms_output.put_line( 'r:' || r); dbms_output.put_line( dbms_sql.last_row_count); dbms_sql.close_cursor(c); END; / ---------------------------ANONYMOUS BLOCK r:1 1 158 第 22 章 22.4.2.14 DBMS_SQL 游标转换 22.4.2.14.1 将游标变量转换为 DBMS_SQL 包内部游标 语法格式 DBMS_SQL.TO_CURSOR_NUMBER( c INOUT refcursor) RETURN INTEGER 功能描述 该函数接受一个打开的强类型或弱类型 ref 游标，并将其转换为 DBMS_SQL 游标号。 参数说明 参数 描述 c 游标变量 返回值说明 返回从 REF 游标转换而来的 DBMS_SQL 中可管理的游标 ID。 使用说明 1) 必须打开传入的 REF 游标，否则会引发错误。 2) 在将 REF 游标转换为 DBMS_SQL 游标号之后，任何本地动态 SQL 操作不再可以访问 REF 游标。 3) 这个子程序返回的 DBMS_SQL 游标的执行方式与已经执行的 DBMS_SQL 游标相同。 示例 游标变量转换为 DBMS_SQL 包内部游标，示例如下: \set SQLTERM ; create table if not exists dbmssql_table1 (i int, j TEXT); \set SQLTERM / DECLARE v_cur int; i int; j text; v_count int; cur refcursor; BEGIN open cur for select i, j from dbmssql_table1; v_cur := dbms_sql.TO_CURSOR_NUMBER(cur); dbms_sql.define_column(v_cur, 1, i); 159 第 22 章 DBMS_SQL dbms_sql.define_column(v_cur, 2, j); loop v_count := dbms_sql.fetch_rows(v_cur); exit when v_count <= 0; dbms_sql.column_value_char(v_cur, 1, i); dbms_sql.column_value(v_cur, 2, j); raise notice 'i = %, j = %', i, j; END LOOP; dbms_sql.close_cursor(v_cur); END; / ---------------------------NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar ANONYMOUS BLOCK 22.4.2.14.2 将 DBMS_SQL 包内的游标转换为本地动态 SQL 游标 语法格式 DBMS_SQL.TO_REFCURSOR( c INTEGER) RETURN refcursor 功能描述 将使用 DBMS_SQL 包打开、解析、执行过的游标 ID 转换为本地动态 SQL 可管理的 REF 游标（弱类型游 标），可供本地动态 SQL 使用。此子程序只与 select 游标一起使用。 参数说明 参数 描述 c 游标 ID 返回值说明 返回从 DBMS_SQL 游标 ID 转换而来的 PL/SQL REF 游标。 使用说明 1) 通过 cursor_name 传入的游标必须被打开、解析和执行，否则会引发错误。 2) 将 cursor_name 转换为 REF 游标后，任何 DBMS_SQL 操作都不能访问 cursor_number。 160 第 22 章 DBMS_SQL 3) 在使用 DBMS_SQL 将 cursor_name 转换为 REF 游标之后，IS_OPEN 检查 cursor_name 是否打开会导致错 误。 示例 DBMS_SQL 包内的游标经过 execute 操作后，可使用 to_refcursor 转换为本地动态 SQL 游标，示例如下: \set SQLTERM ; create table if not exists dbmssql_table1 (i int, j TEXT); \set SQLTERM / DECLARE v_cur number; sql_string varchar2(1024); i int; j text; v_count int; cur refcursor; v_name varchar2(60); BEGIN v_name := 'zs'; v_cur := dbms_sql.open_cursor(); sql_string := 'select i, j from dbmssql_table1'; dbms_sql.parse(v_cur, sql_string, dbms_sql.native); v_count := dbms_sql.execute(v_cur); cur := dbms_sql.to_refcursor(v_cur); loop fetch cur into i, j; exit when cur%notfound; raise notice 'i = %, j = %', i, j; END LOOP; close cur; END; / ---------------------------NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar ANONYMOUS BLOCK 22.4.2.15 返回语句结果集 语法格式 161 第 22 章 DBMS_SQL DBMS_SQL.RETURN_RESULT( rc IN refcursor, to_client IN BOOLEAN DEFAULT TRUE) DBMS_SQL.RETURN_RESULT( rc IN INTEGER, to_client IN BOOLEAN DEFAULT TRUE) 参数说明 参数 描述 rc 游标变量或游标 ID to_client 预留参数，暂无意义 功能描述 DBMS_SQL.RETURN_RESULT 过 程 让 子 程 序 隐 式 地 将 查 询 结 果 返 回 给 客 户 机 程 序 （它 间 接 调 用 子 程 序） 或 子 程 序 的 直 接 调 用 者。 直 接 调 用 者 执 行 递 归 语 句， 在 递 归 语 句 中 返 回 该 语 句 结 果。 在 DBMS_SQL.RETURN_RESULT 调用后，该语句结果只有接收者可以访问它。 使用说明 1) 目前只能返回 SQL 查询，不支持通过远程过程调用返回语句结果。 2) 一旦使用该方法后，除了返回它的客户端或直接调用者外，就不能再访问它了。 3) 当客户端执行的语句或任何中间递归语句是 SQL 查询并引发错误时，不能返回语句结果。 4) 返回的 ref 游标可以是强类型的，也可以是弱类型的。 5) 返回的查询可以部分获取。 6) 要从 PL/SQL 中的递归语句检索返回的语句结果，可以使用 DBMS_SQL 执行递归语句。 示例 通过 return_result 接口将结果集返回到客户端，示例如下: \set SQLTERM ; create table if not exists dbmssql_table1 (i int, j TEXT); \set SQLTERM / DECLARE cur1 refcursor; cur2 int; i_ret int; BEGIN OPEN cur1 for select * from dbmssql_table1; dbms_sql.return_result(cur1); 162 第 22 章 DBMS_SQL cur2 := dbms_sql.open_cursor(TRUE); dbms_sql.parse(cur2, 'select * from dbmssql_table1;',dbms_sql.native); i_ret := dbms_sql.execute(cur2); dbms_sql.return_result(cur2); END; / ---------------------------i | j ---+----1 | foo 2 | bar (2 rows) i | j ---+----1 | foo 2 | bar (2 rows) ANONYMOUS BLOCK 22.4.2.16 接收 RETURN_RESULT 过程的一个返回结果，并返回给客户端应用程 序 语法格式 DBMS_SQL.GET_NEXT_RESULT( c IN INTEGER, rc OUT refcursor) 参数 描述 c 表示一个已经打开的游标 ID， 该 游 标 直 接 或 间 接 调 用 一 个 子 程 序， 而 子 程 序 调 用 RE- TURN_RESULT 过程隐式返回一个查询结果。 表示一个 SYS_REFCURSOR 类型的游标变量或者一个已经打开的游标 ID，接收一个 RE- rc TURN_RESULT 过程返回的结果。 功能描述 GET_NEXT_RESULT 过程获取 RETURN_RESULT 过 程 返 回 的 一 个 查 询 结 果， 并 返 回 给 接 收 者。 163 第 22 章 DBMS_SQL GET_NEXT_RESULT 与 RETURN_RESULT 返回结果的顺序相同。 使用说明 1) 在检索语句结果的游标之后，调用者必须在不再需要游标时正确关闭该游标。 2) 所有未检索返回语句的游标将在递归语句的游标关闭后关闭。 3) 要打开游标并获得它的游标 ID，请调用 DBMS_SQL.OPEN_CURSOR 方法,DBMS_SQL.OPEN_CURSOR 有一个可选的参数 treat_as_client。当此参数为 FALSE（默认参数）时，打开此游标（用来调用子程序） 的调用方不会被视为客户端接受查询结果的子程序，相反，这些查询结果在较上层返回给客户机。如果 treat_as_client 为 TRUE，调用者将被视为客户端。 示例 使用游标变量和 dbms_sql 游标获取 RETURN_RESULT 过程返回的结果集，示例如下: \set SQLTERM ; create table if not exists dbmssql_table1 (i int, j TEXT); \set SQLTERM / --将游标的结果集返回给 get_results 的调用者 CREATE OR REPLACE PROCEDURE get_results(p_id IN NUMBER DEFAULT NULL) AS cur1 refcursor; cur2 refcursor; BEGIN IF p_id IS NOT NULL THEN OPEN cur1 for select * from dbmssql_table1; dbms_sql.return_result(cur1); END IF; OPEN cur2 for select * from dbmssql_table1; dbms_sql.return_result(cur2); END; / --使用游标变量获取 RETURN_RESULT 过程返回的结果集 DECLARE c integer; c1 integer; sqlstmt varchar2(1024); rc refcursor; i_ret int; i int; j text; BEGIN c := dbms_sql.open_cursor(TRUE); sqlstmt := 'begin get_results(1);end;'; dbms_sql.parse(c, sqlstmt,dbms_sql.native); i_ret := dbms_sql.execute(c); 164 第 22 章 DBMS_SQL loop BEGIN --使用 rc 接收 c 的结果集 dbms_sql.get_next_result(c,rc); exception when no_data_found then exit; END; loop fetch rc into i, j; exit when rc%NOTFOUND; raise notice 'i = %, j = %', i, j; end loop; end loop; dbms_sql.close_cursor(c); END; / ---------------------------NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar ANONYMOUS BLOCK --使用 dbms_sql 游标获取 RETURN_RESULT 过程返回的结果集 \set SQLTERM / DECLARE c integer; c1 integer; sqlstmt varchar2(1024); rc refcursor; i_ret int; i int; j text; BEGIN c := dbms_sql.open_cursor(TRUE); sqlstmt := 'begin get_results(1);end;'; dbms_sql.parse(c, sqlstmt,dbms_sql.native); i_ret := dbms_sql.execute(c); loop BEGIN dbms_sql.get_next_result(c,c1); 165 第 22 章 DBMS_SQL exception when no_data_found then exit; END; dbms_sql.define_column(c1, 1, i); dbms_sql.define_column(c1, 2, j); LOOP exit when dbms_sql.fetch_rows(c1) <= 0; dbms_sql.column_value(c1, 1, i); dbms_sql.column_value(c1, 2, j); raise notice 'i = %, j = %', i, j; END LOOP; end loop; dbms_sql.close_cursor(c1); END; / ---------------------------NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar NOTICE: i = 1, j = foo NOTICE: i = 2, j = bar ANONYMOUS BLOCK 22.4.2.17 返回 SQL 语句错误发生处的字节偏移量 语法格式 DBMS_SQL.LAST_ERROR_POSITION() RETURN INTEGER 功能描述 这个函数返回发生错误的 SQL 语句文本中的字节偏移量。SQL 语句中的第一个字符位于位置 0。 返回值说明 返回发生错误的 SQL 语句文本中的字节偏移量。 使用说明 调用该函数在 PARSE 调用之后，在调用任何其他 DBMS_SQL 过程或函数之前。 示例 166 第 22 章 DBMS_SQL 在异常块中使用 LAST_ERROR_POSITION 接口获取语句错误位置，示例如下: \set SQLTERM ; create table if not exists dbmssql_table1 (i int, j TEXT); \set SQLTERM / DECLARE v_cur int; sql_string varchar2(1024); v_count int; error_offset number; b int := 1; BEGIN sql_string := 'select i, j, k from dbmssql_table1'; v_cur := dbms_sql.open_cursor(); dbms_sql.parse(v_cur, sql_string, dbms_sql.native); v_count := dbms_sql.execute(v_cur); v_count := dbms_sql.fetch_rows(v_cur); exception when others then error_offset := DBMS_SQL.LAST_ERROR_POSITION(); raise notice 'error_offset:%',error_offset; dbms_sql.close_cursor(v_cur); END / ---------------------------NOTICE: error_offset:13 ANONYMOUS BLOCK 22.4.2.18 返回该语句的 SQL 函数代码 语法格式 DBMS_SQL.LAST_SQL_FUNCTION_CODE RETURN INTEGER; 功能描述 返回该语句的 SQL 函数代码。 返回值说明 返回该语句的 SQL 函数代码。 167 第 22 章 DBMS_SQL 使用说明 1) 该函数在未执行任何语句时调用返回默认值 0。 2) 在 PARSE 语句之后该函数返回语句的 SQL 函数代码。 3) 同一个 session 中，如果之前执行的 PLSQL 过程已调用一次 PARSE 语句，且当前 PLSQL 过程未调用 OPEN_CURSOR 函数，该函数返回上一次 PARSE 的值；调用 OPEN_CURSOR 后，PARSE 语句前调用， 返回默认值 0。 SQL SQL 语句 代码 SQL SQL 语句 代码 SQL SQL 语句 代码 01 CREATE TABLE 43 (NOT USED) 85 TRUNCATE TABLE 02 SET ROLE 44 (NOT USED) 86 (NOT USED) 03 INSERT 45 (NOT USED) 87 (NOT USED) 04 SELECT 46 (NOT USED) 88 (NOT USED) 05 UPDATE 47 (NOT USED) 89 (NOT USED) 06 DROP ROLE(USER) 48 (NOT USED) 90 SET CONSTRAINTS 07 DROP VIEW 49 (NOT USED) 91 CREATE FUNCTION 08 DROP TABLE 50 (NOT USED) 92 (NOT USED) 09 DELETE 51 (NOT USED) 93 DROP FUNCTION 10 CREATE VIEW 52 (NOT USED) 94 CREATE PACKAGE 11 (NOT USED) 53 (NOT USED) 95 (NOT USED) 12 CREATE ROLE(USER) 54 (NOT USED) 96 DROP PACKAGE 13 CREATE SEQUENCE 55 (NOT USED) 97 (NOT USED) 14 ALTER SEQUENCE 56 (NOT USED) 98 (NOT USED) 15 (NOT USED) 57 (NOT USED) 99 DROP PACKAGE BODY 16 DROP SEQUENCE 58 (NOT USED) 157 (NOT USED) 17 CREATE SCHEMA 59 CREATE TRIGGER 158 DROP DIRECTORY 18 (NOT USED) 60 (NOT USED) 159 (NOT USED) 19 (NOT USED) 61 DROP TRIGGER 160 (NOT USED) 见续表 168 第 22 章 DBMS_SQL 表 22.4.1 – 续表 SQL SQL 语句 代码 SQL SQL 语句 代码 SQL SQL 语句 代码 20 CREATE INDEX 62 ANALYZE TABLE 161 (NOT USED) 21 DROP INDEX 63 (NOT USED) 162 (NOT USED) 22 (NOT USED) 64 (NOT USED) 163 CREATE OPERATOR 23 (NOT USED) 65 (NOT USED) 164 (NOT USED) 24 (NOT USED) 66 (NOT USED) 165 (NOT USED) 25 (NOT USED) 67 (NOT USED) 166 (NOT USED) 26 (NOT USED) 68 DROP PROCEDURE 167 DROP OPERATOR 27 EXPLAIN 69 (NOT USED) 168 (NOT USED) 28 GRANT 70 (NOT USED) 169 (NOT USED) 29 (NOT USED) 71 (NOT USED) 170 CALL METHOD 30 CREATE SYNONYM 72 (NOT USED) 171 (NOT USED) 31 DROP SYNONYM 73 (NOT USED) 172 (NOT USED) 32 (NOT USED) 74 (NOT USED) 173 (NOT USED) 33 SET TRANSACTION 75 (NOT USED) 174 (NOT USED) 34 PL/SQL EXECUTE 76 (NOT USED) 175 (NOT USED) 35 LOCK 77 CREATE TYPE 176 (NOT USED) 36 (NOT USED) 78 DROP TYPE 177 (NOT USED) 37 RENAME 79 (NOT USED) 178 (NOT USED) 38 COMMENT 80 (NOT USED) 179 (NOT USED) 39 (NOT USED) 81 (NOT USED) 180 (NOT USED) 40 (NOT USED) 82 (NOT USED) 181 (NOT USED) 41 (NOT USED) 83 DROP TYPE BODY 182 (NOT USED) 42 (NOT USED) 84 (NOT USED) 183 ALTER OPERATOR 示例 LAST_SQL_FUNCTION_CODE 接口在不同情况下调用，获取值可能不同，示例如下: 169 第 22 章 DBMS_SQL \set SQLTERM / create table if not exists dbmssql_table1 (i int, j TEXT); / \set SQLTERM / DECLARE sql_code int; c int; vc int; BEGIN c := dbms_sql.open_cursor; sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; dbms_sql.parse(c, 'insert into dbmssql_table1 values (1,''xxx'')', dbms_sql.native); vc := dbms_sql.execute(c); sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; dbms_sql.close_cursor(c); END; / \set SQLTERM ; ---------------------------NOTICE: 0 NOTICE: 3 NOTICE: 3 ANONYMOUS BLOCK set serverout on \set SQLTERM / DECLARE sql_code int; c int; vc int; BEGIN sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; c := dbms_sql.open_cursor; sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; dbms_sql.parse(c, 'insert into t1 values (1,''xx'')', dbms_sql.native); vc := dbms_sql.execute(c); sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); raise notice '%',sql_code; 170 第 22 章 DBMS_SQL sql_code := dbms_sql.LAST_SQL_FUNCTION_CODE(); dbms_output.put_line(sql_code); raise notice '%',sql_code; END; / \set SQLTERM ; ---------------------------NOTICE: 3 NOTICE: 0 NOTICE: 3 NOTICE: 3 ANONYMOUS BLOCK 22.4.2.19 其他示例 在一个匿名块分别对 create 语句、truncate 语句，以及 select 语句做动态 sql 操作，示例如下: set serverout on \set SQLTERM / DECLARE cnt integer; count integer := 0; descs DBMS_SQL.DESC_TAB; hander integer; res int; result_name text; my_id int := 10; my_name text := 'hello world'; my_text text; BEGIN hander := dbms_sql.open_cursor(); dbms_sql.parse(hander,'create table if not exists test_tmp(id int,sname text)',dbms_sql.native); count=dbms_sql.execute(hander); dbms_output.put_line( 'count:'||count); dbms_sql.parse(hander,'truncate table test_tmp',dbms_sql.native); count=dbms_sql.execute(hander); dbms_output.put_line( 'count:'||count); dbms_sql.parse(hander, 'select * from test_tmp', dbms_sql.native); dbms_sql.define_column(hander, 1, res); dbms_sql.define_column(hander, 2, result_name); count = dbms_sql.execute_and_fetch(hander); 171 第 22 章 DBMS_SQL if count > 0 then dbms_sql.column_value(hander, 1, res); dbms_sql.column_value(hander, 2, result_name); dbms_output.put_line( dbms_sql.last_row_count); dbms_sql.describe_columns(hander, cnt, descs); dbms_output.put_line( 'describe_columns: ' || dbms_sql.last_row_count); end if; WHILE dbms_sql.fetch_rows(hander) > 0 LOOP dbms_sql.column_value(hander, 1, res); dbms_sql.column_value(hander, 2, result_name); dbms_output.put_line(dbms_sql.last_row_count); END LOOP; dbms_sql.close_cursor(hander); END; / -----------------------------ANONYMOUS BLOCK count:0 count:0 22.5 插件 dbms_sql 卸载方法 无法卸载。 22.6 插件 dbms_sql 升级方法 dbms_sql 随着 KingbaseES 安装包一并升级。通常，用户无须单独升级该插件。 172 第 23 章 DBMS_UTILITY 23章 dbms_utility 第 23.1 插件 dbms_utility 简介 插件 dbms_utility 是 KingbaseES 的一个扩展插件。插件 dbms_utility 功能是提供 dbms_utility 系统包。 dbms_utility 系统包提供一些具有通用功能的子程序，如查看错误堆栈、查看时间等。 • 插件名为 dbms_utility • 插件版本 V1.0 23.2 插件 dbms_utility 加载方式 该插件为初始化数据库实例时默认创建。 23.3 插件 dbms_utility 的参数配置 dbms_utility 扩展插件无需配置任何参数。 23.4 插件 dbms_utility 使用方法 DBMS_UTILITY 系统包包含的子程序及简介如下表所示： 173 第 23 章 子程序 简介 FORMAT_CALL_STACK 函数 返回当前的调用堆栈。 FORMAT_ERROR_BACKTRACE 函数 返回当前的错误回溯信息。 FORMAT_ERROR_STACK 函数 返回当前的错误堆栈。 GET_TIME 函数 返回一个时间戳。 GET_HASH_VALUE 函数 返回指定字符串的散列值。 DBMS_UTILITY 23.4.1 FORMAT_CALL_STACK 函数 该函数可以返回当前的调用堆栈信息，包括调用对象的地址，调用的行号和调用对象的名称，它可以用在函数、 存储过程或者触发器等 PL/SQL 对象中，用于帮助调试 PL/SQL 程序。 语法 DBMS_UTILITY.FORMAT_CALL_STACK() RETURN TEXT; DBMS_UTILITY.FORMAT_CALL_STACK(FORMAT TEXT) RETURN TEXT; 注意: 目前调用对象的地址为函数或过程的 oid 值，如果是内建函数或过程则为对应包的 oid 值。 使用说明 FORMAT: 指定调用堆栈信息的显示模式，分别有’o’, ’p’, ’s’ 三种模式。默认使用模式为’p’ 模式，输出 8 位有效 长度的十进制数输出对象地址信息。 • 其中’o’ 参数将按照’%8x%8d%s’ 格式打印对象地址，调用行号，对象名称，如示例 2 所示。 • 其中’p’ 参数将按照’%8d%8d%s’ 格式打印对象地址，调用行号，对象名称，如示例 3 所示。 • 其中’s’ 参数将按照’%d,%d,%s’ 格式打印对象地址，调用行号，对象名称，如示例 4 所示。 示例 示例 1 调用无参数的 format_call_stack 子程序，示例如下： \set SQLTERM / CREATE OR REPLACE FUNCTION checkCallStack() RETURNS TEXT AS stack TEXT; BEGIN SELECT dbms_utility.format_call_stack() INTO stack ; RETURN stack; END; 174 第 23 章 DBMS_UTILITY / \set SQLTERM ; call checkCallStack(); checkcallstack ------------------------------------------------------------------------ PL/SQL Call Stack ----- + object line object + handle number name + 14575 30 package body sys.dbms_utility.format_call_stack+ 16387 4 function public.checkcallstack (1 row) 示例 示例 2 调用传入’o’ 参数的 format_call_stack 子程序，示例如下： \set SQLTERM / CREATE OR REPLACE FUNCTION checkHexCallStack() RETURNS TEXT AS stack TEXT; BEGIN SELECT dbms_utility.format_call_stack('o') INTO stack ; RETURN stack; END; / \set SQLTERM ; CALL checkHexCallStack(); checkhexcallstack ------------------------------------------------------------------------ PL/SQL Call Stack ----- + object line object + handle number name + 38ef 22 package body sys.dbms_utility.format_call_stack+ 4004 4 function public.checkhexcallstack (1 row) 示例 示例 3 调用传入’p’ 参数的 format_call_stack 子程序，示例如下： \set SQLTERM / CREATE OR REPLACE FUNCTION checkIntCallStack() RETURNS TEXT AS stack TEXT; 175 第 23 章 DBMS_UTILITY BEGIN SELECT dbms_utility.format_call_stack('p') INTO stack ; RETURN stack; END; / \set SQLTERM ; CALL checkIntCallStack(); checkintcallstack -------------------------------------------------------------------+ 14575 22 package body sys.dbms_utility.format_call_stack+ 16389 4 function public.checkintcallstack (1 row) 示例 示例 4 调用传入’s’ 参数的 format_call_stack 子程序，示例如下： \set SQLTERM / CREATE OR REPLACE FUNCTION checkIntUnpaddedCallStack() RETURNS TEXT AS stack TEXT; BEGIN SELECT dbms_utility.format_call_stack('s') INTO stack ; RETURN stack; END; / \set SQLTERM ; call checkIntUnpaddedCallStack(); checkintunpaddedcallstack -------------------------------------------+ 14575,22,sys.dbms_utility.format_call_stack+ 16390,4,public.checkintunpaddedcallstack (1 row) 23.4.2 FORMAT_ERROR_BACKTRACE 函数 该函数用于返回当前程序发生异常时的错误回溯堆栈，若程序未发生异常，则返回 NULL。 语法 176 第 23 章 DBMS_UTILITY DBMS_UTILITY.FORMAT_ERROR_BACKTRACE() RETURN TEXT; 示例 format_error_backtrace 函数在异常时使用，示例如下： set serverout on \set SQLTERM / CREATE OR REPLACE PROCEDURE p01() AS i INT := 0; BEGIN i = i/0; END; / \set SQLTERM ; \set SQLTERM / CREATE OR REPLACE PROCEDURE p02() AS detail TEXT; stack TEXT; BEGIN p01(); EXCEPTION WHEN DIVISION_BY_ZERO THEN detail = dbms_utility.format_error_stack(); stack = dbms_utility.format_error_backtrace(); DBMS_OUTPUT.PUT_LINE('FORMAT_ERROR_STACK IS:'); DBMS_OUTPUT.PUT_LINE(detail); DBMS_OUTPUT.PUT_LINE('FORMAT_ERROR_BACKTRACE IS:'); DBMS_OUTPUT.PUT_LINE(stack); END; / \set SQLTERM ; CALL p02(); FORMAT_ERROR_STACK IS: division by zero at "public.p01", line 4 FORMAT_ERROR_BACKTRACE IS: at "public.p01", line 4 at "public.p02", line 5 177 第 23 章 DBMS_UTILITY 23.4.3 FORMAT_ERROR_STACK 函数 该函数用于返回当前程序发生异常时的错误堆栈，若程序未发生异常，则返回 NULL。 语法 DBMS_UTILITY.FORMAT_ERROR_STACK() RETURN TEXT; 示例 见FORMAT_ERROR_BACKTRACE 函数 。 23.4.4 GET_TIME 函数 该函数用于返回一个时间戳，该时间戳不是标准的系统时间戳，单位为厘秒（百分之一秒）。通常在 PL/SQL 程序开始和结束时各调用一次该函数，然后用后一个数字减去前一个数字，以确定当前程序的执行耗时。 语法 DBMS_UTILITY.GET_TIME() RETURN NUMBER; 使用说明 函数的返回值在 -2147483648 到 2147483647 之间，具体数值取决于机器和系统。调用该函数时，应用程序需要 考虑到返回值的符号。例如，两次调用皆为负数，或者第一次调用为负数，第二次调用为正数等情况。 示例 get_time 函数可用于计算语句运行时间，示例如下： \set SQLTERM / CREATE OR REPLACE PROCEDURE TestGetTime() AS t1 PLS_INTEGER; t2 PLS_INTEGER; BEGIN t1 := dbms_utility.get_time(); perform sys_sleep(3); t2 := dbms_utility.get_time(); RAISE NOTICE 'sleeped: % sec.', (t2 - t1) / 100; END; / \set SQLTERM ; call TestGetTime(); NOTICE: sleeped: 3 sec. 178 第 23 章 DBMS_UTILITY 23.4.5 GET_HASH_VALUE 函数 对于指定的字符串，返回范围在 [base, base+hase_size-1] 的散列值。 语法 DBMS_UTILITY.GET_HASH_VALUE( NAME VARCHAR2, BASE NUMBER, HASH_SIZE NUMBER )RETURN NUMBER; 参数说明 参数 描述 NAME 指定的要被 HASH 的字符串。 BASE 返回的 HASH 值的基准值，即返回值的最小值。 HASH_SIZE 指定的 HASH 表的大小。 返回值 基于输入字符串的哈希值。 异常说明 • BASE 参数为 NULL，则报错”bad argument”。 • HASH_SIZE 参数为 NULL，则报错”bad argument”。 • HASH_SIZE 为 0 时，则报错”bad argument”。 使用说明 • BASE 可为负值。 • 返回 HASH 值的最小值为 BASE；返回 HASH 值的最大值 BASH+HASH_SIZE-1。例如，若要获取哈希值介 于 1000 和 3047 之间的字符串的哈希值，请使用 1000 作为基值，使用 2048 作为 HASH 表大小。 • NAME 为 NULL 或空字符串，若其他参数正常，则返回 BASE 值。 • 若 HASH_SIZE 为负值则返回的哈希值不在哈希范围内，哈希值可能为正，也可能为负。 示例 select DBMS_UTILITY.GET_HASH_VALUE('hello world',1,100) from dual; get_hash_value ---------------- 179 第 23 章 DBMS_UTILITY 61 (1 row) 23.5 插件 dbms_utility 卸载方法 无法卸载。 23.6 插件 dbms_utility 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.0 升级到 1.1 ALTER EXTENSION dbms_utility UPDATE TO '1.1'; 180 第 24 章 DICT_INT 24章 dict_int 第 24.1 插件 dict_int 简介 dict_int 是一个附加的全文搜索词典模板的示例。这个示例词典的动机是控制有符号和无符号整数的索引，允许 对此类数字进行索引，同时防止唯一词数量的过度增长严重影响搜索性能。 • 插件名为 dict_int • 插件版本 V1.0 24.2 插件 dict_int 加载方式 CREATE EXTENSION dict_int; 24.3 插件 dict_int 的参数配置 该词典接受两个选项 maxlen 参数指定在一个整数词中允许的最大位数。默认值为 6。 rejectlong 参数指定一个超长整数是否应该被截断或忽略。如果 rejectlong 为 false（默认），该词典返回该 整数的第一个数字。如果 rejectlong 为 true，该词典将一个超长整数作为一个停用词对待，因此它将不会被索引。 **注意 ** 这也意味着这样一个整数不能被搜索。 24.4 插件 dict_int 的使用方法 安装 dict_int 扩展会使用默认参数创建一个文本搜索模板 intdict_template 和一个基于它的词典 intdict。 您可以修改 intdict 词典参数 181 第 24 章 DICT_INT ALTER TEXT SEARCH DICTIONARY intdict (MAXLEN = 4, REJECTLONG = true); 或者创建一个基于该模板的新词典 CREATE TEXT SEARCH DICTIONARY myintdict ( TEMPLATE = intdict_template ); 要测试 intdict 词典，可以尝试 SELECT ts_lexize('intdict', '12345678'); ts_lexize ----------{123456} 也可以将字典应用于文本搜索配置中 ALTER TEXT SEARCH CONFIGURATION english ALTER MAPPING FOR int, uint WITH intdict; 24.5 插件 dict_int 卸载方法 DROP EXTENSION dict_int; 24.6 插件 dict_int 升级方法 dict_int 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 ALTER EXTENSION dict_int UPDATE TO new_version; 182 第 25 章 DICT_XSYN 第 25.1 25章 dict_xsyn 插件 dict_xsyn 简介 dict_xsyn（扩展同义词字典）是一个附加全文搜索字典模板的例子。这种字典类型将词替换为它们的同义词分 组，并且让使用其任一同义词进行搜索变得可能。 25.2 插件 dict_xsyn 加载方式 create extension dict_xsyn; 25.3 插件 dict_xsyn 的参数配置 一个 dict_xsyn 词典接受以下选项 * matchorig 控制该词典是否接受原生词。默认为 true。 * matchsynonyms 控制该词典是否接受同义词。默认为 false。 * keeporig 控制原生词是否被包括在词典的输出中。默认为 true。 * keepsynonyms 控制同义词是否被包括在词典的输出中。默认为 true。 * rules 是包含同义词列表的文件的基本名。这个文件必须被存储在 $SHAREDIR/ tsearch_data/（其中 $SHAREDIR 表示 KingbaseES 安装的共享数据目录）中。它的名称必须以.rules 结束（这不包括在 rules 参数中）。 规则文件具有下面的格式 * 每一行表示一个单一词的同义词分组，它在该行中首先被给出。同义词被空白分隔，如下所示 word syn1 syn2 syn3 183 第 25 章 DICT_XSYN * 井号（#）是注释定界符。它可以出现在一行中的任何位置。该行的剩余部分将被跳过。 具体用例可以看看在 $SHAREDIR/tsearch_data/中的 xsyn_sample.rules。 25.4 插件 dict_xsyn 的使用方法 安装 dict_xsyn 扩展会用默认参数创建一个文本搜索模板 xsyn_template 以及一个基于它的词典 xsyn。你可以 修改参数，例如： ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false); 或者基于该模板创建新的词典。 要测试该词典，你可以尝试： SELECT ts_lexize('xsyn', 'word'); ts_lexize ----------------------{syn1,syn2,syn3} ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true); SELECT ts_lexize('xsyn', 'word'); ts_lexize ----------------------{word,syn1,syn2,syn3} ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=false, MATCHSYNONYMS=true); SELECT ts_lexize('xsyn', 'syn1'); ts_lexize ----------------------{syn1,syn2,syn3} ALTER TEXT SEARCH DICTIONARY xsyn (RULES='my_rules', KEEPORIG=true, MATCHORIG=false, KEEPSYNONYMS=false); SELECT ts_lexize('xsyn', 'syn1'); ts_lexize ----------------------{word} 在实际使用时可以将它包含在一个文本搜索配置中。如下所示： ALTER TEXT SEARCH CONFIGURATION english ALTER MAPPING FOR word, asciiword WITH xsyn, english_stem; 184 第 25 章 DICT_XSYN 25.5 插件 dict_xsyn 卸载方法 drop extension dict_xsyn; 25.6 插件 dict_xsyn 升级方法 dict_xsyn 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 185 第 26 章 EARTHDISTANCE 26章 earthdistance 第 26.1 插件 earthdistance 简介 earthdistance 支持了与地球表面相关的数据操作。 • 插件名为 earthdistance • 插件版本 V1.0 26.2 插件 earthdistance 加载方式 使用时需要 create extension earthdistance; 示例 create extension earthdistance; 26.3 插件 earthdistance 参数配置 无需配置任何参数。 26.4 插件 citext 使用方法 26.4.1 geo_distance 计算两点之间的地理距离。 语法 186 第 26 章 EARTHDISTANCE geo_distance(p1 point, p2 point ) RETURNS float8; 描述 计算点 p1 与 p2 之间的地理距离。 示例 TEST=# select geo_distance('(2,1)'::point,'(2,0)'::point); geo_distance -----------------69.0931819000054 (1 行记录) 26.4.2 earth 获取地球半径。 语法 earth() returns float8 描述 earth 会获取地球的半径长度。 示例 TEST=# select earth(); earth --------6378168 (1 行记录) 26.4.3 sec_to_gc 把直线距离转换为标准圆的距离。 语法 sec_to_gc(float8) returns float8; 示例 187 第 26 章 EARTHDISTANCE SELECT sec_to_gc(0)::numeric(20,5); sec_to_gc ----------0.00000 (1 row) SELECT sec_to_gc(2*earth())::numeric(20,5); sec_to_gc ---------------20037605.73216 (1 row) SELECT sec_to_gc(10*earth())::numeric(20,5); sec_to_gc ---------------20037605.73216 (1 row) SELECT sec_to_gc(-earth())::numeric(20,5); sec_to_gc ----------0.00000 (1 row) SELECT sec_to_gc(1000)::numeric(20,5); sec_to_gc -----------1000.00000 (1 row) 26.4.4 gc_to_sec 把标准圆的距离转换为直线距离。 语法 gc_to_sec(float8) returns float8; 示例 SELECT gc_to_sec(0)::numeric(20,5); gc_to_sec ----------0.00000 188 第 26 章 EARTHDISTANCE (1 row) SELECT gc_to_sec(sec_to_gc(2*earth()))::numeric(20,5); gc_to_sec ---------------12756336.00000 (1 row) SELECT gc_to_sec(10*earth())::numeric(20,5); gc_to_sec ---------------12756336.00000 (1 row) SELECT gc_to_sec(pi()*earth())::numeric(20,5); gc_to_sec ---------------12756336.00000 (1 row) SELECT gc_to_sec(-1000)::numeric(20,5); gc_to_sec ----------0.00000 (1 row) SELECT gc_to_sec(1000)::numeric(20,5); gc_to_sec -----------1000.00000 (1 row) SELECT gc_to_sec(10000)::numeric(20,5); gc_to_sec -----------9999.99898 (1 row) 26.4.5 ll_to_earth 通过经度和纬度计算地球表面距离地心的距离 语法 189 第 26 章 EARTHDISTANCE ll_to_earth(float8, float8) returns earth; 示例 SELECT cube_ll_coord(ll_to_earth(0,0),1)::numeric(20,5), cube_ll_coord(ll_to_earth(0,0),2)::numeric(20,5), cube_ll_coord(ll_to_earth(0,0),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord ---------------+---------------+--------------6378168.00000 | 0.00000 | 0.00000 (1 row) SELECT cube_ll_coord(ll_to_earth(360,360),1)::numeric(20,5), cube_ll_coord(ll_to_earth(360,360),2)::numeric(20,5), cube_ll_coord(ll_to_earth(360,360),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord ---------------+---------------+--------------6378168.00000 | 0.00000 | 0.00000 (1 row) SELECT cube_ll_coord(ll_to_earth(180,180),1)::numeric(20,5), cube_ll_coord(ll_to_earth(180,180),2)::numeric(20,5), cube_ll_coord(ll_to_earth(180,180),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord ---------------+---------------+--------------6378168.00000 | 0.00000 | 0.00000 (1 row) SELECT cube_ll_coord(ll_to_earth(180,360),1)::numeric(20,5), cube_ll_coord(ll_to_earth(180,360),2)::numeric(20,5), cube_ll_coord(ll_to_earth(180,360),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord ----------------+---------------+---------------6378168.00000 | 0.00000 | 0.00000 (1 row) SELECT cube_ll_coord(ll_to_earth(-180,-360),1)::numeric(20,5), cube_ll_coord(ll_to_earth(-180,-360),2)::numeric(20,5), cube_ll_coord(ll_to_earth(-180,-360),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord ----------------+---------------+---------------6378168.00000 | 0.00000 | 0.00000 (1 row) 190 第 26 章 EARTHDISTANCE 26.4.6 latitude 通过地球表面一点计算纬度。 语法 latitude(earth) returns float8; 示例 SELECT latitude(ll_to_earth(0,0))::numeric(20,10); latitude -------------0.0000000000 (1 row) SELECT latitude(ll_to_earth(45,0))::numeric(20,10); latitude --------------45.0000000000 (1 row) SELECT latitude(ll_to_earth(90,0))::numeric(20,10); latitude --------------90.0000000000 (1 row) SELECT latitude(ll_to_earth(-45,0))::numeric(20,10); latitude ----------------45.0000000000 (1 row) SELECT latitude(ll_to_earth(-90,0))::numeric(20,10); latitude ----------------90.0000000000 (1 row) SELECT latitude(ll_to_earth(0,90))::numeric(20,10); latitude -------------0.0000000000 (1 row) 191 第 26 章 EARTHDISTANCE SELECT latitude(ll_to_earth(45,90))::numeric(20,10); latitude --------------45.0000000000 (1 row) SELECT latitude(ll_to_earth(90,90))::numeric(20,10); latitude --------------90.0000000000 (1 row) SELECT latitude(ll_to_earth(-45,90))::numeric(20,10); latitude ----------------45.0000000000 (1 row) 26.4.7 longitude 通过地球表面一点计算纬度。 语法 longitude(earth) returns float8; 示例 SELECT longitude(ll_to_earth(0,0))::numeric(20,10); longitude -------------0.0000000000 (1 row) SELECT longitude(ll_to_earth(45,0))::numeric(20,10); longitude -------------0.0000000000 (1 row) SELECT longitude(ll_to_earth(90,0))::numeric(20,10); longitude -------------0.0000000000 192 第 26 章 EARTHDISTANCE (1 row) SELECT longitude(ll_to_earth(-45,0))::numeric(20,10); longitude -------------0.0000000000 (1 row) SELECT longitude(ll_to_earth(-90,0))::numeric(20,10); longitude -------------0.0000000000 (1 row) SELECT longitude(ll_to_earth(0,90))::numeric(20,10); longitude --------------90.0000000000 (1 row) SELECT longitude(ll_to_earth(45,90))::numeric(20,10); longitude --------------90.0000000000 (1 row) SELECT longitude(ll_to_earth(90,90))::numeric(20,10); longitude --------------90.0000000000 (1 row) SELECT longitude(ll_to_earth(-45,90))::numeric(20,10); longitude --------------90.0000000000 (1 row) SELECT longitude(ll_to_earth(-90,90))::numeric(20,10); longitude --------------90.0000000000 (1 row) SELECT longitude(ll_to_earth(0,180))::numeric(20,10); 193 第 26 章 EARTHDISTANCE longitude ---------------180.0000000000 (1 row) 26.4.8 earth_distance 计算地球表面两点之间的距离。 语法 earth_distance(earth, earth) returns float8; 示例 SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(0,0))::numeric(20,5); earth_distance ---------------0.00000 (1 row) SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(0,180))::numeric(20,5); earth_distance ---------------20037605.73216 (1 row) SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(90,0))::numeric(20,5); earth_distance ---------------10018802.86608 (1 row) SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(0,90))::numeric(20,5); earth_distance ---------------10018802.86608 (1 row) SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(0,1))::numeric(20,5); earth_distance ---------------111320.03185 (1 row) 194 第 26 章 EARTHDISTANCE SELECT earth_distance(ll_to_earth(0,0),ll_to_earth(1,0))::numeric(20,5); earth_distance ---------------111320.03185 (1 row) SELECT earth_distance(ll_to_earth(30,0),ll_to_earth(30,1))::numeric(20,5); earth_distance ---------------96405.66962 (1 row) SELECT earth_distance(ll_to_earth(30,0),ll_to_earth(31,0))::numeric(20,5); earth_distance ---------------111320.03185 (1 row) SELECT earth_distance(ll_to_earth(60,0),ll_to_earth(60,1))::numeric(20,5); earth_distance ---------------55659.48608 (1 row) SELECT earth_distance(ll_to_earth(60,0),ll_to_earth(61,0))::numeric(20,5); earth_distance ---------------111320.03185 (1 row) SELECT earth_distance(ll_to_earth(41.8,87.6),ll_to_earth(35.1,106.7))::numeric(20,5); earth_distance ---------------1819303.21265 (1 row) SELECT (earth_distance(ll_to_earth(41.8,87.6),ll_to_earth(35.1,106.7))* 100./2.54/12./5280.)::numeric(20,5); numeric -----------1130.46261 (1 row) 195 第 26 章 EARTHDISTANCE 26.4.9 earth_box 得到环绕表面一点得到的物体。 语法 earth_box(earth, float8) returns float8; 示例 SELECT cube_ll_coord(earth_box(ll_to_earth(0,0),112000),1)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),112000),2)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),112000),3)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),112000),1)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),112000),2)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),112000),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord | cube_ur_coord | cube_ur_coord | cube_ur_coord ---------------+---------------+---------------+---------------+---------------+--------------6266169.43896 | -111998.56104 | -111998.56104 | 6490166.56104 | 111998.56104 | 111998.56104 (1 row) SELECT cube_ll_coord(earth_box(ll_to_earth(0,0),pi()*earth()),1)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),pi()*earth()),2)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),pi()*earth()),3)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),pi()*earth()),1)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),pi()*earth()),2)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),pi()*earth()),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord | cube_ur_coord | cube_ur_coord | cube_ur_coord ----------------+-----------------+-----------------+----------------+----------------+----------------6378168.00000 | -12756336.00000 | -12756336.00000 | 19134504.00000 | 12756336.00000 | 12756336.00000 (1 row) SELECT cube_ll_coord(earth_box(ll_to_earth(0,0),10*earth()),1)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),10*earth()),2)::numeric(20,5), cube_ll_coord(earth_box(ll_to_earth(0,0),10*earth()),3)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),10*earth()),1)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),10*earth()),2)::numeric(20,5), cube_ur_coord(earth_box(ll_to_earth(0,0),10*earth()),3)::numeric(20,5); cube_ll_coord | cube_ll_coord | cube_ll_coord | cube_ur_coord | cube_ur_coord | cube_ur_coord ----------------+-----------------+-----------------+----------------+----------------+----------------6378168.00000 | -12756336.00000 | -12756336.00000 | 19134504.00000 | 12756336.00000 | 12756336.00000 (1 row) 196 第 26 章 EARTHDISTANCE 26.4.10 geo_distance 计算两点的地理距离 语法 geo_distance(point, point) returns float8; 示例 SELECT geo_distance('(0,0)'::point,'(0,0)'::point)::numeric(20,5); geo_distance -------------0.00000 (1 row) SELECT geo_distance('(0,0)'::point,'(180,0)'::point)::numeric(20,5); geo_distance -------------12436.77274 (1 row) SELECT geo_distance('(0,0)'::point,'(0,90)'::point)::numeric(20,5); geo_distance -------------6218.38637 (1 row) SELECT geo_distance('(0,0)'::point,'(90,0)'::point)::numeric(20,5); geo_distance -------------6218.38637 (1 row) SELECT geo_distance('(0,0)'::point,'(1,0)'::point)::numeric(20,5); geo_distance -------------69.09318 (1 row) SELECT geo_distance('(0,0)'::point,'(0,1)'::point)::numeric(20,5); geo_distance -------------69.09318 (1 row) 197 第 26 章 EARTHDISTANCE SELECT geo_distance('(0,30)'::point,'(1,30)'::point)::numeric(20,5); geo_distance -------------59.83626 (1 row) 26.5 插件 earthdistance 卸载方法 不需要 earthdistance 插件只需要卸载插件即可。 示例： drop extension earthdistance; 26.6 插件 earthdistance 升级方法:= earthdistance 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 198 第 27 章 FILE_FDW 27章 file_fdw 第 插件 file_fdw 简介 27.1 file_fdw 模块提供外部数据包装器 file_fdw，它能被用来访问服务器的文件系统中的数据文件，或者在服务器上 执行程序并读取它们的输出。数据文件或程序输出必须是能够被 COPY FROM 读取的格式，详见 COPY。当前只能 读取数据文件。 插件 file_fdw 加载方式 27.2 在 ksql 中运行： create extension file_fdw; 插件 file_fdw 的参数配置 27.3 用这个包装器创建的一个外部表可以有下列选项： • filename 指定要被读取的文件。必须是一个绝对路径名。必须指定 filename 或 program，但不能同时指定两 个。 • program 指定要执行的命令。该命令的标准输出将被读取，就像使用 COPY FROM PROGRAM 一样。必须 指定 program 或 filename，但不能同时指定两个。 • format 指定数据的格式，和 COPY 的 FORMAT 选项相同。 • header 199 第 27 章 FILE_FDW 指定数据是否具有一个头部行，和 COPY 的 HEADER 选项相同。 • delimiter 指定数据的定界符字符，和 COPY 的 DELIMITER 选项相同。 • quote 指定数据的引用字符，和 COPY 的 QUOTE 选项相同。 • escape 指定数据的转义字符，和 COPY 的 ESCAPE 选项相同。 • null 指定数据的空字符串，和 COPY 的 NULL 选项相同。 • encoding 指定数据的编码，和 COPY 的 ENCODING 选项相同。 注意虽然 COPY 允许诸如 HEADER 的选项不用一个相应的值指定，但是外部表选项语法要求在所有情况下都 出现一个值。要激活通常写入没有值的 COPY 选项，你可以传递值 TRUE，因为所有这些选项都是布尔值。 使用这个包装器创建的表的一列可以具有下列选项： • force_not_null 这是一个布尔选项。如果为真，它指定该列的值不应该与空字符串匹配（也就是表级别的 null 选 项）。这和把该列放在 COPY 的 FORCE_NOT_NULL 选项中具有相同的效果。 • force_null 这是一个布尔选项。如果为真，它指定匹配空值字符串的列值会被返回为 NULL，即使该值被引号引 用。如果没有这个选项，只有匹配空值字符串的未被引用的值会被返回为 NULL。这和在 COPY 的 FORCE_NULL 选项中列出该列有同样的效果。 COPY 的 FORCE_QUOTE 选项当前不被 file_fdw 支持。 这些选项只能为一个外部表及其列指定，而不能在 file_fdw 外部数据包装器的选项中指定，也不能在使用该包装 器的服务器或者用户映射的选项中指定。 出于安全原因，改变表级别的选项要求超级用户特权或具有默认角色 sys_read_server_files（使用文件名）或默 认角色 sys_execute_server_program （使用程序）的权限只有特定用户能够控制读取哪个文件或者运行哪个程序。 原则上普通用户可以被允许改变其它选项，但是当前还不支持这样做。 当指定 program 选项时，请记住，选项字符串是通过 shell 执行的。如果想传递任何参数到来自不受信任的源的 命令，必须小心去掉或转义任何对 shell 来说可能有特殊含义的字符。安全起见，最好使用固定的命令字符串，或者 至少避免传递任何用户输入。 对于一个使用 file_fdw 的外部表，EXPLAIN 显示要读取的文件名或要运行的程序。对于文件来说，除非指定 COSTS OFF，否则文件尺寸（以字节计）也会被显示。 200 第 27 章 FILE_FDW 27.4 插件 file_fdw 的使用方法 一种 file_fdw 的用法是把可用的 PostgreSQL 活动日志变成一个表用于查询。要这样做，首先你必须正在将日志 记录到一个 CSV 文件，这里我们称其为 pglog.csv。首先，将 file_fdw 安装为一个扩展： CREATE EXTENSION file_fdw; 然后创建一个外部服务器 CREATE SERVER pglog FOREIGN DATA WRAPPER file_fdw; 现在你已经准备好创建外部数据表。使用 CREATE FOREIGN TABLE 命令，你将需要为该表定义列、CSV 文 件名以及格式。 CREATE FOREIGN TABLE pglog ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text ) SERVER pglog OPTIONS ( filename '/home/josh/data/log/pglog.csv', format 'csv' ); 就是这样了—现在你能够直接查询你的日志了。当然，在生产中你会需要定义一些方法来处理日志轮转。 201 第 27 章 FILE_FDW 27.5 插件 file_fdw 卸载方式 在 ksql 中运行 drop extension file_fdw; 27.6 插件 file_fdw 升级方式 file_fdw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 202 第 28 章 FIX_SECURITY_HOLE 28章 fix_security_hole 第 28.1 插件 fix_security_hole 简介 fix_security_hole 是 KingbaseES 的一个扩展插件，主要用于禁止数据库通过 copy 执行操作系统 shell 命令。 • 插件名为 fix_security_hole • 插件版本 V1.0 28.2 插件 fix_security_hole 加载方式 在使用 fix_security_hole 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重 启 KingbaseES 数据库。 示例： shared_preload_libraries = 'fix_security_hole' 28.3 插件 fix_security_hole 的参数配置 close_copy_crogram 启动禁止 copy 执行操作系统 shell 命令，取值范围为 on 或者 off，缺省为 on。 show close_copy_crogram; close_copy_crogram -------------------on (1 row) \c - system alter system set close_copy_crogram = off; 203 第 28 章 FIX_SECURITY_HOLE select sys_reload_conf(); show close_copy_crogram; close_copy_crogram -------------------off (1 row) 28.4 插件 fix_security_hole 使用方法 KingbaseES 加载 fix_security_hole 插件后，超级用户将无法通过 copy 执行操作系统的 shell 命令。 示例： --功能为关闭状态时 create table t1 (a text); copy t1 from program 'ifconfig'; COPY 51 .. code:: --功能为开启状态时 create table t1 (a text); copy t1 from program 'ifconfig'; 错误: not support Copy_To/From_Porgram feature 28.5 插件 fix_security_hole 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 28.6 插件 fix_security_hole 升级方法 fix_security_hole 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 204 第 29 章 第 29.1 FTUTILX 29章 ftutilx 插件 ftutilx 简介 ftutilx 是一个 KingbaseES 的扩展，主要用于从存储流版式文件的 blob 类型字段中抽取文本内容。其中 blob 类 型字段内容可以包括 pdf、doc、docx、wps、xls、xlsx、ppt 和 pptx 格式文件。ftutilx 插件不支持加密文件格式。 29.2 插件 ftutilx 加载方式 在使用 ftutilx 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数 据库。 shared_preload_libraries = 'ftutilx' # (change requires restart) 使用 KSQL 创建插件： CREATE EXTENSION ftutilx; 29.3 插件 ftutilx 的参数配置 ftutilx.max_string_length 抽取结果最大长度，默认值 128M，该参数设置后立即生效。 ftutilx.jvm_option_string JVM 初 始 化 参 数， 默 认 值”-Xmx1024m,-Xms1024m,-Xmn256m,- XX:MetaspaceSize=64m,-XX:MaxMetaspaceSize=128m,-XX:CompressedClassSpaceSize=256m”， 该 参 数 只在会话进程中首次调用 extracttext 函数创建 JVM 时生效，再次设置该参数不再有效。 在数据库默认扩展加载机制下，在一个会话中创建扩展以后，在新的会话开始后并不是立即加载扩展动态库，而 是直到首次调用扩展中的接口时才会加载扩展动态库，导致在这之前在新会话中设置扩展参数无效。解决方法是修改 数据库配置文件中的 shared_preload_libraries 或者 session_preload_libraries 两个参数之一，使参数值包括 ftutilx， 即可在新会话开始后立即加载 ftutilx 扩展动态库，并设置扩展参数。 205 第 29 章 29.4 FTUTILX 插件 ftutilx 的使用方法 ftutilx 插件提供了 extracttext 函数用于抽取存储在 blob 类型字段内的文件内容。extracttext 函数接受一个代表 文件内容的 blob 类型参数，返回抽取的 text 类型文本内容。 CREATE TABLE tab (title text, body blob); INSERT INTO tab VALUES ('test.doc', blob_import('/home/test/data.doc')); SELECT title, length(extracttext(body)) FROM tab; 29.4.1 使用 ftutilx 全文检索的联合使用方案 由于电子文档内容抽取速度较慢，为提高全文检索性能，可以在表中添加存储列，用于存储内容抽取结果或者词 位列表。 方案一 CREATE EXTENSION zhparser; CREATE TEXT SEARCH CONFIGURATION zhparsercfg (PARSER = zhparser); ALTER TEXT SEARCH CONFIGURATION zhparsercfg ADD MAPPING FOR n,v,a,i,e,l WITH simple; CREATE EXTENSION ftutilx; CREATE TABLE tab (title text, body blob); ALTER TABLE tab ADD COLUMN content text GENERATED ALWAYS AS (extracttext(body)) STORED; CREATE INDEX tab_idx ON tab USING GIN (to_tsvector('zhparsercfg', content)); INSERT INTO tab VALUES ('test.doc', blob_import('/home/test/data.doc')); SELECT title FROM tab WHERE to_tsvector('zhparsercfg', content) @@ to_tsquery('日志'); 方案二 CREATE EXTENSION zhparser; CREATE TEXT SEARCH CONFIGURATION zhparsercfg (PARSER = zhparser); ALTER TEXT SEARCH CONFIGURATION zhparsercfg ADD MAPPING FOR n,v,a,i,e,l WITH simple; 206 第 29 章 FTUTILX CREATE EXTENSION ftutilx; CREATE TABLE tab (title text, body blob); ALTER TABLE tab ADD COLUMN tab_idx_col tsvector GENERATED ALWAYS AS (to_tsvector('zhparsercfg', extracttext(body))) STORED; CREATE INDEX tab_idx ON tab USING GIN (tab_idx_col); INSERT INTO tab VALUES ('test.doc', blob_import('/home/test/data.doc')); SELECT title FROM tab WHERE tab_idx_col @@ to_tsquery('日志'); 29.4.2 注意事项 1）ftutilx 需要依赖于 jre-1.8.0 运行时环境，部署后需要设置 LD_LIBRARY_PATH 系统环境变量包含 jre-1.8.0 的 libjvm.so 路径。 2）ftutilx.max_string_length 参数用于配置抽取结果的最大长度，但由于 tsvector 目前最大支持 (1M-1)，所以 extracttext 结合 to_tsvector 使用时，分词结果大小不能超过 (1M-1)。 3）ftutilx 需要创建 JVM，JVM 会占用较多内存。虽然调整 ftutilx.jvm_option_string 的-Xmx 可以限制 JVM 的内存占用，但过小的-Xmx 值会导致大文件解析时 JVM 发生内存不足异常。 4）基于前面的全文检索联合使用方案，在系统内存较少的环境中，需要限制并行插入数据的会话进程数量，以 免系统内存被耗尽。 5）用户需要从 apache 网站自行下载 tika-app-1.26.jar 或者更高版本的包，改名为 ftutilx.jar 后放入 ftutilx.so 所 在目录，方可使用 ftutilx 扩展。 29.5 插件 ftutilx 卸载方法 DROP EXTENSION ftutilx; 29.6 插件 ftutilx 升级方法 ALTER EXTENSION UPDATE ftutilx TO '2.0'; 207 第 30 章 FUZZYSTRMATCH 30章 fuzzystrmatch 第 30.1 插件 fuzzystrmatch 简介 fuzzystrmatch 提供了两个字符串之间的编辑距离的相关函数，即由一个转换成另一个所需的最少编辑操作次 数。 • 插件名为 fuzzystrmatch • 插件版本 V1.0 30.2 插件 fuzzystrmatch 加载方式 使用时需要 create extension fuzzystrmatch。 示例： create extension fuzzystrmatch; 30.3 插件 fuzzystrmatch 参数配置 无需配置任何参数 30.4 插件 fuzzystrmatch 使用方法 30.4.1 levenshtein 计算两个字符串之间编辑距离。 208 第 30 章 FUZZYSTRMATCH 语法 levenshtein(t1 text, t2 text ) RETURNS int; 参数 t1 源字符串。 t2 目标字符串。 示例 TEST=# select levenshtein('text','tst'); levenshtein ------------2 (1 行记录) TEST=# select levenshtein('text','test'); levenshtein ------------1 (1 行记录) TEST=# select levenshtein('text','text'); levenshtein ------------0 (1 行记录) 30.4.2 levenshtein_with_costs 计算两个字符串之间的编辑距离。 语法 levenshtein_with_costs(t1 text, t2 text, i1 int, i2 int, i3 int) RETURNS int; 参数 t1 源字符串。 t2 目标字符串。 i1 insert 的代价权重。 i2 replace 的代价权重。 i3 delete 的代价权重。 示例 209 第 30 章 FUZZYSTRMATCH TEST=# select levenshtein('tet','text', 1 ,2 ,3); levenshtein ------------1 (1 行记录) TEST=# select levenshtein('tet','text', 2 ,2 ,3); levenshtein ------------2 (1 行记录) TEST=# select levenshtein('tet','text', 2 ,2 ,3); levenshtein ------------2 (1 行记录) 30.4.3 levenshtein_less_equal 求字符之间编码距离与大于指定的值的最小整数值之间的最小值。 语法 levenshtein_less_equal(t1 text, t2 text, i int) RETURNS int; 参数 t1 源字符串。 t2 目标字符串。 i 参与比较的值。 示例 SELECT levenshtein_less_equal('extensive', 'exhaustive', 2); levenshtein_less_equal -----------------------3 (1 row) SELECT levenshtein_less_equal('extensive', 'exhaustive', 4); levenshtein_less_equal -----------------------4 (1 row) 210 第 30 章 FUZZYSTRMATCH 30.4.4 levenshtein_less_equal_with_costs 与上述函数相似，增加如 levenshtein_with_costs 一样的代价花销。 30.4.5 metaphone 计算字符串的 metaphone 键。 语法 metaphone(text, int) returns text。 语法 text 参与计算的字符串。 int 参与运算的参考键值。 示例 SELECT metaphone('GUMBO', 4); metaphone ----------KM (1 row) 30.4.6 soundex, text_soundex 生成字符串的 soundex 键。 语法 soundex(text) rerturns text。 参数 text 参与计算的字符串。 示例 TEST=# select soundex('A500'); soundex --------A000 (1 行记录) TEST=# select soundex('A529sd800'); soundex --------- 211 第 30 章 FUZZYSTRMATCH A230 (1 行记录) TEST=# select soundex('A529sds800'); soundex --------A232 (1 行记录) TEST=# select soundex('hello world'); soundex --------H464 (1 行记录) 30.4.7 difference 获得两个对比的字符串转换为 soundex 值后匹配的位数。 语法 difference(t1 text, t2 text) RETURNS int; 参数 t1 参与计算的字符串 1。 t2 参与计算的字符串 2。 示例 TEST=# select difference('ab', 'as'); difference -----------3 (1 行记录) TEST=# select difference('ab', 'ab'); difference -----------4 (1 行记录) 212 第 30 章 FUZZYSTRMATCH 30.4.8 dmetaphone 获取 text 的 dmetaphone。 语法 dmetaphone(text) returns text。 参数 text 参与计算的 text 字符串。 示例 TEST=# select dmetaphone('tetx'); dmetaphone -----------TTKS (1 行记录) 30.5 插件 fuzzystrmatch 卸载方法 不需要 fuzzystrmatch 插件只需要卸载插件即可。 示例 drop extension fuzzystrmatch; 30.6 插件 fuzzystrmatch 升级方法 fuzzystrmatch 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 213 第 31 章 HSTORE 31章 hstore 第 31.1 插件 hstore 简介 hstore 支持 hstore 类型及其相关的函数。 • 插件名为 hstore • 插件版本 V1.0 31.2 插件 hstore 加载方式 使用时需要 create extension hstore。 示例： create extension hstore; 注意: 创建扩展前，需要关闭禁用多态函数参数，执行’set ora_forbid_func_polymorphism to off;’ 。 31.3 插件 hstore 参数配置 无需配置任何参数。 214 第 31 章 HSTORE 31.4 插件 hstore 使用方法 31.4.1 hstore 类型 字符串的一种，可以将字符串与’=>’ 进行单元分割重组形成新的字符串。 示例 select ''::hstore; hstore -------(1 row) select 'a=>b'::hstore; hstore ---------"a"=>"b" (1 row) select ' a=>b'::hstore; hstore ---------"a"=>"b" (1 row) select 'a =>b'::hstore; hstore ---------"a"=>"b" (1 row) select 'a=>b '::hstore; hstore ---------"a"=>"b" (1 row) select 'a=> b'::hstore; hstore ---------"a"=>"b" (1 row) select '"a"=>"b"'::hstore; 215 第 31 章 HSTORE hstore ---------"a"=>"b" (1 row) select ' "a"=>"b"'::hstore; hstore ---------"a"=>"b" (1 row) select '"a" =>"b"'::hstore; hstore ---------"a"=>"b" (1 row) select '"a"=>"b" '::hstore; hstore ---------"a"=>"b" (1 row) select '"a"=> "b"'::hstore; hstore ---------"a"=>"b" (1 row) select 'aa=>bb'::hstore; hstore -----------"aa"=>"bb" (1 row) select ' aa=>bb'::hstore; hstore -----------"aa"=>"bb" (1 row) select 'aa =>bb'::hstore; hstore -----------"aa"=>"bb" 216 第 31 章 HSTORE (1 row) select 'aa=>bb '::hstore; hstore -----------"aa"=>"bb" (1 row) select 'aa=> bb'::hstore; hstore -----------"aa"=>"bb" (1 row) select '"aa"=>"bb"'::hstore; hstore -----------"aa"=>"bb" (1 row) select ' "aa"=>"bb"'::hstore; hstore -----------"aa"=>"bb" (1 row) select '"aa" =>"bb"'::hstore; hstore -----------"aa"=>"bb" (1 row) select '"aa"=>"bb" '::hstore; hstore -----------"aa"=>"bb" (1 row) select '"aa"=> "bb"'::hstore; hstore -----------"aa"=>"bb" (1 row) select 'aa=>bb, cc=>dd'::hstore; 217 第 31 章 HSTORE hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>bb , cc=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>bb ,cc=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>bb, "cc"=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>bb , "cc"=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>bb ,"cc"=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>"bb", cc=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>"bb" , cc=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" 218 第 31 章 HSTORE (1 row) select 'aa=>"bb" ,cc=>dd'::hstore; hstore -----------------------"aa"=>"bb", "cc"=>"dd" (1 row) select 'aa=>null'::hstore; hstore -----------"aa"=>NULL (1 row) select 'aa=>NuLl'::hstore; hstore -----------"aa"=>NULL (1 row) select 'aa=>"NuLl"'::hstore; hstore -------------"aa"=>"NuLl" (1 row) select e'\\=a=>q=w'::hstore; hstore ------------"=a"=>"q=w" (1 row) select e'"=a"=>q\\=w'::hstore; hstore ------------"=a"=>"q=w" (1 row) select e'"\\"a"=>q>w'::hstore; hstore -------------"\"a"=>"q>w" (1 row) 219 第 31 章 HSTORE 31.4.2 hstore_to_jsonb 将 hstore 类型转换为 jsonb 类型。 语法 hstore_to_jsonb(hstore) returns jsonb。 示例 select hstore_to_jsonb('"a key" =>1, b => t, c => null, d=> 12345, e => 012345, f=> 1.234, g=> 2.345e+4'); hstore_to_jsonb ------------------------------------------------------------------------------------------------{"b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4", "a key": "1"} (1 row) 31.4.3 hstore_to_json 将 hstore 转换为 json 类型。 语法 hstore_to_json(hstore) returns json。 示例 select hstore_to_json('"a key" =>1, b => t, c => null, d=> 12345, e => 012345, f=> 1.234, g=> 2.345e+4'); hstore_to_json ------------------------------------------------------------------------------------------------{"b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4", "a key": "1"} (1 row) 31.5 插件 hstore 卸载方法 不需要 hstore 插件只需要卸载插件即可。 示例： drop extension hstore; 220 第 31 章 HSTORE 31.6 插件 hstore 升级方法 hstore 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 221 第 32 章 HTTP 32章 http 第 32.1 插件 http 简介 插件 http 是 KingbaseES 的一个扩展插件。插件功能是提供数据库的 http 功能，允许在数据库内检索网页。 • 插件名为 http • 插件版本 V1.4 注意: http 插件不支持在 Windows 平台使用。 32.2 插件 http 加载方式 CREATE EXTENSION http; 32.3 插件 http 的参数配置 http 插件可以设置 http.keepalive 参数和 http.timeout_msec 参数。 32.3.1 http.keepalive 变量 功能描述 默认情况下，每个请求都使用一个全新的连接，并确保在完成请求后关闭该连接。当扩展程序在较长的时间段内 运行时，设置 http.keepalive 为’on’ 的操作减少了消耗系统资源（套接字）的机会。 高性能应用程序可能希望启用保持活动状态和连接持久性，以减少延迟并提高吞吐量。该 GUC 变量更改了 http 扩展名的行为，以尽可能长时间地保持连接。 222 第 32 章 HTTP 示例 set http.keepalive = 'on'; 32.3.2 http.timeout_msec 变量 功能描述 默认情况下，http.timeout_msec 为 0。如果需要不同的超时时间，则可以使用该 GUC 变量以毫秒为单位进行 设置。 示例 set http.timeout_msec = 200; 32.4 插件 http 使用方法 32.4.1 数据类型 32.4.1.1 UTL_HTTP.req 功能描述 使用此类型表示 HTTP 请求。 语法格式 CREATE TYPE UTL_HTTP.req AS( url VARCHAR2(32767), method VARCHAR2(64), http_version VARCHAR2(64)); 类型说明 参数 描述 url http 请求的 URL method 对 URL 所标识的资源执行的方法，目前仅支持 GET http_version 兼容性参数，无意义 223 第 32 章 HTTP 32.4.1.2 UTL_HTTP.resp 功能描述 使用此类型表示 HTTP 响应。 语法格式 CREATE TYPE UTL_HTTP.resp AS( status_code INTEGER , reason_phrase VARCHAR2(256), http_version VARCHAR2(64), content TEXT); 类型说明 参数 描述 status_code web 服务器返回的状态代码 reason_phrase 兼容性参数，无意义 http_version 兼容性参数，无意义 content web 服务器返回的内容 32.4.1.3 http_method 功能描述 在 text 类型上增加检查 http 方法名的约束。 语法格式 CREATE DOMAIN http_method AS text CHECK ( VALUE ILIKE 'get' OR VALUE ILIKE 'post' OR VALUE ILIKE 'put' OR VALUE ILIKE 'delete' OR VALUE ILIKE 'patch' OR VALUE ILIKE 'head' ); 224 第 32 章 HTTP 32.4.1.4 http_header 功能描述 表示一个 http 的头信息。 语法格式 CREATE TYPE http_header AS ( field VARCHAR, value VARCHAR ); 类型说明 参数 描述 field http 请求头的名字 value http 请求头的值 32.4.1.5 http_response 功能描述 表示 http 返回的响应。 语法格式 CREATE TYPE http_response AS ( status INTEGER, content_type VARCHAR, headers http_header[], content VARCHAR ); 类型说明 参数 描述 status web 服务器返回的状态代码 content_type web 服务器返回内容的类型 headers web 服务器返回的 http 头信息 content web 服务器返回的内容 225 第 32 章 HTTP 32.4.1.6 http_request 功能描述 表示 http 请求。 语法格式 CREATE TYPE http_request AS ( method http_method, uri VARCHAR, headers http_header[], content_type VARCHAR, content VARCHAR ); 类型说明 参数 描述 method 对 URL 所标识的资源执行的方法 uri http 请求的 URL headers 请求头信息 content_type 请求类型 content 请求内容 32.4.2 UTL_HTTP.BEGIN_REQUEST 功能描述 这个函数开始一个新的 HTTP 请求。 语法格式 UTL_HTTP.BEGIN_REQUEST ( url IN VARCHAR2, method IN VARCHAR2 DEFAULT 'GET', http_version IN VARCHAR2 DEFAULT NULL, request_context IN VARCHAR2 DEFAULT NULL, https_host IN VARCHAR2 DEFAULT NULL) RETURN UTL_HTTP.req 参数说明 226 第 32 章 参数 描述 url http 请求的 URL method 对 URL 所标识的资源执行的方法，目前仅支持 GET http_version 兼容性参数，无意义 request_context 兼容性参数，无意义 https_host 兼容性参数，无意义 HTTP 返回值说明 返回 HTTP 请求。 32.4.3 UTL_HTTP.SET_HEADER 功能描述 设置一个 HTTP 请求头。 语法格式 UTL_HTTP.SET_HEADER ( r IN OUT UTL_HTTP.req, name IN VARCHAR2, value IN VARCHAR2 参数说明 参数 描述 r http 的请求 name http 请求头的名字 value http 请求头的值 32.4.4 UTL_HTTP.GET_RESPONSE 功能描述 此函数用于读取 http 响应，目前仅支持 get 功能。 语法格式 227 第 32 章 HTTP UTL_HTTP.GET_RESPONSE ( r IN UTL_HTTP.req, return_info_response IN BOOLEAN DEFAULT FALSE) RETURN UTL_HTTP.resp 参数说明 参数 描述 r http 的请求 return_info_response 兼容性参数，无意义 返回值说明 返回 HTTP 响应。 32.4.5 UTL_HTTP.READ_LINE 功能描述 这个过程以文本形式读取 HTTP 响应体，直到到达行尾，并在调用者提供的缓冲区返回输出。如果到达 HTTP 响应正文的末尾，将引发 NO_DATA_FOUND 异常。 语法格式 UTL_HTTP.READ_LINE( r IN OUT UTL_HTTP.resp, data OUT VARCHAR2, remove_crlf IN BOOLEAN DEFAULT FALSE) 参数说明 参数 描述 r http 的响应 data http 的响应正文 remove_crlf 兼容性参数，无意义 32.4.6 UTL_HTTP.READ_TEXT 功能描述 228 第 32 章 HTTP 这个过程以文本形式读取 HTTP 响应体，并在调用者提供的缓冲区返回输出。如果到达 HTTP 响应正文的末 尾，将引发 NO_DATA_FOUND 异常。 语法格式 UTL_HTTP.READ_TEXT( r IN OUT UTL_HTTP.resp, data OUT VARCHAR2, len IN INTEGER DEFAULT NULL) 参数说明 参数 描述 r http 的响应 data http 的响应正文 len 要读取数据的最大字符数 注意: 如果 len 为 NULL, 这个过程将读取尽可能多的输入来填充数据中分配的字符串。 32.4.7 UTL_HTTP.END_RESPONSE 功能描述 此过程结束 http 响应。 语法格式 UTL_HTTP.END_RESPONSE ( r IN OUT UTL_HTTP.resp) 参数说明 参数 描述 r http 的响应 32.4.8 UTL_HTTP.END_REQUEST 功能描述 此过程结束 http 请求。 229 第 32 章 HTTP 语法格式 UTL_HTTP.END_REQUEST ( r IN OUT UTL_HTTP.req) 参数说明 参数 描述 r http 的请求 32.4.9 http_header 函数 功能描述 组成一个简单数组返回。 语法格式 http_header(field VARCHAR, value VARCHAR) returns http_header 参数说明 参数名称 描述 field 指定名字 value 指定值 返回值说明 返回一个请求头。 示例 SELECT content::json->'headers'->>'Authorization' FROM http(( 'GET', 'http://httpbin.org/headers', ARRAY[http_header('Authorization','Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9')], NULL, NULL )::http_request) content ---------------------------------------------Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9 (1 row) 230 第 32 章 HTTP 32.4.10 http 函数 功能描述 可以进行 get、post、put、delete、patch 功能。 语法格式 http(request http_request) returns http_response 参数说明 参数名称 描述 request 输入的请求 返回值说明 从网页获取的响应。 示例 SELECT status, content::json->'args' as args, content::json->>'data' as data, content::json->'url' as url, content::json->'method' as method from http(('GET', 'https://httpbin.org/anything', NULL, 'application/json', '{"search": "toto"}')); 32.4.11 http_get 函数 功能描述 请求指定的页面信息，并返回响应主体。 语法格式 http_get(uri VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 返回值说明 231 第 32 章 HTTP 从网页获取的响应。 示例 SELECT content FROM http_get('http://httpbin.org/ip'); content ----------------------------+ {"origin":"24.69.186.43"} (1 row) 32.4.12 http_post 函数 功能描述 该请求会向指定的资源提交数据，请求服务器处理，如表单数据提交、文件上传等。 语法格式 http_post(uri VARCHAR, content VARCHAR, content_type VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 content 请求内容 content_type 请求类型 返回值说明 从网页获取的响应。 示例 SELECT status, content::json->'data' AS data, content::json->'args' AS args, content::json->'url' AS url, content::json->'method' AS method FROM http_post('https://httpbin.org/anything?foo=bar','payload','text/plain'); status | data | args | url | method --------+-----------+------------------+----------------------------------------+-------200 | "payload" | { | | +| "https://httpbin.org/anything?foo=bar" | "POST" "foo": "bar"+| | 232 第 32 章 | | } | HTTP | (1 row) 32.4.13 http_put 函数 功能描述 put 请求会向指定资源位置上传其最新的内容，不能创建新的资源。 语法格式 http_put(uri VARCHAR, content VARCHAR, content_type VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 content 请求内容 content_type 请求类型 返回值说明 从网页获取的响应。 示例 SELECT status, content_type, content::json->>'data' AS data FROM http_put('http://httpbin.org/put', 'some text', 'text/plain'); status | content_type | data --------+------------------+----------200 | application/json | some text 32.4.14 http_patch 函数 功能描述 patch 请求与 put 请求类似都是用于资源的更新。但二者有以下不同 patch 请求一般用于资源的部分更新，而 put 一般用于资源的整体更新。 语法格式 233 第 32 章 HTTP http_patch(uri VARCHAR, content VARCHAR, content_type VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 content 请求内容 content_type 请求类型 返回值说明 从网页获取的响应。 示例 SELECT status, content::json->'data' AS data, content::json->'args' AS args, content::json->'url' AS url, content::json->'method' AS method FROM http_patch('https://httpbin.org/anything?foo=bar','{"this":"that"}','application/json'); status | data | args | url | method --------+-----------------------+------------------+----------------------------------------+--------200 | "{\"this\":\"that\"}" | { | | | | +| "https://httpbin.org/anything?foo=bar" | "PATCH" "foo": "bar"+| | | | } (1 row) 32.4.15 http_delete 函数 功能描述 删除资源。 语法格式 http_delete(uri VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 234 第 32 章 HTTP 返回值说明 从网页获取的响应。 示例 SELECT status, content::json->'args' AS args, content::json->'url' AS url, content::json->'method' AS method FROM http_delete('https://httpbin.org/anything?foo=bar'); status | args | url | method --------+------------------+----------------------------------------+---------200 | { +| "https://httpbin.org/anything?foo=bar" | "DELETE" | | "foo": "bar"+| | | | } (1 row) 32.4.16 http_head 函数 功能描述 请求网页响应的头部信息。 语法格式 http_head(uri VARCHAR) returns http_response 参数说明 参数名称 描述 uri 标识互联网资源名称的字符串 返回值说明 从网页获取的响应。 示例 SELECT http.status, headers.value AS location FROM http_head('http://google.com') AS http LEFT OUTER JOIN LATERAL (SELECT value FROM unnest(http.headers) 235 第 32 章 HTTP WHERE field = 'Location') AS headers ON true; status | location --------+----------------------------------------------------------302 | http://www.google.ch/?gfe_rd=cr&ei=ACESWLy_KuvI8zeghL64Ag 32.4.17 http_set_curlopt 函数 功能描述 设置 curl 选项。 语法格式 http_set_curlopt(curlopt VARCHAR, value varchar) returns boolean 参数说明 参数名称 描述 curlopt 设置项 value 设置值 返回值说明 返回设置状态，为真则设置成功，为假则设置失败。 示例 -- Alter options and and reset them and throw errors SELECT http_set_curlopt('CURLOPT_PROXY', '127.0.0.1'); http_set_curlopt -----------------t (1 row) -- Error because proxy is not there SELECT status FROM http_get('https://httpbin.org/status/555'); ERROR: Failed to connect to 127.0.0.1 port 1080: Connection refused -- Still an error SELECT status FROM http_get('https://httpbin.org/status/555'); ERROR: Failed to connect to 127.0.0.1 port 1080: Connection refused 236 第 32 章 HTTP 32.4.18 http_reset_curlopt 函数 功能描述 重置 curl 选项。 语法格式 http_reset_curlopt() returns boolean 返回值说明 返回状态，为真则设置成功，为假则设置失败。 示例 SELECT http_reset_curlopt(); http_reset_curlopt -------------------t (1 row) -- Now it should work SELECT status FROM http_get('https://httpbin.org/status/555'); status -------555 (1 row) 32.4.19 http_list_curlopt 函数 功能描述 打印已经设置的 curl 选项。 语法格式 http_list_curlopt() returns setof(curlopt text, value text) 返回值说明 返回已经设置的 curl 选项。 示例 SELECT http_set_curlopt('CURLOPT_PROXY', '127.0.0.1'); http_set_curlopt ------------------ 237 第 32 章 HTTP t (1 row) select http_list_curlopt(); http_list_curlopt --------------------------(CURLOPT_PROXY,127.0.0.1) 32.4.20 urlencode 函数 功能描述 对包含任何“特殊”字符（实际上是 a-z 和 0-9 以外的任何其他字符）的内容进行 URL 编码。 语法格式 urlencode(string VARCHAR) returns text 参数说明 参数名称 描述 string 需要编码的字符串 返回值说明 返回已编码后的字符串。 示例 SELECT urlencode('my special string''s & things?'); urlencode ------------------------------------my+special+string%27s+%26+things%3F (1 row) 32.5 插件 http 卸载方法 drop EXTENSION http; 238 第 32 章 32.6 HTTP 插件 http 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.4 升级到 1.5： ALTER EXTENSION http UPDATE TO '1.5'; 239 第 33 章 IDENTITY_PWDEXP 33章 identity_pwdexp 第 33.1 插件 identity_pwdexp 简介 identity_pwdexp 是 KingbaseES 的一个扩展插件，用于设置口令有效期。 KingbaseES 的用户管理中含有口令有效期这一属性，用户密码过期检查就是通过设置用户密码的有效期，在用 户密码过期后限制用户登录数据库，并输入新密码的功能。 KingbaseES 通过插件的方式来进行用户密码过期检查。这种方式更为灵活，当数据库的实用场景需要进行用户 密码过期检查时，加载插件即可。而不需要该功能时，卸载插件即可。 KingbaseES 中通过 1 个全局级参数配合插件来实现用户密码过期检查。 • 插件名为 identity_pwdexp • 插件版本 V1.0 33.2 插件 identity_pwdexp 加载方法 在使用 identity_pwdexp 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 shared_preload_libraries = 'identity_pwdexp' # (change requires restart) 33.3 插件 identity_pwdexp 的参数配置 identity_pwdexp.password_change_interval 密码有效期，单位是天，取值范围为 [1，INT_MAX]，缺省为 30。 参数只能在 postmaster 启动或由安全管理员通过 SQL 语言 (alter 命令) 进行设置。 语句 Alter system set 参数名 = 参数值； 240 第 33 章 IDENTITY_PWDEXP 修改后再运行 select sys_reload_conf(); 不用重启服务器，对所有数据库及连接立即生效。 指定密码创建用户时，可通过 valid until 选项指定该用户的密码有效期，指定的密码有效期必须晚于当前 时间且早于更换周期。identity_pwdexp.password_change_interval 指定的时间。 对已创建成功且已拥有密码的用户，也可通过 alter 语句的 valid until 选项修改其密码有效期，但仅安全 管理员有这个权限，其它用户无法修改自己及他人的口令更换周期。 若在创建用户或修改用户密码时未显示的通过 valid until 选项指定该用户的密码有效期，那么系统会根据 identity_pwdexp.password_change_interval 参数设定的值自动为其计算密码有效期。 identity_pwdexp.max_password_change_interval 最大密码有效期，单位是天，取值范围为 [1，INT_MAX]，缺省为 30。 参数只能在 postmaster 启动或由安全管理员通过 SQL 语言 (alter 命令) 进行设置。 此参数用于限制密码有效期的设置范围，当设置的密码有效期大于最大密码有效期时，系统会报错提示。 33.3.1 示例 -- 创建扩展 \c test system create extension identity_pwdexp; CREATE EXTENSION -- 设置密码有效期是 5 天 \c test sso show identity_pwdexp.password_change_interval; identity_pwdexp.password_change_interval -----------------------------------------30 (1 row) alter system set identity_pwdexp.password_change_interval = 5; ALTER SYSTEM show identity_pwdexp.password_change_interval; identity_pwdexp.password_change_interval -----------------------------------------30 (1 行记录) select sys_reload_conf(); sys_reload_conf ----------------t (1 行记录) 241 第 33 章 IDENTITY_PWDEXP show identity_pwdexp.password_change_interval; identity_pwdexp.password_change_interval -----------------------------------------5 (1 行记录) \c test system call now(); now ------------------------------2020-04-30 15:34:30.408304+08 (1 行记录) CREATE USER u_pwd_et PASSWORD '1234567890abC/.' VALID UNTIL '2020-05-01'; CREATE ROLE SELECT USENAME, VALUNTIL FROM SYS_USER WHERE USENAME = 'u_pwd_et'; usename | valuntil ----------+-----------------------u_pwd_et | 2020-05-01 00:00:00+08 (1 行记录) ALTER USER u_pwd_et PASSWORD '/.1234567890abC'; 警告: user "u_pwd_et" does not be locked ALTER ROLE SELECT USENAME, VALUNTIL FROM SYS_USER WHERE USENAME = 'u_pwd_et'; usename | valuntil ----------+------------------------------u_pwd_et | 2020-05-05 15:35:23.448381+08 (1 行记录) 33.4 插件 identity_pwdexp 使用方法 具体参考《KingbaseES 数据库安全指南》3.2.2.4 口令有效期设置章节。 33.5 插件 identity_pwdexp 的卸载插件 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 242 第 33 章 IDENTITY_PWDEXP shared_preload_libraries = '' 33.6 插件 identity_pwdexp 升级方法 identity_pwdexp 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 243 第 34 章 INTAGG 34章 intagg 第 34.1 插件 intagg 简介 intagg 模块提供了一个整数聚合器和一个枚举器，作为内置函数的兼容性封装器提供。 • 插件名为 intagg • 插件版本 V1.0 34.2 插件 intagg 加载方式: 使用时需要 create extension intagg。 示例: create extension intagg; 34.3 插件 intagg 参数配置 无需配置任何参数 34.4 插件 intagg 使用方法 34.4.1 函数 聚合器是一个生产正好包含输入的整数的整数数组的聚合函数 int_array_agg(integer)。这是 array_agg 的封装 器，array_agg 对于任意数组类型做相同的事情。 244 第 34 章 INTAGG 枚举器是返回 setof integer 类型的函数 int_array_enum(integer[])。本质上是聚合器的反向操作：给出一个整数 数组，将其展开为一组行。这是 unnest 的封装器，unnest 对于任意数组类型做相同的事情。 示例： 许多数据库系统有一到多个表的概念。这样的一个表通常位于两个索引表之间 例如: CREATE TABLE left_table(id INT PRIMARY KEY, ...); CREATE TABLE right_table(id INT PRIMARY KEY, ...); CREATE TABLE one_to_many(l INT REFERENCES left_table, r INT REFERENCES right_table); 通常这样使用: SELECT right_table.* from right_table JOIN one_to_many ON (right_table.id = one_to_many.r) WHERE one_to_ many.l = item; 这将返回所有在左手边的表里有记录的右手边表里的条目。这在 SQL 中是一个非常普通的构造。现在，这个方 法在一个有非常大数量的记录的 one_to_many 表里是很难处理的。通常，像这样的连接将会导致索引扫描和抓取表 中有左手边记录的每个右手边的记录。 如果你有一个非常动态的系统，那么没有什么你可以做的。不过，如果你有一些静态数据，你可以使用该聚合器 创建一个汇总表。 CREATE TABLE summary AS SELECT l, int_array_aggregate(r) AS right_num FROM one_to_many GROUP BY l; 这将创建一个表，这个表有每个左边的条目和一个左边条目的数组。现在，如果没有使用该数组的方法则是相当 无用的; 这就是为什么有一个数组枚举器。你可以： SELECT l,int_array_enum(r) FROM summary WHERE l = item; 上面的查询使用 int_array_enum 产生下面相同的结果： SELECT l , r FROM one_to_many WHERE l = item; 不同之处是针对 summary 表的查询必须只从表中获取一行，而针对 one_to_many 的直接查询必须索引扫描然 后从每条记录中获取一行。 在一个系统上，一个显示了消耗 8488 的查询的 EXPLAIN 减少到消耗 329. 原始查询时一个包括 one_to_many 表的连接，替换为： 245 第 34 章 INTAGG SELECT r, count(r) FROM ( SELECT l, int_array_enum(r) AS right_num FROM summary JOIN (SELECT l FROM left_table WHERE left_table.id = item) AS lefts ON (summary.l = lefts.l ) AS list GROUP BY r ORDER BY count DESC; 34.5 插件 intagg 卸载方法 不需要 intagg 插件只需要卸载插件即可。 示例： drop extension intagg; 34.6 插件 intagg 升级方法 intagg 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 246 第 35 章 INTARRAY 35章 intarray 第 35.1 插件 intarray 简介 intarray 模块为操作整数的 null-free 数组提供一些有用的函数和操作符。也支持使用其中的一些操作符执行索引 搜索。如果提供的数组包含任何空元素，那么所有这些操作符都将抛出一个错误。这些操作符中的一些只对一维数组 敏感。尽管他们将接受多个维数的输入数组，数组将按照存储的顺序当做一维数组。 • 插件名为 intarray • 插件版本 V1.0 35.2 插件 intarray 加载方式 使用时需要 create extension intarray。 示例: create extension intarray; 35.3 插件 intarray 参数配置 无需配置任何参数。 35.4 插件 intarray 使用方法 35.4.1 icount 计算数组中元素的个数 247 第 35 章 INTARRAY 语法 icount(_int4) RETURNS int; 示例 TEST=# select icount('{1,2,3}'::int[]); icount -------3 (1 行记录) 35.4.2 sort 对 int 数组进行排序。 语法 sort(int[]) returns int[]; sort(int[], text dir) returns int[]; 参数 dir 如果 dir 是 asc，则对数组进行升序排序。如果 dir 是 desc，则对数组进行降序排序。 示例 TEST=# select sort('{2,1,5,7,3}'); sort ------------{1,2,3,5,7} (1 行记录) TEST=# select sort('{2,1,5,7,3}', 'asc'); sort ------------{1,2,3,5,7} (1 行记录) TEST=# select sort('{2,1,5,7,3}', 'desc'); sort ------------{7,5,3,2,1} (1 行记录) 35.4.3 sort_asc 以升序的方式对数组进行排序。 248 第 35 章 INTARRAY 语法 sort_asc(int[]) returns int[]; 示例 TEST=# select sort_asc('{2,1,5,7,3}'); sort_asc ------------{1,2,3,5,7} (1 行记录) 35.4.4 sort_desc 以降序的方式对 int 数组进行排序。 语法 sort_desc(int[]) returns int[]; 示例 TEST=# select sort_desc('{2,1,5,7,3}'); sort_desc ------------{7,5,3,2,1} (1 行记录) 35.4.5 uniq 消除相邻的相同的元素。 语法 uniq(int[]) returns int[]; 示例 TEST=# select uniq('{2,1,5,7,7,7,3}'); uniq ------------{2,1,5,7,3} (1 行记录) 249 第 35 章 INTARRAY 35.4.6 idx 匹配 item 的第一个元素中的索引（如果没有则为 0）。 语法 idx(int[], int item) returns int; 参数 item 需要匹配的值。 示例 TEST=# select idx(array[1,23,5,2,5,2], 2); idx ----4 (1 行记录) 35.4.7 subarray 在 start 位置开始的，len 个元素的数组的一部分。 语法 subarray(int[], int start) returns int[]; subarray(int[], int start, int len) returns int[]; 参数 start 开始的位置。 len 指定子数组的长度。 示例 TEST=# select subarray('{1,2,3,2,1}'::int[], 2, 3); subarray ---------{2,3,2} (1 行记录) 35.4.8 intset 制作单个元素的数组。 语法 intset(int) returns int[]; 250 第 35 章 INTARRAY 示例 TEST=# select intset(42); intset -------{42} (1 行记录) 35.4.9 intarray 模块中支持的操作符 && @>@< # + - | & @@ 35.5 插件 intarray 卸载方法 不需要 intarray 插件只需要卸载插件即可。 示例 drop extension intarray; 35.6 插件 intarray 升级方法 intarray 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 251 第 36 章 ISN 36章 isn 第 36.1 插件 isn 简介 插件 isn 为下列国际产品编号标准提供数据类型 EAN13、UPC、ISBN（图书）、ISMN（音乐）以及 ISSN（期 刊）。 在输入时会按照一个硬编码的前缀列表对输入进行验证，这个前缀的列表也被用来在输出时连接号码。 因为新的前缀总是不时地出现，这个前缀列表可能会过时。 这个模块的一个未来版本有希望得到一个来自于一个或多个表的前缀列表，这样用户可以根据需要来方便 地更新前缀列表。 不过，在当前该列表只能通过修改源代码并且重新编译来更新。 另外一种方案是，这个模块的未来版本中可能会直接移除前缀验证和连接支持。 • 插件名为 isn • 插件版本 V1.2 36.2 插件 isn 加载方式 使用时需要在命令行执行 create extension isn; 36.3 插件 isn 的参数配置 无需配置任何参数 252 第 36 章 36.4 ISN 插件 isn 的使用方法 加载插件 isn 后，按照如下方式使用相应功能。 36.4.1 数据类型 如下表所示： 36.4.2 数据类型 描述 EAN13 欧洲文章号，总是以 EAN13 格式显示 ISBN13 国际标准图书号，以新的 EAN13 格式显示 ISMN13 国际标准音乐号，以新的 EAN13 格式显示 ISSN13 国际标准期刊号，以新的 EAN13 格式显示 ISBN 国际标准图书号，以旧的短格式显示 ISMN 国际标准音乐号，以旧的短格式显示 ISSN 国际标准期刊号，以旧的短格式显示 UPC 通用产品代码 造型 isn 模块提供了下列类型之间的造型： ISBN13 <=> EAN13 ISMN13 <=> EAN13 ISSN13 <=> EAN13 ISBN <=> EAN13 ISMN <=> EAN13 UPC <=> EAN13 ISBN <=> ISBN13 ISMN <=> ISMN13 ISSN <=> ISSN13 当从 EAN13 造型为另一种类型时，会有对该值是否在另一种类型的域中的运行时检查，如果不在则抛出一个错 误。其他的造型则是简单地重新贴个标签，因而总是会成功。 253 第 36 章 36.4.3 ISN 函数和操作符 函数如下表所示： 函数 描述 述 is_weak(boolean) return boolean 设置弱输入模式（返回新设置）。 isn_weak() return boolean 得到弱模式的当前状态。 make_valid(isn) return isn 验证一个非法号码（清除非法标志）。 is_valid(isn) return boolean 检查非法标志的存在。 弱模式被用来允许插入非法数据到一个表中。非法意味着校验位错误，而不是有丢失号码。 为什么你会想要使用弱模式？你可能有一个巨大的 ISBN 号码集合并且出于某种奇怪的原因其中具有错误的校验 位。 当你使用弱模式在一个表中插入非法号码时，被插入的号码将会被加上修正过的校验位，但是它的最后将会有一 个’!’。例如 0-11-000322-5！。这种非法标志符可以用 is_valid 函数检查并且可以用 make_valid 函数清除。 即使不在弱模式中，你也能通过在号码某位追加！字符来强制非法号码的插入。 另一个特殊特性是输入过程中，你可以写一个？代替校验位，然后正确的校验位将被自动插入。 36.4.4 示例 --直接使用类型 select isbn('978-0-393-04002-9'); select isbn13('0901690546'); select issn('1436-4522'); --转换类型 select upc(ean13('022-035648348-1')); select ean13(upc('220356483481')); --创建一个表，它有一个单一列来保存 ISBN 号码 create table test(id isbn); INSERT INTO test VALUES('9780393040029'); --自动计算校验位 INSERT INTO test VALUES('220500896?'); INSERT INTO test VALUES('978055215372?'); select issn('3251231?'); 254 第 36 章 ISN select ismn('979047213542?'); --使用弱模式 SELECT isn_weak(true); INSERT INTO test VALUES('978-0-11-000533-4'); insert into test values('2-205-00876-X'); select isn_weak(false); select id from test where not is_valid(id); update test set id = make_valid(id) where id = '2-205-00876-X!'; select * from test; select isbn13(id) from test; 36.5 插件 isn 卸载方法 不需要使用插件时执行指令 drop extension isn 即可。 36.6 插件 isn 升级方法 isn 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 255 第 37 章 KBCRYPTO 37章 kbcrypto 第 37.1 插件 kbcrypto 简介 kbcrypto 是 KingbaseES 的一个扩展插件，可以提供如 rc4,sm3,sm4,sm2 等加密函数的访问，可以提供明文的加 密打印输出到前端。加密函数功能详情还可参见《KingbaseES 安全指南》中的 手动加密数据章节。 • 插件名为 kbcrypto • 插件版本 V1.3 37.2 插件 kbcrypto 加载方式 KingbaseES 数据库默认将它添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例 shared_preload_libraries = 'kbcrypto' # (change requires restart) 37.3 插件 kbcrypto 的参数配置 无需配置任何参数。 37.4 插件 kbcrypto 的使用方法 加载 kbcrypto 插件后，程序可以提供如 rc4,sm3,sm4,sm2 等加密函数的访问，可以提供明文的加密打印输出到 前端。 256 第 37 章 KBCRYPTO 37.4.1 sm3 函数 37.4.1.1 sm3 函数 功能 实现 sm3 的加密。 语法 sm3(text) 参数说明 加密数据。 示例 select sm3('123456789'); sm3 -----------------------------------------------------------------c7ae0aec3d2f9beb84dc1885aa7a576baa7a07b38060afc64c5600f93a5456b5 37.4.2 sm4 函数 37.4.2.1 sm4 函数 功能 实现 sm4 的加密、解密。 语法 sm4(text,text,int) 参数说明 加/解密数据、密钥、加密/解密标识。标识为 0 代表加密，1 代表解密。 示例 -- 加密 select sm4('123456abcdef','0123456789ABCDEF',0); -- 解密 select sm4(sm4('123456abcdef','0123456789ABCDEF',0), '0123456789ABCDEF',1); 257 第 37 章 KBCRYPTO 37.4.2.2 sm4_ex 函数 功能 实现 sm4 包含填充模式的加密、解密。 语法 sm4(text,text,int,int) 参数说明 加/解密数据、密钥、加密/解密标识。标识为 0 代表加密，1 代表解密。加/解密数据、密钥、加密/解密标识、 填充模式。填充模式如下： 1）填充模式选 1, 数据按 16 字节倍数强制填充，缺 m 个字节则填充 m 个字节的 m 值 (m 最大值为 16)。 2）填充模式选 0，数据按 16 字节倍数非强制填充 0x0, 同 sm4。 示例 -- 1）填充模式选 1 -- 加密 select sm4_ex('123456abcdef','0123456789ABCDEF',0,1); -- 解密 select sm4_ex(sm4_ex('123456abcdef','0123456789ABCDEF',0,1), '0123456789ABCDEF',1,1); -- 2) 填充模式选 0 -- 加密 select sm4_ex('123456abcdef','0123456789ABCDEF',0,0); -- 解密 select sm4_ex(sm4_ex('123456abcdef','0123456789ABCDEF',0,0), '0123456789ABCDEF',1,0); 37.4.3 rc4 函数 37.4.3.1 rc4 函数 功能 实现 rc4 的加密、解密。 语法 rc4(text,text,int) 参数说明 加/解密数据、密钥、加密/解密标识。标识为 0 代表加密，1 代表解密。 258 第 37 章 KBCRYPTO 示例 -- 加密： select rc4('123456abcdef','0123456789ABCDEF',0); -- 解密 select rc4(rc4('123456abcdef','0123456789ABCDEF',0), '0123456789ABCDEF',1); 37.4.4 sm2 函数 37.4.4.1 sm2_genkeypair 函数 功能 用于生成 sm2 密钥对, 包含公钥和私钥。 语法 sm2_genkeypair() 示例 select sm2_genkeypair(); sm2_genkeypair ----------------------------------------------------------------------BEGIN EC PRIVATE KEY----- + MHcCAQEEIE9Gm3HKpfHNq+tKEbEbPNbJ2g3CRffK2DrORokpwwepoAoGCCqGSM49+ AwEHoUQDQgAE/eyOgN64tpxIjGmcSX3WtMXED0MRwL6EEqEctRlQMeOzGkGA/TsM+ sE6nbdqy/AdlazI4xnfQNJ/TzYCA1P3n5w== + -----END EC PRIVATE KEY----- + -----BEGIN PUBLIC KEY----- + MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/eyOgN64tpxIjGmcSX3WtMXED0MR+ wL6EEqEctRlQMeOzGkGA/TsMsE6nbdqy/AdlazI4xnfQNJ/TzYCA1P3n5w== + -----END PUBLIC KEY----- + 37.4.4.2 sm2_encrypt 函数 功能 实现基于 sm2 的加密，加密使用公钥。 语法 259 第 37 章 KBCRYPTO sm2_encrypt(text, text) 参数说明 第一个参数是明文，第二个参数是公钥。 示例 明文设置为“hello^”。 select sm2_encrypt('hello^', 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/ eyOgN64tpxIjGmcSX3WtMXED0MRwL6EEqEctRlQMeOzGkGA/TsMsE6nbdqy/AdlazI4xnfQNJ/TzYCA1P3n5w=='); sm2_encrypt ------------------------------------------------------306f02200e467e63de5937b645efc7110f58be9bec16e769291352+ 04c8fd49b44aafbe0f022100c961b9420abeb74a7a149f3b3603c2+ 5bcea9482285deca98c28ae4e8c3c7471e0420f86602b170334b55+ d6e1e62e7c0299886d9b9516eaec3745d91450ed19702eec04068e+ a88764ef26 + 37.4.4.3 sm2_decrypt 函数 功能 实现基于 sm2 的解密，解密使用私钥。 语法 sm2_decrypt(text, text) 参数说明 第一个参数为密文，第二个参数为私钥。 示例 解密出明文结果为“hello^”。 select sm2_decrypt( '306f02200e467e63de5937b645efc7110f58be9bec16e76929135204c8fd49b44aafbe0f022100c961b9420abeb74a7a149f3b3603c25bcea948228 ', 'MHcCAQEEIE9Gm3HKpfHNq+tKEbEbPNbJ2g3CRffK2DrORokpwwepoAoGCCqGSM49AwEHoUQDQgAE/ eyOgN64tpxIjGmcSX3WtMXED0MRwL6EEqEctRlQMeOzGkGA/TsMsE6nbdqy/AdlazI4xnfQNJ/TzYCA1P3n5w=='); sm2_decrypt --------------------hello^ 260 第 37 章 KBCRYPTO 37.4.4.4 sm2_sign 函数 功能 实现基于 sm2 的签名，签名使用私钥。 语法 sm2_sign(text, text) 参数说明 第一个参数为待签名内容，第二个参数为私钥。 示例 待签名内容例如设置为“hello sign^”。 select sm2_sign('hello sign^', 'MHcCAQEEIE9Gm3HKpfHNq+tKEbEbPNbJ2g3CRffK2DrORokpwwepoAoGCCqGSM49AwEHoUQDQgAE/ eyOgN64tpxIjGmcSX3WtMXED0MRwL6EEqEctRlQMeOzGkGA/TsMsE6nbdqy/AdlazI4xnfQNJ/TzYCA1P3n5w=='); sm2_sign ------------------------------------------------------304502205314636312faba3b0661fbfe0f4076dd2068b8e7b0f1c6+ 9fdea67b642927272e02210093dfaf70db2c8b293f235d2176747b+ 64eba44f5829c20f05d9dac7d0c1f02a50 + 37.4.4.5 sm2_verify 函数 功能 实现基于 sm2 的验签，验签使用公钥。 语法 sm2_verify(text, text, text) 参数说明 第一个参数为待签名内容，第二个参数为签名后内容，第三个参数为公钥。 返回值：函数执行后，会产生两种结果 t（true）或者 f（false），分别代表验签成功和验签失败。 示例 验签结果成功。 261 第 37 章 KBCRYPTO sm2_verify('hello sign^', '304502205314636312faba3b0661fbfe0f4076dd2068b8e7b0f1c69fdea67b642927272e02210093dfaf70db2c8b293f235d2176747b64eba44f582 ', 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/eyOgN64tpxIjGmcSX3WtMXED0MRwL6EEqEctRlQMeOzGkGA/TsMsE6nbdqy/ AdlazI4xnfQNJ/TzYCA1P3n5w=='); sm2_verify -----------------t 37.5 插件 kbcrypto 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例 shared_preload_libraries = '' 37.6 插件 kbcrypto 升级方法 kbcrypto 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 262 第 38 章 KBROWLOCKS 38章 kbrowlocks 第 38.1 插件 kbrowlocks 简介 kbrowlocks 提供了一个函数来显示指定表的行级锁信息。默认仅限超级用户、sys_stat_scan_tables 角色的成员 和在该表上拥有 SELECT 权限的用户使用。 • 插件名为 kbrowlocks • 插件版本 V1.2 38.2 插件 kbrowlocks 加载方式 CREATE EXTENSION kbrowlocks; 38.3 插件 kbrowlocks 的参数配置 无需配置任何参数。 263 第 38 章 KBROWLOCKS 38.4 插件 kbrowlocks 的使用方法 表 38.4.1: kbrowlocks 输出列 名称 类型 描述 locked_row tid 该行的 tid locker xid 持有锁的 xid 号 (可能是 multi xid 号) multi boolean locker 是否是 multi xid xids xid[] 持锁的实际 xid modes text[] 持锁的模式 pids integer[] 持锁 backend 的 pid kbrowlocks 会为目标表加 AccessShareLock 并且逐行读取来收集锁信息，对于大表可能很慢。 注意: 1. 如果表被加了排他锁，kbrowlocks 将被阻塞。 2. kbrowlocks 没有用一个一致的快照扫描。在执行过程中，数据可能被加上新行锁，也可能有旧行锁被释放。 kbrowlocks 不显示被锁定行的内容。如果想同时查看行内容，可以这样做 SELECT * FROM accounts AS a, kbrowlocks('accounts') AS p WHERE p.locked_row = a.ctid; 但要注意，这样的查询将非常低效。 SELECT * FROM kbrowlocks('test_rowlocks'); locked_row | locker | multi | xids | modes | pids ------------+--------+-------+---------+---------------+-------(0,1) | 19574 | f | {19574} | {"For Share"} | {5246} (1 row) 38.5 插件 kbrowlocks 卸载方法 DROP EXTENSION kbrowlocks; 264 第 38 章 KBROWLOCKS 38.6 插件 kbrowlocks 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1 ALTER EXTENSION kbrowlocks UPDATE TO '1.1'; 265 第 39 章 KBSTATTUPLE 39章 kbstattuple 第 39.1 插件 kbstattuple 简介 kbstattuple 提供了多种函数来获得关系中元组的统计信息。默认情况下，只有角色 sys_stat_scan_tables 的成 员和超级用户可以使用。 • 插件名为 kbstattuple • 插件版本 V1.5 39.2 插件 kbstattuple 加载方式 CREATE EXTENSION kbstattuple; 39.3 插件 kbstattuple 的参数配置 无需配置任何参数。 39.4 插件 kbstattuple 的使用方法 kbstattuple 提供以下函数： kbstattuple(regclass) returns record 返回给定关系的物理长度、“死亡”元组百分比等信息。这些信息可以 帮助用户决定是否要对关系做清理。 266 第 39 章 KBSTATTUPLE 表 39.4.1: kbstattuple 输出列 名称 类型 描述 table_len bigint 关系大小，单位字节 tuple_count bigint “活着”的元组数 tuple_len bigint “活着”的元组总大小，单位字节 tuple_percent float8 ” 活着” 的元组大小占关系大小百分比 dead_tuple_count bigint “死亡”的元组数 dead_tuple_len bigint “死亡”的元组总大小，单位字节 dead_tuple_percent float8 ” 死亡” 的元组大小占关系大小百分比 free_space bigint 空闲空间大小，单位字节 free_percent float8 | 空闲空间大小占关系大小百分比 kbstattuple(text) returns record 和 kbstattuple(regclass) 相同，区别是通过字符串指定关系。 kbstatindex(regclass) returns record 返回 B 树索引的相关信息。 表 39.4.2: kbstatindex 输出列 名称 类型 描述 version integer B 树页面类型版本号 tree_level integer root 页面的高度 index_size bigint 索引大小，单位字节 root_block_no bigint root 页面的块号 internal_pages bigint 中间页面的数量 leaf_pages bigint 叶子页面的数量 empty_pages bigint 空页面的数量 deleted_pages bigint 被删除页面的数量 avg_leaf_density float8 叶子页面的平均填充度 leaf_fragmentation float8 叶子页面的碎片化程度 kbstatindex(text) returns record 和 kbstatindex(regclass) 相同，区别是通过字符串指定关系。 kbstatginindex(regclass) returns record 返回 GIN 索引的相关信息。 267 第 39 章 KBSTATTUPLE 表 39.4.3: kbstatginindex 输出列 名称 类型 描述 version integer GIN 索引页面类型版本号 pending_pages integer pending 列表中的页面数 pending_tuples bigint pending 列表中的元组数 kbstathashindex(regclass) returns record 返回 HASH 索引的相关信息。 表 39.4.4: kbstathashindex 输出列 名称 类型 描述 version integer HASH 索引页面类型版本号 bucket_pages bigint 桶页面的页面数 overflow_pages bigint 溢出页的页面数 bitmap_pages bigint 位图页的页面数 unused_pages bigint 未使用页面的页面数 live_items bigint 可用元组数 dead_tuples bigint 无效元组数 free_percent float 空闲空间占比 sys_relpages(regclass) returns bigint 返回关系的页面数。 sys_relpages(text) returns bigint 和 sys_relpages(regclass) 相同，区别是通过字符串指定关系。 kbstattuple_approx(regclass) returns record kbstattuple_approx 是 kbstattuple 的一个更快速的替代，它返 回近似的结果。这个函数通过 VM 页面跳过标记了“全部可见”的页面扫描，并从 FSM 页面中获取这类页面 的空闲空间大小并假设剩余的空间都有“活着的”元组使用。对于不能被跳过的页面，函数会扫描每个元组并 进行统计。最后，它会基于已扫描的页面元组数量来估计“活着”的元组总数。除对应 kbstattuple 的列外，有 一个 float8 类型的列 scanned_percent 显示扫描的页面占比。 39.5 插件 kbstattuple 卸载方法 DROP EXTENSION kbstattuple; 268 第 39 章 39.6 KBSTATTUPLE 插件 kbstattuple 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1 ALTER EXTENSION kbstattuple UPDATE TO '1.1'; 269 第 40 章 KDB_DATABASE_LINK 40章 kdb_database_link 第 40.1 插件 Database Link 简介 Database Link 简称 DBLink，是数据库管理系统提供的用于访问外部数据库对象的机制。用户可以通过 DBLink 来访问外部数据库的表、视图对象。DBLink 实现了两个数据库之间的通信。DBLink 包含一个基于网络的数据连接 以及用于登陆远程数据库的用户名、密码信息。本地数据库系统可以通过 DBLink 建立与远程数据库之间的会话，从 而完成对远程数据库对象的访问。DBLink 实现了 SQL/MED 标准中定义的对外部数据源进行访问的部分功能。 • 插件名为 kdb_database_link • 插件版本 V1.0.0 注意: SQL/MED 是 SQL Management of External Data 的缩写，是 ISO/IEC 9075-9:2003 标准中对 SQL 语言的扩 展。SQL/MED 标准规定了如何通过外部数据封装器（Foreign Data Wrapper）和数据连接（datalink）实现对外部 数据的访问。这里的外部数据指的是可以被基于 SQL 的 DBMS 访问的数据。 dblink 对象是一个数据库内部对象，可以通过 dblink 对象连接引用其他数据库的对象。支持连接 Oracle、KingbaseES 和 Postgresql 的 dblink 对象。 相关定义如下： • 本地数据库当前数据库客户端所连接到的数据库，可以直接访问和操作在此数据库内拥有相应权限的对象，客 户端持有该连接。 • 远程数据库通过定义于本地数据库内的 dblink 访问的数据库，虽然客户端看起来可以直接访问远程数据库的对 象，实际上此类连接由本地数据库持有，对象定义等系统信息在本地数据库并不存在。远程数据库也可能只是 本地数据库通过设置连接到了自己的另一个服务进程或者线程。 • 远程连接通过 dblink 访问远程数据库对象时创建的数据库连接，对于目标数据库，本地数据库是它为之提供服 务的客户端。本地数据库对自己创建和拥有的远程连接，需要进行合理的管理，在必要时应及时关闭，防止过 多的资源开销。 • 远程表（视图、物化视图）存在于远程数据库上的表，也可能是视图或者物化视图，本地数据库对此并不关 心，只关心所取得的数据结构定义和数据本身。 270 第 40 章 KDB_DATABASE_LINK • 远程序列存在于远程数据库上的序列发生器，通常用于统一 id 的生成。 • 远程函数（存储过程）存在于远程数据库上的函数或者存储过程，一般远程调用函数的场景居多。 • 远程同义词存在于本地数据库指向远程对象（表、序列、函数等等）的同义词。 40.1.1 Database Link 功能 Dblink 功能主要是为了满足常见语法的适配，让用户应用的代码能够适用于更宽泛的产品而无需在移植时大量 修改 • 支持连接管理，在适当的时候关闭连接减少远程数据库的资源开销。 • 支持远程表（视图、物化视图）的查询，并且支持下推查询条件减少数据传输的网络开销。 • 支持远程表的插入。 • 支持远程序列的访问。 • 支持远程用户自定义函数 (存储过程) 的访问。目前仅支持 KingbaseES 数据库。 40.2 插件 kdb_database_link 的加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 shared_preload_libraries = 'kdb_database_link' 在 ksql 中，运行 CREATE EXTENSION kdb_database_link; 40.3 插件 kdb_database_link 的参数配置 • DriverName 连接驱动名称。 • Host 远程数据库网络地址。 • Port 远程数据库服务端口。 • Dbname 271 第 40 章 KDB_DATABASE_LINK 远程数据库名称。 • DbType 远程数据库类型。DbType 支持 Oracle，KingbaseES，Postgres 三种数据库类型。 40.4 插件 kdb_database_link 的使用方法 40.4.1 创建 Database Link 对象 在创建 dblink 对象时指定连接信息，包括远程数据库网络地址、端口、数据库名称、用户名和密码，具体需要 提供哪些信息会因为不同数据库存在差异。 语法格式 CREATE [ PUBLIC ] DATABASE LINK dblink CONNECT TO user IDENTIFIED BY password USING {(connect_string) | config_tag }; 参数说明 PUBLIC 指定 PUBLIC 创建公有 dblink 对象，所有用户都可以访问公有 dblink 对象。公有 dblink 是创建在 PUBLIC 模式下面的。未指定 PUBLIC 时创建私有 dblink，不可在 PUBLIC 模式下创建私有 dblink。 dblink 指定要创建的数据库链接的名称，同一个模式下的 dblink 不能重名。 user IDENTIFIED BY password 指定远端数据库的用户名和密码。 connect_string 配置连接串信息，connect_string 用来提供用于连接到远程数据库的信息。 config_tag 配置文件标签名, 用于指明配置文件（sys_database_link.conf）中的一项, 从而通过配置文件获取用于建 立数据库连接的远程数据库的网络地址、端口以及数据库名称。 注解 1、在配置文件中的格式如下 [名称] DriverName= 连接驱动名称。 Host= 远程数据库网络地址。 Port= 远程数据库服务端口。 Dbname= 远程数据库名称。 DbType= 远程数据库类型。 DbType 支持 Oracle，KingbaseES，Postgres 三种数据库类型。 272 第 40 章 KDB_DATABASE_LINK 2、使用该功能时，需将 kdb_database_link 加入 shared_preload_libraries 中。 3、查询外部数据库时，需创建对应的数据库插件，如:kingbase_fdw、oracle_fdw、postgres_fdw。 示例 创建一个到 Oracle 数据库的数据库连接，它可以被所有数据库用户使用 CREATE PUBLIC DATABASE LINK mylink CONNECT TO 'SYSTEM' IDENTIFIED BY 'password' USING 'ORADB'; 创建一个到 Oracle 数据库的数据库连接，直接指定连接串信息 CREATE PUBLIC DATABASE LINK mylink CONNECT TO 'SYSTEM' IDENTIFIED BY 'password' USING (DriverName='Oracle ODBC Driver', Host='192.168.0.1', Port=1521, Dbname='TEST', dbType='Oracle'); 40.4.2 修改 Database Link 对象 ALTER DATABASE LINK 修改一个 dblink 数据库对象。 第一种形式更改 dblink 的拥有者，要修改拥有者，你必须拥有该 dblink 并且也是新拥有角色的一个直接或间接 成员。 第二种形式更改 dblink 的名称，只有 dblink 拥有者或者超级用户可以重命名一个 dblink。 语法格式 ALTER [PUBLIC] DATABASE LINK dblink_name OWNER TO new_owner; ALTER [PUBLIC] DATABASE LINK dblink_name RENAME TO new_name; 参数说明 dblink_name 一个现有 dblink 的名称（可以是模式限定的）。 new_owner 该 dblink 的新拥有者的用户名。 dblink_name 该 dblink 的新名称。 注解 ALTER DATABASE LINK 语法类似于 ALTER VIEW。 示例 把 DATABASE LINK kdb_dblink_regress.link_d 拥有者修改为 kdb_dblink_user: ALTER DATABASE LINK kdb_dblink_regress.link_d OWNER TO kdb_dblink_user; 兼容性 ALTER DATABASE LINK 语句是一个 KingbaseES 扩展。 273 第 40 章 KDB_DATABASE_LINK 40.4.3 删除 Database Link 对象 DROP DATABASE LINK 移除一个 dblink。要执行这个命令必须拥有该 dblink 的权限。 语法格式 DROP DATABASE LINK dblink_name; 参数说明 dblink_name 删除名为 dblink_name 的 DATABASE LINK 注解 DBLink 可以被拥有者和 DBA 删除, 删除 DBLink 对象之后，所有的用户会话中的对象都会被清除。 如果 DBLink 正在被其他用户使用，则无法删除此 DBLink。 暂不支持 PUBLIC 关键字。 兼容性 该命令是 KingbaseES 的一个扩展，兼容 Oracle。 40.4.4 Database Link 的权限控制 对于私有的 DBLink，其创建者和 DBA 具有对此 DBLink 对象进行访问的权限。除 DBLink 创建者之外的其他 数据库用户可以对以 PUBLIC 方式建立的 DBLink 进行访问。 本地用户对远程数据库对象的访问权限由远程数据库系统的用户认证机制来控制。通过 DBLink 连接到远程数据 库的本地用户将得到远程数据库的用户拥有的查询权限。 40.4.5 DBLink 相关的视图 DBLink 向用户提供的视图如下： 表 40.4.1: DBLink 相关视图 名称 说明 ALL_DBLINKS 描述当前用户可以访问的所有数据库连接 USER_DBLINKS 描述当前用户拥有的所有数据库连接 DBA_DBLINKS 描述 DBA 可以访问的所有数据库连接 274 第 40 章 KDB_DATABASE_LINK 40.4.6 DATABASE LINK DML DATABASE LINK —dblink 的 DML 操作 语法格式 • INSERT [ WITH [ RECURSIVE ] with_query [, ...] ] INSERT INTO table_name@dblink [ AS alias ] [ ( column_name [, ...] ) ] [ OVERRIDING { SYSTEM | USER} VALUE ] { VALUES ( { expression } [, ...] ) [, ...] | query } [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]; • UPDATE [ WITH [ RECURSIVE ] with_query [, ...] ] UPDATE table_name@dblink [ * ] [ [ AS ] alias ] SET { column_name = { expression } | ( column_name [, ...] ) = [ ROW ] ( { expression } [, ...] ) | ( column_name [, ...] ) = ( sub-SELECT ) } [, ...] [ FROM from_list ] [ WHERE condition ] [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]; • DELETE [ WITH [ RECURSIVE ] with_query [, ...] ] DELETE FROM table_name@dblink [ * ] [ [ AS ] alias ] [ WHERE condition ] [ RETURNING * | output_expression [ [ AS ] output_name ] [, ...] ]; 描述 使用 dblink 对远程表进行插入，更新，删除。 参数 dblink dblink 的名称，使用 CREATE DATABASE LINK 创建的 dblink 数据库连接的名称。 with_query WITH 子句允许你指定一个或者多个子查询，在 INSERT UPDATE DELETE 查询中可以用子查询的名字来引 用它们详见 WITH 查询和 SELECT 。 table_name 一个已有表的名称（可以被模式限定）。 alias 目标表名的替补名称。当提供了一个别名时，它会完全隐藏掉表的实际名称。 column_name 名为 table_name 的表中的一个列的名称，可以用表名 (可以被模式名限定) 做限定。如有必要，列名 还可以用一个子域名 (子域名需要和表名、模式名一同用小括号包围起来进行限定) 或者数组下标限定。 275 第 40 章 KDB_DATABASE_LINK expression 要赋予给相应列的表达式或者值。 output_expression 在每一行被插入或更新或删除后由 INSERT 或 UPUDATE 或 DELETE 命令计算并且返回的表达 式。该表达式可以使用 “table_name“ 指定的表中的任何列。写成 * 可返回被插入或更新或删除行的所有列。 output_name 要用于被返回列的名称。 condition 一个能返回 boolean 值的表达式。只有让这个表达式返回 true 的行才将被更新，删除。 使用限制 • INSERT 远端表插入操作不支持 ON CONFLICT 子句 不支持显示指定生成列的值 对于 RETURNING，不支持 RETURNING ctid 等系统列 暂不支持列的默认值，对于有默认值的远程表，在进行 insert 的时候，如果显式使用例如 insert into {tablename} default value 或者 insert into {tablename} values(default) 会报错 dblink not support insert with default value；如果 insert into 的时候，没有指定全部的列也会报上面的错误比如当表 tab 有两列 a, b 的时候，那么下面 sql 都会报错 1. insert into tab@dblink values(1) 2. insert into tab@dblink(a) values(1) 3. insert into tab@dblink select a from tab 4. insert into tab@dblink(a) select a from tab • UPDATE 当远端表为继承表时，不支持仅更新父表数据，指定 ONLY 关键字时报错 对于 RETURNING，不支持 RETURNING ctid 等系统列 目前 update 不支持列的默认值，在进行 update 的时候，如果显式的指定使用默认值，比如 update {tablenaem} set {columname}=default，会报错 dblink not support insert with default value 目前不支持 WHERE CURRENT OF cursor_name 的用法 目前 update 对于 分区表和 继承表的行为表现不确定，所以禁止使用 dblink 更新远程 分区表或者 继 承表中的数据 • DELETE 当远端表为继承表时，不支持仅删除父表数据，指定 ONLY 关键字时报错 对于 RETURNING，不支持 RETURNING ctid 等系统列 目前 delete 对于 分区表和 继承表的行为表现不确定，所以禁止使用 dblink 删除远程 分区表或者 继 承表中的数据 ORACLE 兼容 276 第 40 章 KDB_DATABASE_LINK 当 dblink 创建的数据库连接是连接到 Oracle 的时候，除了以上的使用限制外，目前 dblink 还不支持 UPDATE 和 DELETE 40.4.7 DATABASE LINK MERGE DATABASE LINK —dblink 的 MERGE 操作 语法格式 MERGE INTO [ schema. ] { target_table@dblink } [ [ AS ] target_table_alias ] USING { [ schema. ] { source_table } [ [ AS ] source_table_alias ] ON ( condition_expression ) [ merge_update_clause ] [ merge_insert_clause ]; merge_update_clause: WHEN MATCHED THEN UPDATE SET column = { expr }[, column = { expr } ]... [ where_clause ] [ delete_clause ] delete_clause: [DELETE where_clause] merge_insert_clause: WHEN NOT MATCHED THEN INSERT [ ( column [, column ]...) ] VALUES ({ expr }[, { expr } ]...) [ where_clause ] where_clause: WHERE condition 描述 使用 dblink 对远程表进行 MERGE 操作。 参数 target_table MERGE 远程目标表的名称。 dblink dblink 的名称，使用 CREATE DATABASE LINK 创建的 dblink 数据库连接的名称。 source_table MERGE 源表的名称。源表可以是一个本地表，普通外表，也可以是一个 dblink 的远程表，即 tablename@dblinkname。 target_table_alias MERGE 目标表的别名。 source_table_alias MERGE 源表的别名。 277 第 40 章 KDB_DATABASE_LINK expr 要赋予给相应列的表达式或者值。 condition_expression 指 定 目 标 表 与 源 表 之 间 进 行 联 接 的 联 接 条 件。 如 果 该 条 件 为 真， 且 指 定 了 WHEN MATCHED THEN UPDATE 子句，则对匹配到的目标表的该元组执行更新操作；否则，如果该条件为假 且指定了 WHEN NOT MATCHED THEN INSERT 子句，则对目标表执行插入操作。 merge_update_clause 当目标表和源表的 ON 条件为真时，执行该子句，即更新目标表数据。该更新操作会触发目 标表上面的触发器。更新的列不能是 ON 条件中被引用的列，更新时可以通过 WHERE 条件指明要更新的行， 条件中既可以包含源表的列，也可以包含目标表的列，当指明 WHERE 条件且条件为假时，则不更新。 delete_clause DELETE 子句只删除目标表和源表的 ON 条件为真、并且是更新后的符合删除条件的记录， DELETE 子句不影响 INSERT 项插入的行。删除条件作用在更新后的记录上，既可以和源表相关，也可以和 目标表相关，或者都相关。如果 ON 条件为真，但是不符合更新条件，并没有更新数据，那么 DELETE 将不 会删除任何数据。 merge_insert_clause 当目标表和源表的 ON 条件为假时，执行该语句。可指定插入条件，插入时的 WHERE 条件 只能引用源表中的列。VALUES 后面也只能引用源表中的列，不能包含目标表的列。 40.4.8 DATABASE LINK 调用函数/存储过程 DATABASE LINK —dblink 调用用户自定义函数/存储过程 语法格式 [schema_name.] func_name@dblink([args]) CALL [schema_name.]proc_name@dblink([args]) 描述 使用 dblink 访问远程用户自定义函数/存储过程。 参数 dblink dblink 的名称，使用 CREATE DATABASE LINK 创建的 dblink 数据库连接的名称。 schema_name 远程模式名称。 func_name 远程用户自定义函数/储存过程名称。 args 函数/储存过程的参数。 使用限制 • 函数 当在同一用户模式下存在同名函数时，该函数不支持通过远程调用。dblink 函数的调用方式，支持 select func@dblink(arg) 这种方式。不支持 select * from func@dblink(arg) 方式，以及 call func@dbink(arg) 的这种方 式。 支持在以下语句类型中调用： 278 第 40 章 KDB_DATABASE_LINK 1. SELECT 列表； 2. WHERE/HAVING 条件； 3. WITH/GROUP BY/ORDER BY； 4. INSERT 的 VALUES 子句； 5. UPDATE 的 SET 子句； 6. JOIN 条件； 7. PL/SQL 中引用。 不支持以下函数类型： – 聚集函数 – 窗口函数 – PIPELINED 函数 函数属性支持情况如下： 1. IMMTABLE：该函数不能修改数据库，并且对于给定的参数值总是会返回相同的值； 2. STABLE：该函数不能修改数据库，并且对于相同的参数值，它在一次表扫描中将返回相同的结果； 3. VOLATILE：该函数的值在一次表扫描中有可能改变，不能做优化； 4. PARALLEL : a. UNSAFE：该函数不能在并行模式中运行并且 SQL 语句中存在一个这样的函数会强制使用顺序执行计 划； b. RESTRICTED：该函数能在并行模式中运行，但是其执行被限制在并行组的 leader 中； c. SAFE：该函数可以不受限制的在并行模式中执行； 5. STRICT：该函数中任意参数为空值时，函数返回值也为空值。 其中，函数参数只支持 IN 模式，支持远程函数参数默认值。参数个数最大支持 510 个。参数类型和返回值支 持 KingbaseES 的基本内置数据类型。 • 存储过程 支持使用 “CALL“调用远程用户自定义存储过程。在 dlbink 用户有执行权限的情况下，允许跨模式调 用其他用户定义的存储过程。另外，当同一模式下存在同名存储过程时，该存储过程不能通过 dblink 远程调用。 目前仅支持 in 参数，不支持 out 参数和 inout 参数。存储过程的参数个数不大于 98 个。 兼容性 目前仅支持 KingbaseES 远程数据库调用函数、存储过程。 279 第 40 章 KDB_DATABASE_LINK 40.5 插件 kdb_database_link 的卸载方法 在 ksql 中运行： drop extension kdb_database_link; 修改 kingbase.conf 文件中 shared_preload_libraries 参数，去掉 kdb_database_link 后重启数据库。 shared_preload_libraries = ''; 40.6 插件 kdb_database_link 的升级方法 kdb_database_link 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 280 第 41 章 KDB_DATE_FUNCTION 41章 kdb_date_function 第 41.1 插件 kdb_date_function 简介 kdb_date_function 是一个兼容 mysql 数据库 date 相关函数的扩展。 • 插件名为 kdb_date_function • 插件版本 V1.1 41.2 插件 kdb_date_function 加载方式 启动 KingbaseES 数据库后执行 SQL 命令创建插件。 示例： create extension kdb_date_function; 41.3 插件 kdb_date_function 的参数配置 无需配置任何参数。 41.4 插件 kdb_date_function 的使用方法 41.4.1 date_add date_add —实现日期的相加 语法 281 第 41 章 KDB_DATE_FUNCTION date_add(ts timestamp, iv interval) 返回 timestamp。 date_add(tstz timestamptz, iv interval) 返回 timestamptz。 描述 date_add 会实现 timestamp 或 timestamptz 与指定的 interval 进行相加的运算。 参数 iv：用于日期相加运算中的 interval 类型值。 ts：用于日期相加运算中的 timestamp 类型值。 tstz：用于日期相加运算中的 timestamptz 类型值。 返回值 返回计算完成的特定的日期类型值。 示例 select date_add('2000-10-10'::timestamp,interval '1 year'); date_add --------------------2001-10-10 00:00:00 (1 行记录) select date_add('2010-10-10 12:00:00'::timestamp,interval '1 year 1 day 2 hour'); date_add --------------------2011-10-11 14:00:00 (1 行记录) 41.4.2 dateadd dateadd —实现日期的相加 语法 dateadd(i_unit text, i_value numeric, i_date time) 返回 time。 dateadd(i_unit text, i_value numeric, i_date timestamp) 返回 timestamp。 dateadd(i_unit text, i_value numeric, i_date timestamptz) 返回 timestamptz。 描述 实现 timestamp 或 timestamptz 或 time 类型与指定的格式进行相加的运算。 参数 i_unit：指定要相加的 i_value 的格式。 282 第 41 章 KDB_DATE_FUNCTION i_value：指定要相加的数量。 i_date：指定被相加的日期。 返回值 返回计算完成的特定的日期类型值。 注解 i_unit 的值可以为’second’,’minute’,’hour’,’day’,’week’,’month’,’year’ 等。 示例 select dateadd('year',9998,'0001-01-01 00:00:00'::timestamptz); dateadd -----------------------9999-01-01 00:00:00+00 (1 行记录) select dateadd('year',201,'1900-01-01 00:00:00'::timestamptz); dateadd -----------------------2101-01-01 00:00:00+00 (1 行记录) 41.4.3 datediff 比较两个日期之间的差距 语法 datediff(d1 date, d2 date) 返回 integer。 datediff(t text, d1 date, d2 date) 返回 int8。 datediff(t text, d1 time, d2 time) 返回 int8。 datediff(t text, d1 timetz, d2 timetz) 返回 int8。 datediff(t text, d1 timestamp, d2 timestamp) 返回 int8。 datediff(t text, d1 timestamptz, d2 timestamptz) 返回 int8。 描述 比较两个日期之间的指定的 text（如果存在此 ** 参数 **）的格式的差距。 参数 t：指定的要返回的日期差距的格式。d1,d2：进行比较的两个日期值。 返回值 返回 text 类型指定的格式的整数值。 283 第 41 章 KDB_DATE_FUNCTION 注解 t 的值可以使’second’,’minute’,’hour’,’day’,’week’,’month’,’year’ 等。 示例 select datediff('year','0001-01-01'::date,'9999-12-31'::date); datediff ---------9998 (1 行记录) select datediff('year','1900-01-01 00:00:00'::date,'2000-12-31 00:00:00'::date); datediff ---------100 (1 行记录) select datediff(month,'0001-01-01 00:00:00'::date,'9999-12-31 00:00:00'::date); datediff ---------119987 (1 行记录) select datediff(month,'1900-01-01 00:00:00'::date,'2000-12-31 00:00:00'::date); datediff ---------1211 (1 行记录) select datediff('month','0001-01-01 00:00:00'::date,'9999-12-31 00:00:00'::date); datediff ---------119987 (1 行记录) select datediff('month','1900-01-01 00:00:00'::date,'2000-12-31 00:00:00'::date); datediff ---------1211 (1 行记录) 41.4.4 date_format 得到指定日期的指定格式的值。 284 第 41 章 KDB_DATE_FUNCTION 语法 date_format(d timestamp, t text) 返回 text。 date_format(d timestamptz, t text) 返回 text。 描述 返回日期类型值的 text 指定的格式。 参数 t：指定的要返回的日期的格式。 d：目标格式的值。 返回值 返回 text 指定的 text 类型的值。 注解 t 的值可以是 nls_date_format 类型的所有值。 示例 select date_format('2000-10-10 12:00:00','mm-yyyy-dd hh24:mi:ss'); date_format --------------------10-2000-10 12:00:00 (1 行记录) 41.5 插件 kdb_date_function 卸载方法 在数据库中执行 SQL 命令卸载插件。 示例： drop extension kdb_date_function; 41.6 插件 kdb_date_function 升级方法 kdb_date_function 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 285 第 42 章 KDB_DDL 42章 kdb_ddl 第 42.1 插件 kdb_ddl 简介 kdb_ddl 是 KingbaseES 的一个扩展插件，用于生成数据库对象 DDL 语句，主要包括数据库对象创建、修改、 删除语句的生成。每个用户仅可以查询自己有使用和查询权限的数据库对象，不包含数据库系统的预创建对象，如系 统视图，INT 类型等。 目前仅支持以下类型对象使用 kdb_ddl 接口查询生成数据库对象 DDL 语句： • FUNCTION • PACKAGE • PROCEDURE • TRIGGER • TYPE • VIEW 上述对象在当前数据库中的状态不论为有效还是无效，均可以通过 kdb_ddl 拓展中提供的接口获取相应的语句 脚本。 注意: 仅当 KingbaseES 处于 ORACLE 模式时，支持 kdb_ddl 扩展中的接口功能。 42.2 插件 kdb_ddl 加载方式 kdb_ddl 不在数据库初始化时创建，需要通过命令创建扩展 kdb_ddl： CREATE EXTENSION kdb_ddl; 286 第 42 章 KDB_DDL 插件 kdb_ddl 的参数配置 42.3 无需配置任何参数。 42.4 插件 kdb_ddl 使用方法 42.4.1 获取完整的数据库对象 DDL 脚本 数据库对象完整 DDL 脚本的定义包括：对象包括目标对象的删除，创建以及授权语句。在脚本语句中，依次为 删除语句，创建语句和授权语句。其中删除语句可以根据用户提供的选项决定是否显示，以及是否添加 if exists 子 句。其中，授权语句只有在授权动作产生后才会显示。 42.4.1.1 通过对象名获取完整的 DDL 脚本 函数 ddlx_script 用于获取数据库对象的完整定义的 DDL 脚本。该接口有两个重载版本，其中一个版本可以通 过对象名称获取完整的 DDL 脚本。 语法 FUNCTION kdb_ddl.ddlx_script(ddlx_name text, ddlx_schema text DEFAULT NULL, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 ddlx_name 对象的名称。对于函数或存储过程，可以通过传入参数类型来确保唯一性，未传入参数时若匹配到多个目 标对象，输出错误提示。用户传入的对象名不存在时，输出错误提示。例如： SELECT kdb_ddl.ddlx_script('func1(int)'); SELECT kdb_ddl.ddlx_script('func1()'); SELECT kdb_ddl.ddlx_script('func1'); ddlx_schema 目标对象的模式名，用于确定目标对象的在数据库中的唯一性，默认为 NULL。当该参数为 NULL 时， ddlx_script 接口会在用户指定的当前的 search_path 内利用目标对象的名称与目标对象的类型进行对象 匹配，若未匹配到对象或者匹配到多个对象，则报错。 ddlx_type 287 第 42 章 KDB_DDL 目标对象的类型，默认为 NULL，使用时仅可以提供一个选项。当该参数为 NULL 时，ddlx_script 接口 会在支持的对象范围内搜索与对象名匹配的对象并返回完整的 DDL 脚本，若有多个对象匹配，输出错误 提示。当用户使用的类型不属于预定义类型内容时，输出错误提示。具体可选值详见表ddlx_type 参数可 选值 。 表 42.4.1: ddlx_type 参数可选值 ddlx_type 参数 描述 FUNCTION 当前获取对象类型为函数。 PROCEDURE 当前获取对象类型为存储过程。 PACKAGE 当前获取对象类型为包。 PACKAGE_SPEC 当前获取对象类型为包声明。 PACKAGE_BODY 当前获取对象类型为包定义。 TRIGGER 当前获取对象类型为触发器。 TYPE 当前获取对象类型为数据类型，包括当前模式数据库所支持的 所有数据类型。 TYPE_SPEC 当前获取对象类型为类型声明，包括当前模式数据库所支持的 所有数据类型。 TYPE_BODY 当前获取对象类型为对象类型定义，若对非对象类型对象使用 该参数，则报错。 VIEW 当前获取对象类型为视图。 当指定目标对象的类型为 PACKAGE_BODY 或者 TYPE_BODY，但实际数据库对象不存在对应的 BODY 时，输出错误提示。对于其它数据类型，也可以通过指定对象类型为 TYPE_SPEC 来获取结果。 ddlx_options 控制 DDL 脚本内容的选项参数，默认为空，使用时可以同时传递多个选项，当多个选项之间存在冲突 的选项时，输出错误提示。当用户使用的选项不属于预定义选项内容时，输出错误提示。具体可选值详见 表ddlx_options 参数可选值。 表 42.4.2: ddlx_options 参数可选值 ddlx_options 参数 描述 drop 显示脚本中的删除语句。 见续表 288 第 42 章 KDB_DDL 表 42.4.2 – 续表 ddlx_options 参数 描述 nodrop 不显示脚本中的删除语句。 owner 总是显示修改 owner 的语句，若没有该选项，则当当前 session 的用户与数据库对象属主相同时，自动省略修改 owner 的 语句。 noowner 不显示设置 owner 的语句。 nogrants 不显示授权相关的语句。 nodcl 不显示设置 owner 语句，也不显示授权相关语句。 noalter 不显示 owner，dcl，授权相关的语句。 ine 为视图创建语句添加 if not exists 子句，若非视图对象，则报 错。 ie drop 语句添加 if exists 子句。 返回值 对象的 DDL 脚本语句。 示例 获取目标函数的 DDL 脚本。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / CREATE OR REPLACE FUNCTION func2(i INT DEFAULT func1(1)) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_script('func1(int)', 'public', 'FUNCTION', '{owner}'); ddlx_script ----------------------------------------------------------------------------DROP FUNCTION func1(integer); + + 289 第 42 章 KDB_DDL -- Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; + END; + + ALTER FUNCTION func1(integer) OWNER TO test; + + REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + 42.4.1.2 根据 OID 获取完整的 DDL 脚本 函数 ddlx_script 用于获取数据库对象的完整定义的 DDL 脚本。该接口有两个重载版本，其中一个版本可以通 过对象 OID 获取完整的 DDL 脚本。 语法 FUNCTION kdb_ddl.ddlx_script(ddlx_id oid, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 ddlx_id 对象的 OID，用户传入的 OID 不存在时，输出错误提示。 其它参数与通过对象名获取完整的 DDL 脚本 的 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的 DDL 脚本语句。 290 第 42 章 KDB_DDL 示例 获取目标函数的 DDL 脚本。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / CREATE OR REPLACE FUNCTION func2(i INT DEFAULT func1(1)) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_script('func1(int)'::regprocedure, 'FUNCTION', '{owner}'); ddlx_script ----------------------------------------------------------------------------DROP FUNCTION func1(integer); + + -- Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; + END; + ALTER FUNCTION func1(integer) OWNER TO test; + + + REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + 291 第 42 章 KDB_DDL 42.4.2 获取数据库对象创建语句 42.4.2.1 通过对象名获取创建语句 ddlx_create 和 ddlx_createonly 用于获取数据库对象的创建语句，二者的区别为 ddlx_create 接口为完整的创建 语句，包含了目标对象的权限处理语句，ddlx_createonly 接口就是纯粹的对象定义创建语句，并不包含权限处理语 句。两个接口均有两个重载版本，其中一个版本可以通过对象名称获取对象的创建语句。 42.4.2.1.1 包含权限处理的对象创建语句 ddlx_create 函数用于获取包含权限处理的对象的创建语句。 语法 FUNCTION kdb_ddl.ddlx_create (ddlx_name text, ddlx_schema text DEFAULT NULL, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的创建语句，包含权限处理语句。 示例 获取目标函数的创建语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_create ('func1(int)', 'public', 'FUNCTION', '{owner}'); ddlx_create ------------------------------------------------------------------------------ Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + 292 第 42 章 KDB_DDL -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; + END; + + ALTER FUNCTION func1(integer) OWNER TO test; + + REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + 42.4.2.1.2 不包含权限处理的对象创建语句 ddlx_create 函数用于获取不包含权限处理的对象的创建语句。 语法 FUNCTION kdb_ddl.ddlx_createonly (ddlx_name text, ddlx_schema text DEFAULT NULL, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的创建语句，不包含权限处理语句。 示例 获取目标函数的创建语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; 293 第 42 章 KDB_DDL SELECT kdb_ddl.ddlx_createonly ('func1(int)', 'public', 'FUNCTION', '{owner}'); ddlx_createonly ------------------------------------------------------------------------------ Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; + END; + + ALTER FUNCTION func1(integer) OWNER TO test; 42.4.2.2 + 通过 OID 获取创建语句 ddlx_create 和 ddlx_createonly 用于获取数据库对象的创建语句，二者的区别为 ddlx_create 接口为完整的创建 语句，包含了目标对象的权限处理语句，ddlx_createonly 接口就是纯粹的对象定义创建语句，并不包含权限处理语 句。两个接口均有两个重载版本，其中一个版本可以通过对象 OID 获取对象的创建语句。 42.4.2.2.1 包含权限处理的对象创建语句 ddlx_create 函数用于获取包含权限处理的对象的创建语句。 语法 FUNCTION kdb_ddl.ddlx_create (ddlx_id oid, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的创建语句，包含权限处理语句。 294 第 42 章 KDB_DDL 示例 获取目标函数的创建语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_create ('func1(int)'::regprocedure, 'FUNCTION', '{owner}); ddlx_create ------------------------------------------------------------------------------ Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; + END; + + ALTER FUNCTION func1(integer) OWNER TO test; + + REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + 42.4.2.2.2 不包含权限处理的对象创建语句 ddlx_create 函数用于获取不包含权限处理的对象的创建语句。 语法 FUNCTION kdb_ddl.ddlx_createonly (ddlx_name text, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) 295 第 42 章 KDB_DDL RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的创建语句，不包含权限处理语句。 示例 获取目标函数的创建语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_createonly (('func1(int)'::regprocedure, 'FUNCTION', '{owner}); ddlx_createonly ------------------------------------------------------------------------------ Type: FUNCTION; Name: func1(integer); Owner: test; Status: VALID + + -- Depend: + -- Not Found + + -- Depended: + -- Type: FUNCTION; Name: func2(integer); + + CREATE OR REPLACE FUNCTION public.func1(integer) + RETURNS integer + AS + BEGIN + RETURN 1; END; + + + ALTER FUNCTION func1(integer) OWNER TO test; 42.4.3 + 获取数据库对象删除语句 删除语句可以根据用户提供的选项决定是否显示，以及是否添加 if exists 子句。 296 第 42 章 KDB_DDL 42.4.3.1 通过对象名获取删除语句 ddlx_drop 函数用于获取数据库对象的删除语句，该接口有两个重载版本，其中一个版本可以通过对象的名称获 取对象的删除语句。 语法 FUNCTION kdb_ddl.ddlx_drop (ddlx_name text, ddlx_schema text DEFAULT NULL, ddlx_type text DEFAULT NULL, ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的删除语句。 示例 获取目标函数的删除语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_drop ('func1(int)', 'public', 'FUNCTION'); ddlx_drop ------------------------------DROP FUNCTION func1(integer); 42.4.3.2 通过 OID 获取删除语句 ddlx_drop 函数用于获取数据库对象的删除语句，该接口有两个重载版本，其中一个版本可以通过对象的 OID 获取对象的删除语句。 语法 FUNCTION kdb_ddl.ddlx_drop (ddlx_id oid, ddlx_type text DEFAULT NULL, 297 第 42 章 KDB_DDL ddlx_options text[] DEFAULT '{}'::text[]) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的删除语句。 示例 获取目标函数的删除语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_drop ('func1(int)'::regprocedure, 'FUNCTION'); ddlx_drop ------------------------------DROP FUNCTION func1(integer); 42.4.4 获取数据库对象授权语句 42.4.4.1 通过对象名获取授权语句 ddlx_grants 函数用于获取数据库对象的授权语句，该接口有两个重载版本，其中一个版本可以通过对象的名称获取对象的授权语 授权语句只有在授权动作产生后才会显示 语法 FUNCTION kdb_ddl.ddlx_grants (ddlx_name text, ddlx_schema text DEFAULT NULL, ddlx_type text DEFAULT NULL RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 298 第 42 章 KDB_DDL 对象的授权语句。 示例 获取目标函数的授权语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_grants ('func1(int)', 'public', 'FUNCTION'); ddlx_grants ---------------------------------------------------------------------------REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + 42.4.4.2 通过 OID 获取授权语句 ddlx_grants 函数用于获取数据库对象的授权语句，该接口有两个重载版本，其中一个版本可以通过对象的 OID 获取对象的授权语句。授权语句只有在授权动作产生后才会显示。 语法 FUNCTION kdb_ddl.ddlx_grants (ddlx_id oid, ddlx_type text DEFAULT NULL) RETURN TEXT 参数说明 参数与 ddlx_script 函数描述一致，详见 ddlx_script 函数的参数说明 。 返回值说明 对象的授权语句。 示例 获取目标函数的授权语句。 \set SQLTERM / CREATE OR REPLACE FUNCTION func1(int) RETURN INT AS BEGIN RETURN 1; 299 第 42 章 KDB_DDL END; / \set SQLTERM ; SELECT kdb_ddl.ddlx_grants ('func1(int)'::regprocedure, 'FUNCTION'); ddlx_grants ---------------------------------------------------------------------------REVOKE ALL ON FUNCTION func1(integer) FROM PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO PUBLIC; + GRANT EXECUTE ON FUNCTION func1(integer) TO test_user; + GRANT EXECUTE ON FUNCTION func1(integer) TO test WITH GRANT OPTION; + 42.5 插件 kdb_ddl 卸载方法 删除 kdb_ddl 扩展，示例如下： DROP EXTENSION kdb_ddl; 42.6 插件 kdb_ddl 升级方法 kdb_ddl 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 300 第 43 章 KDB_EXISTS_EXPAND 43章 kdb_exists_expand 第 43.1 插件 kdb_exists_expand 简介 kdb_exists_expand 插件用于优化 EXISTS 子链接，生成执行效率更高的执行计划。 对于在查询条件中存在 EXISTS 子连接的 SQL 语句，如果满足： 1. EXISTS 子链接为 SELECT 类型的查询语句 2. EXISTS 子链接中为 OR 条件 如下： SELECT * from t1 WHERE EXISTS (SELECT 1 from t2 cond1 OR cond2); 其中的 cond1 的查询条件和子链接中查询的表 t2 有关，cond2 的查询条件和子链接中查询的表 t2 无关，如： SELECT * from t1 WHERE EXISTS (SELECT 1 from t2 WHERE t2.id =1 OR t1.name = null); • 其中 cond1 为 t2.id =1，与子链接中的表 t2 相关 • 其中 cond2 为 t1.name = null，与子链接中的表 t2 不相关 那么该插件将 EXISTS 子链接的不相关条件做提升优化，可以提高 SQL 查询的执行效率。 43.2 插件 kdb_exists_expand 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'kdb_exists_expand' 301 第 43 章 KDB_EXISTS_EXPAND 插件 kdb_exists_expand 的参数配置 43.3 kdb_exists_expand.enable Exists 子链接优化开关，boolean 类型数据，默认为开启状态。 插件 kdb_exists_expand 的使用方法 43.4 KingbaseES 加载 kdb_exists_expand 插件后，碰到满足简介中条件的 SQL 语句时，将 EXISTS 子链接的不相 关条件做提升优化。 示例： 启动该功能后，本来应该是一个 Semi join 的执行计划，被改成了两个并列的子计划 InitPlan 1 和 InitPlan 2 去 执行： create extension kdb_exists_expand; load 'kdb_exists_expand'; set kdb_exists_expand.enable to on; create table t1(id int, name text); create table t2(id int, name text); explain (costs off) SELECT * from t1 WHERE EXISTS (SELECT 1 from t2 WHERE t2.id =1 OR t1.name = null); QUERY PLAN ---------------------------------Result One-Time Filter: ($0 OR $1) InitPlan 1 (returns $0) -> Seq Scan on t2 Filter: (id = 1) InitPlan 2 (returns $1) -> Result One-Time Filter: false -> Seq Scan on t1 43.5 插件 kdb_exists_expand 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 302 第 43 章 KDB_EXISTS_EXPAND 示例： shared_preload_libraries = '' 43.6 插件 kdb_exists_expand 升级方法 kdb_exists_expand 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 303 第 44 章 KDB_FLASHBACK 44章 kdb_flashback 第 44.1 插件 kdb_flashback 简介 插件 kdb_flashback 是 KingbaseES 的一个扩展插件。主要功能是提供错误数据的快速恢复能力，目前提供的闪 回技术包括闪回回收站，闪回查询，闪回版本查询，闪回到任意时间点。 • 插件名为 kdb_flashback • 插件版本 V1.0 44.2 插件 kdb_flashback 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'kdb_flashback' 44.3 插件 kdb_flashback 的参数配置 kdb_flashback.enable_flashback_query 闪回查询的开启参数，默认开启。 kdb_flashback.db_recyclebin 闪回回收站开启参数，参数为 bool 类型，参数级别为 PGC_SIGHUP，默认关闭。 44.4 插件 kdb_flashback 的使用方法 闪回查询相关的技术使用方法 304 第 44 章 KDB_FLASHBACK • 整个闪回技术 (闪回查询和闪回表到指定时间点) 可以通过时间戳和 CSN(commit sequence number) 两种方式 进行。 • 两种方式目前都需要依赖提交的时间戳，因此需要开启 track_commit_timestamp 这个参数。另外闪回查询还 需要开启 kdb_flashback.enable_flashback_query 的参数。 • 这里解释下时间戳和 CSN 两个快照指定的方式，时间戳即 timestamp 用户可以在闪回查询的快照时间表达式 里指定任意一个有效的时间戳。 如果允许闪回查询，那么将返回该时刻能够可见的历史快照的数据。CSN 是提交顺序号，第一个有效的 CSN 为 65536000000，CSN 随着提交线性增加。因此如果用户指定一个有效的 CSN，比如 65536000160，那么闪回查询将基 于这个 CSN 提交号构建历史快照。 • 闪回查询技术有一定的限制，在数据进行深度清理后和部分 schema change 后将拒绝闪回查询（具体参考闪回 查询须知）。 下 面 具 体 介 绍 这 几 种 闪 回 技 术, 在 使 用 任 何 闪 回 查 询 相 关 的 技 术 前， 保 证 在 配 置 文 件 中 开 启 track_commit_timestamp 参数，并重启服务。 44.4.1 闪回查询 闪回查询能否返回用户指定历史时刻的快照数据，历史快照时刻指定方式可以通过 timestamp 和 csn 两种方式指 定 (具体语法参考 SELECT)。 例 2-56AS OF 闪回查询（timestamp）语句的示例 flashback=# create table fb_example(id int, name varchar(100)); CREATE TABLE flashback=# insert into fb_example values(1, 'name1'); INSERT 0 1 flashback=# insert into fb_example values(2, 'name1'); INSERT 0 1 flashback=# insert into fb_example values(3, 'name1'); INSERT 0 1 flashback=# select * from fb_example; id | name ----+------1 | name1 2 | name1 3 | name1 (3 rows) flashback=# \set 'tp1' `date "+%Y-%m-%d %H:%M:%S.%N"` flashback=# update fb_example set name = null; UPDATE 3 flashback=# select * from fb_example; id | name 305 第 44 章 KDB_FLASHBACK ----+-----1 | 2 | 3 | (3 rows) flashback=# select * from fb_example as of timestamp :'tp1'; id | name ----+------1 | name1 2 | name1 3 | name1 (3 rows) 例 2-56 中的 update 语句误将 name 更改为 null，此时可以通过闪回查询查询到 update 前的数据。 通常 CSN 方式进行闪回查询的时候，需要借助闪回版本查询确定合适的 CSN 号，比如 delete 事务误将 fb_example 表删除了，那么通过版本查询可以确定该 delete 事务的 CSN 为 65536000007，可以通过如下的闪回语 句查询删除的数据。 例 2-57AS OF 闪回查询（CSN）语句的示例 flashback=# select versions_startscn, versions_endcsn, * from fb_example versions between csn minvalue and maxvalue; versions_startscn | versions_endcsn | id | name -------------------+-----------------+----+------65536000003 | 65536000006 | 1 | name1 65536000004 | 65536000006 | 2 | name1 65536000005 | 65536000006 | 3 | name1 65536000006 | 65536000007 | 1 | 65536000006 | 65536000007 | 2 | 65536000006 | 65536000007 | 3 | (6 rows) flashback=# select * from fb_example as of csn 65536000006; id | name ----+-----1 | 2 | 3 | (3 rows) 44.4.2 闪回版本查询 闪回版本查询的作用主要有以下几个方面： 306 第 44 章 KDB_FLASHBACK • 进行历史数据的分析。 • 查看数据的变更历史。 • 确定闪回表的精确时间点。 闪回版本查询拥有和 Oracle 相同的参考伪列，伪列和功能参考下表。 表 44.4.1: 闪回版本查询的伪列 伪列名 描述 VERSIONS_STARTTIME 元组被创建的时间戳 VERSIONS_ENDTIIME 元组被删除的时间戳 VERSIONS_STARTCSN 元组被创建的 commit seqno VERSIONS_ENDCSN 元组被删除的 commit seqno VERSIONS_OPERATION 对应的操作 D 表示该元组被删除，I 表示该元组被插入 VEERSIONS_XID 元组被创建的事务 ID 闪回版本查询的 start 和 end 的快照表达式既可以指定一个有效的快照表达式，也可以通过 minvalue 和 maxvalue 两个关键字进行查询。当指定时，将返回该表能够闪回查询的所有的版本信息。 例 2-58 通过 minvalue 和 maxvalue 进行闪回版本查询（CSN）语句的示例 flashback=# select versions_startcsn, versions_endcsn, versions_operation, * from fb_example versions between csn minvalue and maxvalue; versions_startcsn | versions_endcsn | versions_operation | id | name -------------------+-----------------+--------------------+----+------65536000003 | 65536000006 | D | 1 | name1 65536000004 | 65536000006 | D | 2 | name1 65536000005 | 65536000006 | D | 3 | name1 65536000006 | 65536000007 | D | 1 | 65536000006 | 65536000007 | D | 2 | 65536000006 | 65536000007 | D | 3 | 65536000008 | | I | 5 | name3 65536000009 | | I | 6 | name3 (8 rows) 通过上面的例子，我们可以追溯 fb_example 的版本变更的历史，65536000006 这个 CSN 的事务做了一次 update 的操作，65536000007 这个 CSN 的事务做了一次 delete 的操作。因此如果我们想查询被删除前的数据可以尝试 65536000006 这个 CSN 快照。 307 第 44 章 KDB_FLASHBACK 44.4.3 闪回表到指定时间点 闪回表到指定的时间点，实际上为用户提供了还原数据的一种手段，如果说闪回查询能够帮助用户查询历史的数 据，那么闪回表实际上是帮助用户彻底的找回数据, 具体语法参考 FLASHBACK。 闪回表的通常步骤： • 通过闪回版本查询确定待闪回的版本范围，查询 startxxx, endxxx, 和 operation 确定边界。 • 通过 AS OF 闪回查询结合确定的边界锁定闪回查询的精确时间点，并观察数据时候符合预期。 • 通过 FLASHBACK TABLE TO [ Timestamp | CSN ] asof_item，完成表的闪回。 还是参考 2-58 的例子，比如我们推理出错误更新 name 的事务是 65536000006 这个 CSN，那么我们可以指定 65536000005 进行闪回查询。再通过 flashback 闪回到误更前的时刻。 flashback=# select * from fb_example as of csn 65536000005; id | name ----+------1 | name1 2 | name1 3 | name1 (3 rows) flashback=# flashback table fb_example to csn 65536000005; FLASHBACK TABLE flashback=# select * from fb_example; id | name ----+------1 | name1 2 | name1 3 | name1 (3 rows) 44.4.4 闪回查询和闪回表技术的使用须知 • 闪回查询和闪回表技术依赖于历史的数据，如果历史数据因为 vacuum、truncate、rewrite 等操作被回收掉， 那么会导致无法闪回到这些操作之前的时刻。因此推荐用户在期望使用闪回查询的时候对 vacuum 相关参数做 一定的调整（关闭表级的 autovacuum, 推荐调大 vacuum_defer_cleanup_age 的值以降低历史数据被回收的机 会）。 • 目前闪回查询和闪回表技术在 vacuum、truncate、和部分 ddl 之后将不允许进行闪回到这些操作之前。 • 闪回查询应用于视图或者物化视图里面应该尽量避免对于常量时间戳和 CSN 的使用，可能会引发 dump 和 restore 的失败。 308 第 44 章 KDB_FLASHBACK 闪回回收站 44.4.5 闪回回收站功能为用户提供一种误删表后还原表的一种手段，闪回回收站分为将回收站中的表闪回到删除之前的 状态和清空回收站。 例 2-59flashback table to before drop 语句的示例 test=# flashback table range_partition_tb to before drop; FLASHBACK TABLE test=# \d List of relations Schema | Name | Type | Owner -----------+----------------------------+-------------------+-------- flashback | range_partition_tb | partitioned table | system flashback | range_partition_tb_part_01 | table | system flashback | range_partition_tb_part_02 | table | system (3 rows) 回收站需用户定期维护，避免回收站膨胀，用户可以通过 PURGE 操作对回收站进行维护，PURGE 操作分为删 除回收站中一个指定表和清空回收站。清理回收站时，回收站视图 recyclebin 和系统表 sys_recyclebin 中相关对象将 被清除。 例 2-60purge table 语句的示例 test=# select * from recyclebin; oid | original_name | droptime | type -------+----------------------------+-------------------------------+------24968 | range_partition_tb_part_02 | 2022-05-20 15:14:53.581052+08 | TABLE 24965 | range_partition_tb_part_01 | 2022-05-20 15:14:53.581494+08 | TABLE 24962 | range_partition_tb | 2022-05-20 15:14:53.582074+08 | TABLE 24971 | purge_test | 2022-05-20 15:15:45.027217+08 | TABLE 24974 | purge_test1 | 2022-05-20 15:16:49.466221+08 | TABLE (5 rows) test=# purge table purge_test; PURGE test=# select * from recyclebin; oid | original_name | droptime | type -------+----------------------------+-------------------------------+------24968 | range_partition_tb_part_02 | 2022-05-20 15:14:53.581052+08 | TABLE 24965 | range_partition_tb_part_01 | 2022-05-20 15:14:53.581494+08 | TABLE 24962 | range_partition_tb | 2022-05-20 15:14:53.582074+08 | TABLE 24974 | purge_test1 | 2022-05-20 15:16:49.466221+08 | TABLE (4 rows) test=# purge recyclebin; 309 第 44 章 KDB_FLASHBACK PURGE test=# select * from recyclebin; oid | original_name | droptime | type -----+---------------+----------+-----(0 rows) 44.5 插件 kdb_flashback 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例 shared_preload_libraries = '' 44.6 插件 kdb_flashback 升级方法 kdb_flashback 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 310 第 45 章 KDB_LICENSE 第 45.1 45章 kdb_license 插件 kdb_license 简介 插件 kdb_license 是 KingbaseES 的一个扩展插件。主要功能是管理服务器 license 相关的信息。默认加载，属于 内置功能。 • 插件名为 kdb_license • 插件版本 V1.0 45.2 插件 kdb_license 加载方式 KingbaseES 数据库默认在初始化数据库时，自动加载 kdb_license 扩展插件。无须人为加载。 45.3 插件 kdb_license 的参数配置 无需配置任何参数 45.4 插件 kdb_license 的使用方法 KingbaseES 数据库初始化时自动加载 kdb_license 扩展插件。通常用户不直接使用该扩展插件。 45.5 插件 kdb_license 卸载方法 kdb_license 无法人为卸载。 311 第 45 章 KDB_LICENSE 45.6 插件 kdb_license 升级方法 kdb_license 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 312 第 46 章 KDB_MYSQL_FUNCTIONS 46章 kdb_mysql_functions 第 46.1 插件 kdb_mysql_functions 简介 kdb_mysql_functions 是 KingbaseES 中的一个扩展插件，能够提供一些兼容 MySQL 的函数。 46.2 插件 kdb_mysql_functions 加载方式 KingbaseES 默认加载 kdb_mysql_functions 扩展插件。若需要手动创建扩展 kdb_mysql_functions，可执行： 示例： CREATE EXTENSION kdb_mysql_functions; 46.3 插件 kdb_mysql_functions 配置参数 无需配置任何参数 46.4 插件 kdb_mysql_functions 使用方法 kdb_mysql_functions 提供的函数具体语法和使用内容可参考《KingbaseES SQL 语言参考手册》的 函数章节。 下表列出了 kdb_mysql_functions 扩展所提供的函数。 313 第 46 章 46.5 KDB_MYSQL_FUNCTIONS 插件 kdb_mysql_functions 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。或者使用 DROP EXTENSION 命 令进行卸载。 示例： DROP EXTENSION kdb_mysql_functions; 46.6 插件 kdb_mysql_functions 升级方法 kdb_mysql_functions 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 314 第 47 章 KDB_ORACLE_DATATYPE 第 47.1 47章 kdb_oracle_datatype 插件 kdb_oracle_datatype 简介 插件 kdb_oracle_datatype 初始化内置，兼容 Oracle 数据类型。 • 插件名为 kdb_oracle_datatype • 插件版本 V1.3 47.2 插件 kdb_oracle_datatype 加载方式 默认已经创建，如果没有创建需要在命令行执行 create extension kdb_oracle_datatype; 示例： create extension kdb_oracle_datatype; 47.3 插件 kdb_oracle_datatype 的参数配置 无需配置任何参数。 47.4 插件 kdb_oracle_datatype 的使用方法 加载插件 kdb_oracle_datatype 后，按照如下方式使用相应功能。 315 第 47 章 KDB_ORACLE_DATATYPE 47.4.1 支持 blob、clob、nclob 类型导入导出和置空 实现数值类型转换为字符类型 语法 调用如下函数使用： blob_import(text)、blob_export(bytea, text)、empty_blob()、 clob_import(text, text)、clob_export(text, text, text)、empty_clob()、 nclob_import(text, text)、nclob_export(text, text, text)、empty_nclob() 示例 select blob_export('a'::bytea,'test'::text); blob_export ------------1 (1 行记录) select blob_import('test'::text); blob_import ------------a (1 行记录) select empty_blob(); empty_blob -----------(1 行记录) 47.4.2 bpcharbyte 类型 支持 bpcharbyte 类型 示例 select '12'::bpcharbyte; bpcharbyte -----------12 (1 行记录) 316 第 47 章 KDB_ORACLE_DATATYPE 47.4.3 bpcharbyte 类型操作符 bpcharbyte 类型之间支持 =、<>、>、>=、<、<= 和 ~<~、~>~、~<=~、~、!~、~*、!~*、~~、!~~、~~*、 !~~* 操作符。 示例 select '12'::bpcharbyte ~>=~ '12'::bpcharbyte; ?column? ---------t (1 行记录) 47.4.4 bpcharbyte 类型转换 支持 bpcharbyte 类型和 text、bpchar、varchar 类型转换。 示例： select '12'::bpcharbyte::varchar; varchar --------12 (1 行记录) select '12'::bpcharbyte::text; text -----12 (1 行记录) select '12'::bpcharbyte::bpchar; bpchar -------12 (1 行记录) 47.5 插件 kdb_oracle_datatype 卸载方法 系统启动自带插件，无法卸载。 317 第 47 章 KDB_ORACLE_DATATYPE 47.6 插件 kdb_oracle_datatype 升级方法 kdb_oracle_datatype 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 318 第 48 章 KDB_ORACLE_DATATYPE_NLS 48章 kdb_oracle_datatype_nls 第 插件 kdb_oracle_datatype_nls 简介 48.1 插件 kdb_oracle_datatype_nls 兼容 oracle 日期 date 类型。此插件已经合入到插件 kdb_oracle_datatype 中。 • 插件名为 kdb_oracle_datatype_nls • 插件版本 V1.0 插件 kdb_oracle_datatype_nls 加载方式 48.2 此插件已经合入到插件 kdb_oracle_datatype 中，跟随插件 kdb_oracle_datatype 加载自己加载。 插件 kdb_oracle_datatype_nls 的参数配置 48.3 无需配置任何参数。 48.4 插件 kdb_oracle_datatype_nls 的使用方法 48.4.1 操作符的支持 支持操作符 +、示例： select '2019-01-01'::date + '1'::interval as A; a --------------------- 319 第 48 章 KDB_ORACLE_DATATYPE_NLS 2019-01-01 00:00:01 (1 行记录) select '2019-01-03'::date - '2019-01-01'::date as A; a --2 (1 行记录) 48.4.2 索引的支持 支持 hash 和 brin 索引。 示例： create table t1(c1 date); create index hash_index on t1 using hash(c1); create table t1(c1 date); create index brin_index on t1 using brin(c1); 48.5 插件 kdb_oracle_datatype_nls 卸载方法 此插件已经合入到插件 kdb_oracle_datatype 中，插件 kdb_oracle_datatype 为系统启动自带插件，无法卸载。 48.6 插件 kdb_oracle_datatype_nls 升级方法 kdb_oracle_datatype_nls 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插 件。 320 第 49 章 KDB_PARTMAN 49章 kdb_partman 第 49.1 插件 kdb_partman 简介 49.1.1 功能和发展 partman 是可帮助使用者更轻松地管理基于 time 或 serialid 的分区表。partman 只需要几个选项，就可以设置 分区。 子表的创建全部由 partman 自身管理。对于非本地分区，插件还会维护触发器函数。具有现有数据的表，在非 本地分区中，可以将其数据分区为易于管理的小批次；在本地分区中，必须首先创建新的父分区，并在创建过程完成 后迁移数据。 49.1.2 插入数据机制解释 对于非本地分区，如果尝试将数据插入到超过分区集范围的分区集中，则该数据将放入该集的父表中。与自动创 建新分区以匹配该数据相比，这是首选，因为这种策略能够规避插入非分区数据的错误可能会导致产生大量不需要的 子表以及由于 DDL 事务而产生的竞争。 check_default() 函数提供对插入到父默认表中的数据的监视，如果数据是有效数据，则 partition_data_* 函数 集可以轻松地为该数据分区。这比必须清理可能数百或数千个不需要的分区要容易得多，而且也比抛出错误并丢失数 据更好！ 49.1.3 插入数据的策略 请注意，将来的子表创建基于分区集中的当前数据。这意味着，如果放入” 未来” 数据，则新创建的表将不基于 该值。如果不存在子表，这可能会导致在这期间的数据转到父/默认值，如上所述。 建议你将预制值设置得足够高，以包含要插入的预期数据范围。对于非本地分区，请设置 optimize_trigger 值以 有效地处理最常见的数据范围。 321 第 49 章 KDB_PARTMAN 49.1.4 partman 的设计约束和特性 49.1.4.1 时区 保证 partman 运行的操作系统的时区一致性非常重要，尤其是使用基于时间建立的分区。对 kdb_partman 函数 的调用将使用客户端在调用函数时设置的时区。这与 PG 客户端的一般工作方式一致。 强烈建议在 UTC 时间内运行数据库系统，以解决由于夏令时更改而无法解决的问题。然后，还要确保将创建分 区集和运行维护调用的客户端也设置为 UTC。 49.1.4.2 子分区 支持具有多个级别的子分区，但它在 PG 中的用途非常有限，并且在单个分区集（100TB，PB）中的超大数据 之外，它几乎没有性能优势。如果你正在寻找提高性能的方法，请考虑在使用子分区之前调整分区间隔，它是数据组 织和保留管理的主要方法。 对可以执行的子分区级别没有设置限制，但要明智，并牢记在单个继承集中管理多个表时的性能注意事项。此 外，如果单个分区集中的表数变得非常大，则可能必须将 max_locks_per_transactionpostgresql.conf 设置调整到默 认值 64 以上。否则，你可能会遇到共享内存问题，甚至是群集崩溃问题。 如果在调用 run_maintenance() 对所有分区集进行常规维护时遇到竞争问题，可以将 part_config 表中的 automatic_maintenance 列设置为 false。但是，你必须调用 run_maintenance（parent_table），并且必须足够频繁地调 用将来的分区。 如果你使用的是 PG11+，则可以使用新的 run_maintenance_proc（）过程来减少竞争问题，因为它在每个分区 集的维护后会自动提交。本地子分区不支持逻辑复制的发布者/预订者机制。 49.1.4.3 Retention 如果不需要将数据保留在较旧的分区中，则可以使用保留机制来自动删除不需要的子分区。默认情况下，它们只 是未继承/分离的，实际上不会被删除，但如果需要，可以对其进行配置。 还有一种方法可以在表不再需要位于数据库中但仍需要保留，要设置保留策略，请在 part_config 表的保留列中 输入间隔或整数值。对于基于时间的分区，间隔值将设置仅包含早于该时间的数据的任何分区将被删除； 对于基于 id 的分区，整数值将设置 id 值小于当前最大 id 值减去保留值的任何分区。例如，如果当前最大 id 为 100，保留值为 30，则 id 值小于 70 的任何分区都将被删除。drop 函数运行始终参考的当前最大 id 值。 请记住，对于子分区集，当父表删除了子表时，如果该子表又被分区，则该删除是级联，在这个继承树下面的子 表都将被删除。另请注意，由 kdb_partman 管理的分区集必须始终至少有一个子级，因此保留机制永远不会删除集 中的最后一个子表。 322 第 49 章 KDB_PARTMAN 49.1.4.4 约束排除 约束排除是 partman 的一大特性。但是，大多数分区设置的问题在于，这将仅用于分区控制列。如果对分区集 中的任何其他列使用 WHERE 条件，则将对所有子表进行扫描，除非这些列上也存在约束。 预测列的值将是什么来预先创建约束可能非常困难或不可能。kdb_partman 具有对分区集中的旧表应用约束的 功能，该分区集可能不再对它们进行任何编辑（”old” 被定义为早于 optimize_constraint 配置值）。 它检查给定列中的当前最小值/最大值，然后对该子表应用约束。这可以允许约束排除功能在 WHERE 条件下使 用其他列时，潜在地消除扫描较旧的子表。这限制了编辑这些列的能力，但对于适用这些列的情况，它可能会对非常 大的分区集的查询性能产生巨大影响。 因此，如果你只插入新数据，这可能非常有用，但如果在整个分区集中定期插入/更新数据，则作用有限。如果 数据最终必须在那些较旧的分区中进行编辑，partman 还提供了轻松创建约束的功能。 49.1.4.5 自定义时间间隔注意事项 create_parent 函数中提供的时间间隔列表经过优化，可在非本地、基于触发器的分区中非常快地起作用。除了 这些值之外，还可以使用其他间隔，但非常影响性能。 对于本地分区，与 kdb_partman 基于触发器的方法不同，对于任何给定的时间间隔，没有不同的分区方法。使 用本地方法的所有可能的时间间隔都具有相同的性能特征，并且比任何基于触发器的方法都更好。 如果需要的分区间隔不同于 kdb_partman 提供的优化间隔，强烈建议升级到 PG10。支持的最小时间间隔为 1 秒，上限由 PG 支持的最小和最大时间戳值限制，此时支持的最小整数间隔为 10。 首次运行 create_parent 函数创建分区集时，在确定要创建的第一个分区时，小于一天的会向小时舍入。例如小 于 24 小时但大于 1 分钟的间隔舍入的最近小时。小于 1 分钟的间隔使用舍入的最接近的分钟。 当运行 create_parent 时， 可 能 创 建 的 分 区 多 于 预 期， 并 且 可 能 不 会 创 建 所 有 的 分 区。 第 一 次 运 行 run_maintenance 将修复缺少的分区，发生这种情况是由于 partman 支持自定义时间间隔的特性造成的。 对于等于或大于 100 年的间隔，partman 将使用千年的实际开始来确定分区名称和约束规则。例如，21 世纪和 第 3 个千禧年开始于 2001 年 1 月 1 日（不是 2000 年）。 49.1.4.6 命名长度限制 PG 的对象命名长度限制为 63 个字符。因此，如果 partman 尝试创建具有较长名称的对象，则在命名限制之 下，将会自动截断对象名称中超出 63 个字符的部分。这可能会导致依赖于具有专门命名的后缀的分区名称出现明显 问题。 partman 会自动处理所有子表、触发器函数和触发器的此问题。它将截断现有的父表名称以适合所需的后缀。 请注意，如果表的名称很长，名称相似，则当它们是单独分区集的一部分时，可能会遇到命名冲突。使用基于串 行的分区时，请注意，随着时间的推移，表名将被越来越多地截断，以适应更长的分区后缀。因此，建议保留将分区 的表名尽可能短。 323 第 49 章 KDB_PARTMAN 49.1.4.7 唯一约束和更新 PG 中的表继承不允许将父表上的主键或唯一索引/约束应用于所有子表。该约束应用于每个单独的表，但不应 用于整个分区集。 例如，这意味着粗心大意的应用程序可能会导致分区集中的主键值重复。同时，check_unique_constraint.py 脚 本包含在 kdb_partman 中，可以提供监视。 重要说明：自 4.6.0 版和 PG 11+ 起，kdb_partman 不再支持本地分区的更新插入。请使用 PG 自带的 INSERT...ONCONFLICT 功能。 对于非本地分区和 PG10 本地分区，INSERT ...ONCONFLICT（upsert）在分区触发器和本地分区中都受支 持，但都是受限制的。主要限制是，上面提到的，触发 ON CONFLICT 子句的约束冲突仅发生在实际包含数据的 单个子表上。 比数据重复更大的问题是 ONCONFLICT DOUPDATE 从句，它可能不会触发并导致数据非常不一致。对于仅 插入新数据的情况，upsert 可以提供显著的性能改进。 但是，如果你依赖较旧分区中的数据来导致 upsert 通常会处理的约束冲突，则它可能不起作用。此外，如果生 成的 UPDATE 最终违反了该子表的分区约束，它将失败。 kdb_partman 和 PG10 本地分区目前都不支持需要将行从一个子表移动到另一个子表的 UPDATES。这仅在 PG11 以上的版本中支持。 kdb_partman 的更新插入功能是可选的，默认情况下关闭，并且仅包含在没有 PG 支持的版本上。目前，如果 你尚未实现此功能，强烈建议你升级到 PG11。 49.1.4.8 日志记录/监控 PG 的 Jobmon 插件是可选的，允许审核和监视分区维护。如果 jobmon 安装并配置正确，partman 将自动使用 它，无需额外设置。还可以通过使用 part_config 表中的 jobmon 列或在初始设置期间选择 create_parent（）来为每 个分区集单独打开或关闭 Jobmon。 请注意，如果你尝试对使用 pg_jobmon 的表进行分区，则必须将 create_parent（）中的 jobmon 选项设置为 false，否则它将被放入永久死锁，因为 pg_jobmon 将尝试写入时，就会分区。默认情况下，任何连续 3 次无法成功 运行的函数都会导致 jobmon 引发警报。 这就是为什么默认的预做值设置为 4，以便及时引发警报以进行干预，而无需对 jobmon 进行额外配置。当然， 如果需要，你可以将 jobmon 配置为在 3 次故障之前（或之后）发出警报。 如果你在生产环境中运行 partman，强烈建议你安装 jobmon 并配置某种第三方监控（Nagios，Circonus 等）， 以便在分区失败时发出警报。 49.1.4.9 后台进程 KingbaseES 支持创建自定义后台工作线程并在运行时动态加载它们的功能。kdb_partman 的 BGW 基本上只是 一个调度程序，它为你运行 run_maintenance（）函数，因此你不必使用外部调度程序（cron 等）。 324 第 49 章 KDB_PARTMAN 现在，它与直接调用 run_maintenance（）没有任何不同，但将来可能会改变。如果需要直接在任何特定分区 集上调用 run_maintenance（），则仍需要使用外部调度程序手动执行此操作。这仅将 part_config 中的 automatic_maintenance 设置为 true 的分区集。 日志消息被输出到正常的 PG 日志文件，以记录 BGW 何时运行。如果 log_min_messages 设置为”DEBUG1”， 则其他级别的日志记录消息被记录。 插件 kdb_partman 加载方式 49.2 KingbaseES 数据库默认不加载 kdb_partman, 如果用户需要使用 kdb_partman 的相关功能，请人为手动使用以 下命令加载 kdb_partman 插件。 示例： create extension kdb_partman; 49.3 插件 kdb_partman 的参数配置 无需配置任何参数 49.4 插件 kdb_partman 的使用方法 从 4.4.0 开始，SECURITY DEFINER 已从 kdb_partman 中的所有函数中删除。现在，要求超级用户使用 kdb_partman 对于本地分区是可选的。 若要以非超级用户身份运行，运行 kdb_partman 功能和维护的角色必须拥有它们管理的所有分区集的所有权， 并有权在将包含它所管理的分区集的任何架构中创建对象。为了便于使用和权限管理，建议创建专用于分区管理的角 色。 49.4.1 函数 49.4.1.1 create 函数 用于创建具有一个父表和继承子表的分区集 325 第 49 章 KDB_PARTMAN create_parent(p_parent_table text, p_control text, p_type text, p_interval text, p_constraint_cols text[] DEFAULT NULL, p_premake int DEFAULT 4, p_automatic_maintenance text DEFAULT 'on', p_start_partition text DEFAULT NULL, p_inherit_fk boolean DEFAULT true, p_epoch text DEFAULT 'none', p_upsert text DEFAULT '', p_ publications text[] DEFAULT NULL, p_trigger_return_null boolean DEFAULT true, p_template_table text DEFAULT NULL, p_jobmon boolean DEFAULT true, p_date_trunc_interval text DEFAULT NULL) RETURNS boolean 创建已存在的分区集的子分区集。 create_sub_parent(p_top_parent text, p_control text, p_type text, p_interval text, p_native_check text DEFAULT NULL, p_constraint_cols text[] DEFAULT NULL, p_premake int DEFAULT 4, p_start_partition text DEFAULT NULL, p_inherit_fk boolean DEFAULT true, p_epoch text DEFAULT 'none', p_upsert text DEFAULT '', p_trigger_ return_null boolean DEFAULT true, p_jobmon boolean DEFAULT true, p_date_trunc_interval text DEFAULT NULL) RETURNS boolean 对在将父表设置为基于时间的分区集之前可能存在的数据进行分区。 partition_data_time(p_parent_table text, p_batch_count int DEFAULT 1, p_batch_interval interval DEFAULT NULL, p_lock_wait numeric DEFAULT 0, p_order text DEFAULT 'ASC', p_analyze boolean DEFAULT true, p_source_ table text DEFAULT NULL, p_ignored_columns text[] DEFAULT NULL) RETURNS bigint 在将父表设置为 serial id 分区集之前可能存在的分区数据。 partition_data_id(p_parent_table text, p_batch_count int DEFAULT 1, p_batch_interval bigint DEFAULT NULL, p_ lock_wait numeric DEFAULT 0, p_order text DEFAULT 'ASC', p_analyze boolean DEFAULT true, p_source_table text DEFAULT NULL, p_ignored_columns text[] DEFAULT NULL) RETURNS bigint 可以在不同的提交批处理中对数据进行分区，以避免长时间运行的事务和数据竞争问题。 partition_data_proc(p_parent_table text, p_interval text DEFAULT NULL, p_batch int DEFAULT NULL, p_wait int DEFAULT 1, p_source_table text DEFAULT NULL, p_order text DEFAULT 'ASC', p_lock_wait int DEFAULT 0, p_lock_ wait_tries int DEFAULT 10, p_quiet boolean DEFAULT false, p_ignored_columns text[] DEFAULT NULL) 为给定的基于时间父表创建子分区。 create_partition_time(p_parent_table text, p_partition_times timestamptz[], p_analyze boolean DEFAULT true, p_start_partition text DEFAULT NULL) RETURNS boolean 为给定的基于 serial id 父表创建子分区。 create_partition_id(p_parent_table text, p_partition_ids bigint[], p_analyze boolean DEFAULT true, p_start_ partition text DEFAULT NULL) RETURNS boolean 为非本地基于时间的分区创建触发器函数 326 第 49 章 KDB_PARTMAN create_function_time(p_parent_table text, p_job_id bigint DEFAULT NULL) RETURNS void 为非本地基于 serial id 的分区创建触发器函数 create_function_id(p_parent_table text, p_job_id bigint DEFAULT NULL) RETURNS void 49.4.1.2 维护函数 将此函数作为计划作业（cron 等）运行，以便为配置为使用它的分区集自动创建子表 run_maintenance(p_parent_table text DEFAULT NULL, p_analyze boolean DEFAULT NULL, p_jobmon boolean DEFAULT true) RETURNS void 对于 PG11 以上，这是运行分区维护与直接调用 run_maintenance（）函数的首选方法 run_maintenance_proc(p_wait int DEFAULT 0, p_analyze boolean DEFAULT NULL, p_jobmon boolean DEFAULT true) 运行此函数以监视 kdb_partman 管理的分区集的父表（非本地表）或默认表（本地 PG11+）是否未向其插入 行。 check_default(p_exact_count boolean DEFAULT true) 列出由 kdb_partman 管理的给定分区集的所有子表。 show_partitions (p_parent_table text, p_order text DEFAULT 'ASC', p_include_default boolean DEFAULT false) RETURNS TABLE (partition_schemaname text, partition_tablename text) 给定由 kdb_partman 管理的父表和适当的值，返回该值将存在于其中的子分区的名称。 show_partition_name (p_parent_table text, p_value text, OUT partition_table text, OUT suffix_timestamp timestamp, OUT suffix_id bigint, OUT table_exists boolean) 给定一个 schema 限定的子表名，返回该子表的相关边界值以及追加到子表名的后缀。 @extschema@.show_partition_info (p_child_table text, p_partition_interval text DEFAULT NULL, p_parent_table text DEFAULT NULL, OUT child_start_time timestamptz, OUT child_end_time timestamptz, OUT child_start_id bigint, OUT child_end_id bigint, OUT suffix text) RETURNS record 用于返回必要命令以在 kdb_partman 中为给定的父表重新创建分区集的函数 @extschema@.dump_partitioned_table_definition(p_parent_table text, p_ignore_template_table boolean default false) RETURNS text 用于填充给定父表的子表系列中可能存在的间隔的函数 327 第 49 章 KDB_PARTMAN partition_gap_fill(p_parent_table text) RETURNS integer 将约束应用于为已配置的列的给定分区集中的子表 apply_constraints(p_parent_table text, p_child_table text DEFAULT NULL, p_analyze boolean DEFAULT FALSE, p_ job_id bigint DEFAULT NULL) RETURNS void 删除由 kdb_partman 为在 part_config 中配置的列创建的约束。 drop_constraints(p_parent_table text, p_child_table text, p_debug boolean DEFAULT false) PG11 以上，kdb_partman 管理的额外约束 reapply_constraints_proc(p_parent_table text, p_drop_constraints boolean DEFAULT false, p_apply_constraints boolean DEFAULT false, p_wait int DEFAULT 0, p_dryrun boolean DEFAULT false) 根据父表设置的内容，对所有子表重新应用所有权和 grants。 reapply_privileges(p_parent_table text) 将分区集中的父表上存在的任何外键应用于所有子表。PG10 之前使用 apply_foreign_keys(p_parent_table text, p_child_table text DEFAULT NULL, p_job_id bigint DEFAULT NULL, p_ debug boolean DEFAULT false) 从 part_config_sub 表中删除 parent_table 条目 stop_sub_partition(p_parent_table text, p_jobmon boolean DEFAULT true) RETURNS boolean 49.4.1.3 销毁函数 销毁由 partman 创建的函数 undo_partition(p_parent_table text, p_batch_count int DEFAULT 1, p_batch_interval text DEFAULT NULL, p_keep_ table boolean DEFAULT true, p_lock_wait numeric DEFAULT 0, p_target_table text DEFAULT NULL, p_ignored_ columns text[] DEFAULT NULL, p_drop_cascade boolean DEFAULT false, OUT partitions_undone int, OUT rows_ undone bigint) RETURNS record 在不同的提交批处理中取消分区数据，以避免长时间运行的事务和数据竞争问题 undo_partition_proc(p_parent_table text, p_interval text DEFAULT NULL, p_batch int DEFAULT NULL, p_wait int DEFAULT 1, p_target_table text DEFAULT NULL, p_keep_table boolean DEFAULT true, p_lock_wait int DEFAULT 0, p_lock_wait_tries int DEFAULT 10, p_quiet boolean DEFAULT false, p_ignored_columns text[] DEFAULT NULL, p_ drop_cascade boolean DEFAULT false) 328 第 49 章 KDB_PARTMAN 从基于时间的分区集中删除子表 drop_partition_time(p_parent_table text, p_retention interval DEFAULT NULL, p_keep_table boolean DEFAULT NULL, p_keep_index boolean DEFAULT NULL, p_retention_schema text DEFAULT NULL) RETURNS int 从基于 serial id 的分区集中删除子表 drop_partition_id(p_parent_table text, p_retention bigint DEFAULT NULL, p_keep_table boolean DEFAULT NULL, p_keep_index boolean DEFAULT NULL, p_retention_schema text DEFAULT NULL) RETURNS int 根据添加列的时间（在设置分区之前或之后），将其放在父级上可能会或可能不会从所有子级中删除它。 drop_partition_column(p_parent_table text, p_column text) RETURNS void 49.4.1.4 脚本 创建分区使用小批量的脚本。 partition_data_proc() 撤掉本地分区中使用小批量的脚本。 undo_partition_proc() 使用已有 schema 提取表中数据。 dump_partition.py 清理一个已有分区中的死数据。 vacuum_maintenance.py 在分区集中的子表上更改索引后，重新应用这些索引。 reapply_indexes.py 为表中配置的列重做给定分区集中子表 part_config 约束。 reapply_constraints_proc() 检查分区集中的所有行对于给定列是否唯一。 check_unique_constraints.py 329 第 49 章 KDB_PARTMAN 编译 49.4.1.5 在 KingbaseES 编译之前需要确保 contrib 目录的 makefile 已经添加了 kdb_partman，可以随 KingbaseES 编 译。 示例 49.4.1.6 49.4.1.6.1 创建本地分区 一天一分区 用模版添加主键 CREATE SCHEMA IF NOT EXISTS partman; CREATE EXTENSION kdb_partman SCHEMA partman; CREATE TABLE partman.time_taptest_table (col1 int, col2 text default 'stuff', col3 timestamptz NOT NULL DEFAULT now()) PARTITION BY RANGE (col3); CREATE INDEX ON partman.time_taptest_table (col3); \d+ partman.time_taptest_table Partitioned table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | | | | col2 | text | | | 'stuff'::text | extended | | col3 | timestamp with time zone | | not null | now() | plain | plain | | Partition key: RANGE (col3) Indexes: "time_taptest_table_col3_idx" btree (col3) Number of partitions: 0 CREATE TABLE partman.time_taptest_table_template (LIKE partman.time_taptest_table); ALTER TABLE partman.time_taptest_table_template ADD PRIMARY KEY (col1); \d partman.time_taptest_table_template Table "partman.time_taptest_table_template" Column | Type | Collation | Nullable | Default 330 第 49 章 KDB_PARTMAN --------+--------------------------+-----------+----------+--------col1 | integer | | not null | col2 | text | | col3 | timestamp with time zone | | | not null | Indexes: "time_taptest_table_template_pkey" PRIMARY KEY, btree (col1) SELECT partman.create_parent('partman.time_taptest_table', 'col3', 'native', 'daily', p_template_table := 'partman.time_taptest_table_template'); create_parent --------------t (1 row) \d+ partman.time_taptest_table Partitioned table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | | | | col2 | text | | | 'stuff'::text | extended | | col3 | timestamp with time zone | | not null | now() | plain | plain | | Partition key: RANGE (col3) Indexes: "time_taptest_table_col3_idx" btree (col3) Partitions: partman.time_taptest_table_p2020_10_26 FOR VALUES FROM ('2020-10-26 00:00:00-04') TO ('2020-1027 00:00:00-04'), partman.time_taptest_table_p2020_10_27 FOR VALUES FROM ('2020-10-27 00:00:00-04') TO ('2020-1028 00:00:00-04'), partman.time_taptest_table_p2020_10_28 FOR VALUES FROM ('2020-10-28 00:00:00-04') TO ('2020-1029 00:00:00-04'), partman.time_taptest_table_p2020_10_29 FOR VALUES FROM ('2020-10-29 00:00:00-04') TO ('2020-1030 00:00:00-04'), partman.time_taptest_table_p2020_10_30 FOR VALUES FROM ('2020-10-30 00:00:00-04') TO ('2020-1031 00:00:00-04'), partman.time_taptest_table_p2020_10_31 FOR VALUES FROM ('2020-10-31 00:00:00-04') TO ('2020-1101 00:00:00-04'), partman.time_taptest_table_p2020_11_01 FOR VALUES FROM ('2020-11-01 00:00:00-04') TO ('2020-1102 00:00:00-05'), partman.time_taptest_table_p2020_11_02 FOR VALUES FROM ('2020-11-02 00:00:00-05') TO ('2020-1103 00:00:00-05'), partman.time_taptest_table_p2020_11_03 FOR VALUES FROM ('2020-11-03 00:00:00-05') TO ('2020-1104 00:00:00-05'), 331 第 49 章 KDB_PARTMAN partman.time_taptest_table_default DEFAULT \d+ partman.time_taptest_table_p2020_10_26 Table "partman.time_taptest_table_p2020_10_26" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | not null | col2 | text | | col3 | timestamp with time zone | | plain | | | 'stuff'::text | extended | | | not null | now() | plain | | Partition of: partman.time_taptest_table FOR VALUES FROM ('2020-10-26 00:00:00-04') TO ('2020-10-27 00:00: 00-04') Partition constraint: ((col3 IS NOT NULL) AND (col3 >= '2020-10-26 00:00:00-04'::timestamp with time zone) AND (col3 < '2020-10-27 00:00:00-04'::timestamp with time zone)) Indexes: "time_taptest_table_p2020_10_26_pkey" PRIMARY KEY, btree (col1) "time_taptest_table_p2020_10_26_col3_idx" btree (col3) Access method: heap 49.4.1.6.2 10 个 id 值一个分区 10 个 ID 值一个分区 父表创建子表之后添加主键，子表不能自动添加主键，需要手动添加。 CREATE TABLE partman.id_taptest_table ( col1 bigint , col2 text not null , col3 timestamptz DEFAULT now() , col4 text) PARTITION BY RANGE (col1); CREATE INDEX ON partman.id_taptest_table (col1); \d+ partman.id_taptest_table Partitioned table "partman.id_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | bigint | | col2 | text | col3 col4 | | | not null | | extended | | | timestamp with time zone | | | now() | plain | | | text | | | extended | | | | | plain Partition key: RANGE (col1) Indexes: 332 第 49 章 KDB_PARTMAN "id_taptest_table_col1_idx" btree (col1) Number of partitions: 0 SELECT partman.create_parent('partman.id_taptest_table', 'col1', 'native', '10'); create_parent --------------t (1 row) \d+ partman.id_taptest_table Partitioned table "partman.id_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | bigint | | col2 | text | col3 col4 | | | not null | | extended | | | timestamp with time zone | | | now() | plain | | | text | | | extended | | | | | plain Partition key: RANGE (col1) Indexes: "id_taptest_table_col1_idx" btree (col1) Partitions: partman.id_taptest_table_p0 FOR VALUES FROM ('0') TO ('10'), partman.id_taptest_table_p10 FOR VALUES FROM ('10') TO ('20'), partman.id_taptest_table_p20 FOR VALUES FROM ('20') TO ('30'), partman.id_taptest_table_p30 FOR VALUES FROM ('30') TO ('40'), partman.id_taptest_table_p40 FOR VALUES FROM ('40') TO ('50'), partman.id_taptest_table_default DEFAULT select template_table from partman.part_config where parent_table = 'partman.id_taptest_table'; template_table -----------------------------------------------partman.template_partman_id_taptest_table ALTER TABLE partman.template_partman_id_taptest_table ADD PRIMARY KEY (col2); INSERT INTO partman.id_taptest_table (col1, col2) VALUES (generate_series(1,20), generate_series(1,20):: text||'stuff'::text); CALL partman.run_maintenance(); \d+ partman.id_taptest_table Partitioned table "partman.id_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------- 333 第 49 章 KDB_PARTMAN col1 | bigint | | col2 | text | col3 col4 | | | not null | | extended | | | timestamp with time zone | | | now() | plain | | | text | | | extended | | | | | plain Partition key: RANGE (col1) Indexes: "id_taptest_table_col1_idx" btree (col1) Partitions: partman.id_taptest_table_p0 FOR VALUES FROM ('0') TO ('10'), partman.id_taptest_table_p10 FOR VALUES FROM ('10') TO ('20'), partman.id_taptest_table_p20 FOR VALUES FROM ('20') TO ('30'), partman.id_taptest_table_p30 FOR VALUES FROM ('30') TO ('40'), partman.id_taptest_table_p40 FOR VALUES FROM ('40') TO ('50'), partman.id_taptest_table_p50 FOR VALUES FROM ('50') TO ('60'), partman.id_taptest_table_p60 FOR VALUES FROM ('60') TO ('70'), partman.id_taptest_table_default DEFAULT \d partman.id_taptest_table_p40 Table "partman.id_taptest_table_p40" Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------col1 | bigint | | col2 | text | | not null | col3 | timestamp with time zone | | | now() col4 | text | | | | Partition of: partman.id_taptest_table FOR VALUES FROM ('40') TO ('50') Indexes: "id_taptest_table_p40_col1_idx" btree (col1) \d partman.id_taptest_table_p50 Table "partman.id_taptest_table_p50" Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------col1 | bigint | | col2 | text | | not null | col3 | timestamp with time zone | | | now() col4 | text | | | | Partition of: partman.id_taptest_table FOR VALUES FROM ('50') TO ('60') Indexes: "id_taptest_table_p50_pkey" PRIMARY KEY, btree (col2) "id_taptest_table_p50_col1_idx" btree (col1) \d partman.id_taptest_table_p60 Table "partman.id_taptest_table_p60" Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------- 334 第 49 章 KDB_PARTMAN col1 | bigint | | col2 | text | | not null | col3 | timestamp with time zone | | | now() col4 | text | | | | Partition of: partman.id_taptest_table FOR VALUES FROM ('60') TO ('70') Indexes: "id_taptest_table_p60_pkey" PRIMARY KEY, btree (col2) "id_taptest_table_p60_col1_idx" btree (col1) ALTER TABLE partman.id_taptest_table_p0 ADD PRIMARY KEY (col2); ALTER TABLE partman.id_taptest_table_p10 ADD PRIMARY KEY (col2); ALTER TABLE partman.id_taptest_table_p20 ADD PRIMARY KEY (col2); ALTER TABLE partman.id_taptest_table_p30 ADD PRIMARY KEY (col2); ALTER TABLE partman.id_taptest_table_p40 ADD PRIMARY KEY (col2); 49.4.1.6.3 49.4.1.6.3.1 分区一个已经存在的表 离线分区 数据无法在迁移前后同时访问，优势在于可以分为比分区间隔更小的批次传输，同时只需要较少的重命名次数。 CREATE TABLE public.original_table ( col1 bigint not null , col2 text not null , col3 timestamptz DEFAULT now() , col4 text); CREATE INDEX ON public.original_table (col1); INSERT INTO public.original_table (col1, col2, col3, col4) VALUES (generate_series(1,100000), 'stuff'|| generate_series(1,100000), now(), 'stuff'); ALTER TABLE public.original_table RENAME to old_nonpartitioned_table; CREATE TABLE public.original_table ( col1 bigint not null , col2 text not null , col3 timestamptz DEFAULT now() , col4 text) PARTITION BY RANGE (col1); CREATE INDEX ON public.original_table (col1); SELECT partman.create_parent('public.original_table', 'col1', 'native', '10000'); 335 第 49 章 KDB_PARTMAN \d+ original_table; Partitioned table "public.original_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | bigint | | not null | | plain | | col2 | text | | not null | | extended | | col3 | timestamp with time zone | | | now() | plain | | col4 | text | | | extended | | | Partition key: RANGE (col1) Indexes: "original_table_col1_idx1" btree (col1) Partitions: original_table_p0 FOR VALUES FROM ('0') TO ('10000'), original_table_p10000 FOR VALUES FROM ('10000') TO ('20000'), original_table_p20000 FOR VALUES FROM ('20000') TO ('30000'), original_table_p30000 FOR VALUES FROM ('30000') TO ('40000'), original_table_p40000 FOR VALUES FROM ('40000') TO ('50000'), original_table_default DEFAULT CALL partman.partition_data_id('public.original_table', p_batch_interval := '1000', p_batch_count := 200, p_ source_table := 'public.old_nonpartitioned_table'); partition_data_id -------------------100000 (1 row) VACUUM ANALYZE public.original_table; VACUUM SELECT count(*) FROM old_nonpartitioned_table ; count ------0 (1 row) SELECT count(*) FROM original_table; count -------100000 (1 row) \d+ public.original_table Partitioned table "public.original_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description 336 第 49 章 KDB_PARTMAN --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | bigint | | not null | | plain | | col2 | text | | not null | | extended | | col3 | timestamp with time zone | | | now() | plain | | col4 | text | | | extended | | | Partition key: RANGE (col1) Indexes: "original_table_col1_idx1" btree (col1) Partitions: original_table_p0 FOR VALUES FROM ('0') TO ('10000'), original_table_p10000 FOR VALUES FROM ('10000') TO ('20000'), original_table_p100000 FOR VALUES FROM ('100000') TO ('110000'), original_table_p20000 FOR VALUES FROM ('20000') TO ('30000'), original_table_p30000 FOR VALUES FROM ('30000') TO ('40000'), original_table_p40000 FOR VALUES FROM ('40000') TO ('50000'), original_table_p50000 FOR VALUES FROM ('50000') TO ('60000'), original_table_p60000 FOR VALUES FROM ('60000') TO ('70000'), original_table_p70000 FOR VALUES FROM ('70000') TO ('80000'), original_table_p80000 FOR VALUES FROM ('80000') TO ('90000'), original_table_p90000 FOR VALUES FROM ('90000') TO ('100000'), original_table_default DEFAULT SELECT count(*) FROM original_table_p10000; count ------10000 (1 row) 49.4.1.6.3.2 在线分区 CREATE TABLE public.original_table ( col1 bigint not null PRIMARY KEY GENERATED ALWAYS AS IDENTITY , col2 text not null , col3 timestamptz DEFAULT now() not null , col4 text); CREATE INDEX CONCURRENTLY ON public.original_table (col3); INSERT INTO public.original_table (col2, col3, col4) VALUES ('stuff', generate_series(now() - '1 week':: interval, now(), '5 minutes'::interval), 'stuff'); CREATE TABLE public.new_partitioned_table ( col1 bigint not null GENERATED BY DEFAULT AS IDENTITY , col2 text not null 337 第 49 章 KDB_PARTMAN , col3 timestamptz DEFAULT now() not null , col4 text) PARTITION BY RANGE (col3); CREATE INDEX ON public.new_partitioned_table (col3); CREATE TABLE public.original_table_template (LIKE public.original_table); ALTER TABLE public.original_table_template ADD PRIMARY KEY (col1); select min(col3), max(col3) from original_table; min | max -------------------------------+------------------------------2020-12-02 19:04:08.559646-05 | 2020-12-09 19:04:08.559646-05 (1 row) SELECT partman.create_parent('public.new_partitioned_table', 'col3', 'native', 'daily', p_template_table:= 'public.original_table_template', p_premake := 1, p_start_partition := (CURRENT_TIMESTAMP+'2 days':: interval)::text); default 分区是 partman 自动创建的。 DROP TABLE public.new_partitioned_table_default; SELECT CURRENT_TIMESTAMP; current_timestamp ------------------------------2020-12-09 19:05:15.358796-05 \d+ new_partitioned_table; Partitioned table "public.new_partitioned_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+----------------------------------+----------+-------------+------------col1 | bigint | | not null | generated by default as identity | plain | | | not null | | extended | | not null | now() | plain | | extended | | col2 | text | col3 | timestamp with time zone | | | col4 | text | | | Partition key: RANGE (col3) Indexes: 338 第 49 章 KDB_PARTMAN "new_partitioned_table_col3_idx" btree (col3) Partitions: new_partitioned_table_p2020_12_11 FOR VALUES FROM ('2020-12-11 00:00:00-05') TO ('2020-12-12 00: 00:00-05') 设置 part_config 名字。 UPDATE partman.part_config SET parent_table = 'public.original_table', premake = 4 WHERE parent_table = 'public.new_partitioned_table'; UPDATE 1 迁移自增长将源表设置为 default BEGIN; LOCK TABLE public.original_table IN ACCESS EXCLUSIVE MODE; LOCK TABLE public.new_partitioned_table IN ACCESS EXCLUSIVE MODE; SELECT max(col1) FROM public.original_table; ALTER TABLE public.original_table RENAME TO original_table_default; -- IF using an IDENTITY column ALTER TABLE public.original_table_default ALTER col1 DROP IDENTITY; ALTER TABLE public.new_partitioned_table_p2022_08_04 RENAME TO original_table_p2022_08_04; ALTER TABLE public.new_partitioned_table RENAME TO original_table; -- IF using an IDENTITY column ALTER SEQUENCE public.new_partitioned_table_col1_seq RENAME TO original_table_col1_seq; -- IF using an IDENTITY column ALTER TABLE public.original_table ALTER col1 RESTART WITH 100; ALTER TABLE public.original_table ATTACH PARTITION public.original_table_default DEFAULT; COMMIT; or ROLLBACK; 迁移 CALL partman.partition_data_time('public.original_table', p_batch_count := 200); NOTICE: Batch: 1, Rows moved: 60 NOTICE: Batch: 2, Rows moved: 288 NOTICE: Batch: 3, Rows moved: 288 NOTICE: Batch: 4, Rows moved: 288 339 第 49 章 KDB_PARTMAN NOTICE: Batch: 5, Rows moved: 288 NOTICE: Batch: 6, Rows moved: 288 NOTICE: Batch: 7, Rows moved: 288 NOTICE: Batch: 8, Rows moved: 229 NOTICE: Total rows moved: 2017 NOTICE: Ensure to VACUUM ANALYZE the parent (and source table if used) after partitioning data CALL Time: 8432.725 ms (00:08.433) VACUUM ANALYZE original_table; VACUUM Time: 60.690 ms 设置自增长 ALTER TABLE public.original_table ALTER col1 SET GENERATED ALWAYS; \d+ original_table; Partitioned table "public.original_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+----------------------------------+----------+-------------+------------col1 | bigint | | not null | generated by default as identity | plain | | | not null | | extended | | not null | now() | plain | | extended | | col2 | text | col3 | timestamp with time zone | | | col4 | text | | | Partition key: RANGE (col3) Indexes: "new_partitioned_table_col3_idx" btree (col3) Partitions: original_table_p2020_12_02 FOR VALUES FROM ('2020-12-02 00:00:00-05') TO ('2020-12-03 00:00:0005'), original_table_p2020_12_03 FOR VALUES FROM ('2020-12-03 00:00:00-05') TO ('2020-12-04 00:00:0005'), original_table_p2020_12_04 FOR VALUES FROM ('2020-12-04 00:00:00-05') TO ('2020-12-05 00:00:0005'), original_table_p2020_12_05 FOR VALUES FROM ('2020-12-05 00:00:00-05') TO ('2020-12-06 00:00:0005'), original_table_p2020_12_06 FOR VALUES FROM ('2020-12-06 00:00:00-05') TO ('2020-12-07 00:00:0005'), original_table_p2020_12_07 FOR VALUES FROM ('2020-12-07 00:00:00-05') TO ('2020-12-08 00:00:0005'), 340 第 49 章 KDB_PARTMAN original_table_p2020_12_08 FOR VALUES FROM ('2020-12-08 00:00:00-05') TO ('2020-12-09 00:00:0005'), original_table_p2020_12_09 FOR VALUES FROM ('2020-12-09 00:00:00-05') TO ('2020-12-10 00:00:0005'), original_table_p2020_12_11 FOR VALUES FROM ('2020-12-11 00:00:00-05') TO ('2020-12-12 00:00:0005'), 检查 SELECT partman.run_maintenance('public.original_table'); \d+ original_table; Partitioned table "public.original_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+----------------------------------+----------+-------------+------------col1 | bigint | | not null | generated by default as identity | plain | | | not null | | extended | | not null | now() | plain | | extended | | col2 | text | col3 | timestamp with time zone | | | col4 | text | | | Partition key: RANGE (col3) Indexes: "new_partitioned_table_col3_idx" btree (col3) Partitions: original_table_p2020_12_02 FOR VALUES FROM ('2020-12-02 00:00:00-05') TO ('2020-12-03 00:00:0005'), original_table_p2020_12_03 FOR VALUES FROM ('2020-12-03 00:00:00-05') TO ('2020-12-04 00:00:0005'), original_table_p2020_12_04 FOR VALUES FROM ('2020-12-04 00:00:00-05') TO ('2020-12-05 00:00:0005'), original_table_p2020_12_05 FOR VALUES FROM ('2020-12-05 00:00:00-05') TO ('2020-12-06 00:00:0005'), original_table_p2020_12_06 FOR VALUES FROM ('2020-12-06 00:00:00-05') TO ('2020-12-07 00:00:0005'), original_table_p2020_12_07 FOR VALUES FROM ('2020-12-07 00:00:00-05') TO ('2020-12-08 00:00:0005'), original_table_p2020_12_08 FOR VALUES FROM ('2020-12-08 00:00:00-05') TO ('2020-12-09 00:00:0005'), original_table_p2020_12_09 FOR VALUES FROM ('2020-12-09 00:00:00-05') TO ('2020-12-10 00:00:0005'), original_table_p2020_12_11 FOR VALUES FROM ('2020-12-11 00:00:00-05') TO ('2020-12-12 00:00:0005'), 341 第 49 章 KDB_PARTMAN original_table_p2020_12_12 FOR VALUES FROM ('2020-12-12 00:00:00-05') TO ('2020-12-13 00:00:0005'), original_table_p2020_12_13 FOR VALUES FROM ('2020-12-13 00:00:00-05') TO ('2020-12-14 00:00:0005'), original_table_default DEFAULT 检查 default 中是否存在数据 SELECT * FROM partman.check_default(p_exact_count := true); 填补分区表之间的间隔 SELECT * FROM partman.partition_gap_fill('public.original_table'); partition_gap_fill -------------------1 (1 row) \d+ original_table; Partitioned table "public.original_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+----------------------------------+----------+-------------+------------col1 | bigint | | not null | generated by default as identity | plain | | | not null | | extended | | not null | now() | plain | | extended | | col2 | text | col3 | timestamp with time zone | | | col4 | text | | | Partition key: RANGE (col3) Indexes: "new_partitioned_table_col3_idx" btree (col3) Partitions: original_table_p2020_12_02 FOR VALUES FROM ('2020-12-02 00:00:00-05') TO ('2020-12-03 00:00:0005'), original_table_p2020_12_03 FOR VALUES FROM ('2020-12-03 00:00:00-05') TO ('2020-12-04 00:00:0005'), original_table_p2020_12_04 FOR VALUES FROM ('2020-12-04 00:00:00-05') TO ('2020-12-05 00:00:0005'), original_table_p2020_12_05 FOR VALUES FROM ('2020-12-05 00:00:00-05') TO ('2020-12-06 00:00:0005'), original_table_p2020_12_06 FOR VALUES FROM ('2020-12-06 00:00:00-05') TO ('2020-12-07 00:00:0005'), 342 第 49 章 KDB_PARTMAN original_table_p2020_12_07 FOR VALUES FROM ('2020-12-07 00:00:00-05') TO ('2020-12-08 00:00:0005'), original_table_p2020_12_08 FOR VALUES FROM ('2020-12-08 00:00:00-05') TO ('2020-12-09 00:00:0005'), original_table_p2020_12_09 FOR VALUES FROM ('2020-12-09 00:00:00-05') TO ('2020-12-10 00:00:0005'), original_table_p2020_12_10 FOR VALUES FROM ('2020-12-10 00:00:00-05') TO ('2020-12-11 00:00:0005'), original_table_p2020_12_11 FOR VALUES FROM ('2020-12-11 00:00:00-05') TO ('2020-12-12 00:00:0005'), original_table_p2020_12_12 FOR VALUES FROM ('2020-12-12 00:00:00-05') TO ('2020-12-13 00:00:0005'), original_table_p2020_12_13 FOR VALUES FROM ('2020-12-13 00:00:00-05') TO ('2020-12-14 00:00:0005'), original_table_default DEFAULT 正常使用 INSERT INTO original_table (col2, col3, col4) VALUES ('newstuff', now(), 'newstuff'); INSERT INTO original_table (col2, col3, col4) VALUES ('newstuff', now(), 'newstuff'); SELECT * FROM original_table ORDER BY col1 DESC limit 5; 49.4.1.6.3.3 撤销本地分区 CREATE TABLE public.new_regular_table ( col1 bigint not null GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY , col2 text not null , col3 timestamptz DEFAULT now() not null , col4 text); CREATE INDEX ON public.new_regular_table (col3); 迁移数据 CALL partman.undo_partition('public.original_table', p_batch_interval := '1 hour'::text, p_batch_count := 500, p_target_table := 'public.new_regular_table', p_keep_table := false); NOTICE: Moved 13 row(s) to the target table. Removed 1 partitions. NOTICE: Batch: 1, Partitions undone this batch: 1, Rows undone this batch: 13 NOTICE: Moved 13 row(s) to the target table. Removed 0 partitions. NOTICE: Batch: 2, Partitions undone this batch: 0, Rows undone this batch: 13 NOTICE: Moved 13 row(s) to the target table. Removed 0 partitions. NOTICE: Batch: 3, Partitions undone this batch: 0, Rows undone this batch: 13 [...] 343 第 49 章 KDB_PARTMAN NOTICE: Batch: 160, Partitions undone this batch: 0, Rows undone this batch: 13 NOTICE: Moved 5 row(s) to the target table. Removed 1 partitions. NOTICE: Batch: 161, Partitions undone this batch: 1, Rows undone this batch: 5 NOTICE: Moved 0 row(s) to the target table. Removed 4 partitions. NOTICE: Total partitions undone: 13, Total rows moved: 2017 NOTICE: Ensure to VACUUM ANALYZE the old parent & target table after undo has finished CALL Time: 163465.195 ms (02:43.465) VACUUM ANALYZE original_table; VACUUM Time: 20.706 ms VACUUM ANALYZE new_regular_table; VACUUM Time: 20.375 ms 设置新表自增长 SELECT max(col1) FROM public.original_table; ALTER TABLE original_table RENAME TO old_partitioned_table; ALTER SEQUENCE original_table_col1_seq RENAME TO old_partitioned_table_col1_seq; ALTER TABLE new_regular_table RENAME TO original_table; ALTER SEQUENCE new_regular_table_col1_seq RENAME TO original_table_col1_seq; ALTER TABLE public.original_table ALTER col1 RESTART WITH 100; ALTER TABLE public.original_table ALTER col1 SET GENERATED ALWAYS; 可以正常使用 INSERT INTO original_table (col2, col3, col4) VALUES ('newstuff', now(), 'newstuff'); INSERT INTO original_table (col2, col3, col4) VALUES ('newstuff', now(), 'newstuff'); SELECT * FROM original_table ORDER BY col1 DESC limit 2; 49.4.1.6.4 49.4.1.6.4.1 设置触发分区 每天一个分区 \d partman.time_taptest_table Table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------col1 | integer | | not null | col2 | text | | col3 | timestamp with time zone | | | not null | now() 344 第 49 章 KDB_PARTMAN Indexes: "time_taptest_table_pkey" PRIMARY KEY, btree (col1) SELECT partman.create_parent('partman.time_taptest_table', 'col3', p_type := 'native', p_interval := 'daily '); create_parent --------------t (1 row) \d+ partman.time_taptest_table Table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | integer | | not null | | plain | | col2 | text | | | extended | | col3 | timestamp with time zone | | plain | | | not null | now() | Indexes: "time_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: time_taptest_table_part_trig BEFORE INSERT ON partman.time_taptest_table FOR EACH ROW EXECUTE PROCEDURE partman.time_taptest_table_part_trig_func() Child tables: partman.time_taptest_table_p2017_03_23, partman.time_taptest_table_p2017_03_24, partman.time_taptest_table_p2017_03_25, partman.time_taptest_table_p2017_03_26, partman.time_taptest_table_p2017_03_27, partman.time_taptest_table_p2017_03_28, partman.time_taptest_table_p2017_03_29, partman.time_taptest_table_p2017_03_30, partman.time_taptest_table_p2017_03_31 \sf partman.time_taptest_table_part_trig_func 在 contrib/kdb_partman/sql 目录下，找到 sql 文件，添加自定义函数。 CREATE TABLE partman.time_taptest_table( col1 int not null , col2 text , col3 timestamptz NOT NULL DEFAULT now()) PARTITION BY RANGE (col3); CREATE INDEX ON partman.time_taptest_table (col3); SELECT partman.create_parent('partman.time_taptest_table', 'col3', p_type := 'native', p_interval := 'daily '); CREATE OR REPLACE FUNCTION partman.time_taptest_table_part_trig_func() RETURNS trigger 345 第 49 章 KDB_PARTMAN LANGUAGE plpgsql AS $function$ DECLARE v_count int; v_partition_name text; v_partition_timestamp timestamptz; BEGIN IF TG_OP = 'INSERT' THEN v_partition_timestamp := date_trunc('day', NEW.col3); IF NEW.col3 >= '2022-07-30 00:00:00-04' AND NEW.col3 < '2022-07-31 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_07_30 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-07-31 00:00:00-04' AND NEW.col3 < '2022-08-01 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_07_31 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-01 00:00:00-04' AND NEW.col3 < '2022-08-02 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_01 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-02 00:00:00-04' AND NEW.col3 < '2022-08-03 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_02 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-03 00:00:00-04' AND NEW.col3 < '2022-08-04 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_03 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-04 00:00:00-04' AND NEW.col3 < '2022-08-05 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_04 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-05 00:00:00-04' AND NEW.col3 < '2022-08-06 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_05 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-06 00:00:00-04' AND NEW.col3 < '2022-08-07 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_06 VALUES (NEW.*); ELSIF NEW.col3 >= '2022-08-07 00:00:00-04' AND NEW.col3 < '2022-08-08 00:00:00-04' THEN INSERT INTO partman.time_taptest_table_p2022_08_07 VALUES (NEW.*); ELSE v_partition_name := partman.check_name_length('time_taptest_table', to_char(v_partition_ timestamp, 'YYYY_MM_DD'), TRUE); SELECT count(*) INTO v_count FROM sys_catalog.sys_tables WHERE schemaname = 'partman'::name AND tablename = v_partition_name::name; IF v_count > 0 THEN EXECUTE format('INSERT INTO %I.%I VALUES($1.*) ', 'partman', v_partition_name) USING NEW; ELSE RETURN NEW; END IF; END IF; END IF; RETURN NULL; END $function$ 346 第 49 章 KDB_PARTMAN 49.4.1.6.4.2 10 个数一个分区 \d partman.id_taptest_table Table "partman.id_taptest_table" Column | Type | Modifiers --------+--------------------------+-------------------------------col1 | integer | not null col2 | text | not null default 'stuff'::text col3 | timestamp with time zone | default now() Indexes: "id_taptest_table_pkey" PRIMARY KEY, btree (col1) SELECT partman.create_parent('partman.id_taptest_table', 'col1', 'native', '10'); create_parent --------------t (1 row) \d+ partman.id_taptest_table Table "partman.id_taptest_table" Column | Type | Modifiers | Storage | Stats target | Description --------+--------------------------+--------------------------------+----------+--------------+------------col1 | integer | not null | plain | | col2 | text | not null default 'stuff'::text | extended | | col3 | timestamp with time zone | default now() | plain | | Indexes: "id_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: id_taptest_table_part_trig BEFORE INSERT ON partman.id_taptest_table FOR EACH ROW EXECUTE PROCEDURE partman.id_taptest_table_part_trig_func() Child tables: partman.id_taptest_table_p0, partman.id_taptest_table_p10, partman.id_taptest_table_p20, partman.id_taptest_table_p30, partman.id_taptest_table_p40 \sf partman.id_taptest_table_part_trig_func CREATE OR REPLACE FUNCTION partman.id_taptest_table_part_trig_func() RETURNS trigger LANGUAGE plpgsql AS $function$ DECLARE v_count int; 347 第 49 章 KDB_PARTMAN v_current_partition_id bigint; v_current_partition_name text; v_id_position int; v_last_partition text := 'id_taptest_table_p40'; v_next_partition_id bigint; v_next_partition_name text; v_partition_created boolean; BEGIN IF TG_OP = 'INSERT' THEN IF NEW.col1 >= 0 AND NEW.col1 < 10 THEN INSERT INTO partman.id_taptest_table_p0 VALUES (NEW.*) ; ELSIF NEW.col1 >= 10 AND NEW.col1 < 20 THEN INSERT INTO partman.id_taptest_table_p10 VALUES (NEW.*) ; ELSIF NEW.col1 >= 20 AND NEW.col1 < 30 THEN INSERT INTO partman.id_taptest_table_p20 VALUES (NEW.*) ; ELSIF NEW.col1 >= 30 AND NEW.col1 < 40 THEN INSERT INTO partman.id_taptest_table_p30 VALUES (NEW.*) ; ELSIF NEW.col1 >= 40 AND NEW.col1 < 50 THEN INSERT INTO partman.id_taptest_table_p40 VALUES (NEW.*) ; ELSE v_current_partition_id := NEW.col1 - (NEW.col1 % 10); v_current_partition_name := partman.check_name_length('id_taptest_table', v_current_partition_ id::text, TRUE); SELECT count(*) INTO v_count FROM sys_catalog.sys_tables WHERE schemaname = 'partman'::name AND tablename = v_current_partition_name::n ame; IF v_count > 0 THEN EXECUTE format('INSERT INTO %I.%I VALUES($1.*) ', 'partman', v_current_partition_name) USING NEW; ELSE RETURN NEW; END IF; END IF; END IF; RETURN NULL; END $function$ INSERT INTO partman.id_taptest_table(col1,col2) VALUES(1,'insert1'); INSERT 0 0 Time: 4.876 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+------------------------------1 | insert1 | 2017-03-27 14:23:02.769999-04 (1 row) 348 第 49 章 KDB_PARTMAN INSERT INTO partman.id_taptest_table(col1,col2) VALUES(2,'insert2'); INSERT 0 0 Time: 1.583 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+------------------------------2 | insert2 | 2017-03-27 14:23:02.769999-04 (1 row) 49.4.1.6.4.3 10 个数一个分区创建的空表使用 upsert 丢弃行冲突 Uses same example table as above SELECT partman.create_parent('partman.id_taptest_table', 'col1', 'native', '10', p_upsert := 'ON CONFLICT (col1) DO NOTHING'); create_parent --------------t (1 row) \d+ partman.id_taptest_table Table "partman.id_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | not null | | | col2 | text | | not null | 'stuff'::text | extended | | col3 | timestamp with time zone | | | | now() | plain | plain | Indexes: "id_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: id_taptest_table_part_trig BEFORE INSERT ON partman.id_taptest_table FOR EACH ROW EXECUTE PROCEDURE partman.id_taptest_table_part_trig_func() Child tables: partman.id_taptest_table_p0, partman.id_taptest_table_p10, partman.id_taptest_table_p20, partman.id_taptest_table_p30, partman.id_taptest_table_p40 创建插入函数，如果有冲突不会插入冲突行 349 第 49 章 KDB_PARTMAN \sf partman.id_taptest_table_part_trig_func CREATE OR REPLACE FUNCTION partman.id_taptest_table_part_trig_func() RETURNS trigger LANGUAGE plpgsql AS $function$ DECLARE v_count int; v_current_partition_id bigint; v_current_partition_name text; v_id_position int; v_last_partition text := 'id_taptest_table_p40'; v_next_partition_id bigint; v_next_partition_name text; v_partition_created boolean; BEGIN IF TG_OP = 'INSERT' THEN IF NEW.col1 >= 0 AND NEW.col1 < 10 THEN INSERT INTO partman.id_taptest_table_p0 VALUES (NEW.*) ON CONFLICT (col1) DO NOTHING; ELSIF NEW.col1 >= 10 AND NEW.col1 < 20 THEN INSERT INTO partman.id_taptest_table_p10 VALUES (NEW.*) ON CONFLICT (col1) DO NOTHING; ELSIF NEW.col1 >= 20 AND NEW.col1 < 30 THEN INSERT INTO partman.id_taptest_table_p20 VALUES (NEW.*) ON CONFLICT (col1) DO NOTHING; ELSIF NEW.col1 >= 30 AND NEW.col1 < 40 THEN INSERT INTO partman.id_taptest_table_p30 VALUES (NEW.*) ON CONFLICT (col1) DO NOTHING; ELSIF NEW.col1 >= 40 AND NEW.col1 < 50 THEN INSERT INTO partman.id_taptest_table_p40 VALUES (NEW.*) ON CONFLICT (col1) DO NOTHING; ELSE v_current_partition_id := NEW.col1 - (NEW.col1 % 10); v_current_partition_name := partman.check_name_length('id_taptest_table', v_current_partition_ id::text, TRUE); SELECT count(*) INTO v_count FROM sys_catalog.sys_tables WHERE schemaname = 'partman'::name AND tablename = v_current_partition_name::n ame; IF v_count > 0 THEN EXECUTE format('INSERT INTO %I.%I VALUES($1.*) ON CONFLICT (col1) DO NOTHING', 'partman', v_ current_partition_name) USING NEW; ELSE RETURN NEW; END IF; END IF; END IF; RETURN NULL; END $function$ 插入一个行 350 第 49 章 KDB_PARTMAN INSERT INTO partman.id_taptest_table(col1,col2) VALUES(1,'insert1'); INSERT 0 0 Time: 4.876 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+------------------------------1 | insert1 | 2017-03-27 14:23:02.769999-04 (1 row) 插入冲突行，结果为保留原有行 INSERT INTO partman.id_taptest_table(col1,col2) VALUES(1,'insert2'); INSERT 0 0 Time: 1.583 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+------------------------------1 | insert1 | 2017-03-27 14:23:02.769999-04 (1 row) 49.4.1.6.4.4 用 upsert 更新行冲突 Uses same example table as above SELECT partman.create_parent('partman.id_taptest_table', 'col1', 'partman', '10', p_upsert := 'ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3'); create_parent --------------t (1 row) \d+ partman.id_taptest_table Table "partman.id_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | not null | | | col2 | text | | not null | 'stuff'::text | extended | | col3 | timestamp with time zone | | | | now() | plain | plain | Indexes: "id_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: id_taptest_table_part_trig BEFORE INSERT ON partman.id_taptest_table FOR EACH ROW EXECUTE PROCEDURE partman.id_taptest_table_part_trig_func() 351 第 49 章 KDB_PARTMAN Child tables: partman.id_taptest_table_p0, partman.id_taptest_table_p10, partman.id_taptest_table_p20, partman.id_taptest_table_p30, partman.id_taptest_table_p40 创建插入函数，如果有冲突行则更新原有行 \sf partman.id_taptest_table_part_trig_func CREATE OR REPLACE FUNCTION partman.id_taptest_table_part_trig_func() RETURNS trigger LANGUAGE plpgsql AS $function$ DECLARE v_count int; v_current_partition_id bigint; v_current_partition_name text; v_id_position int; v_last_partition text := 'id_taptest_table_p40'; v_next_partition_id bigint; v_next_partition_name text; v_partition_created boolean; BEGIN IF TG_OP = 'INSERT' THEN IF NEW.col1 >= 0 AND NEW.col1 < 10 THEN INSERT INTO partman.id_taptest_table_p0 VALUES (NEW.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3; ELSIF NEW.col1 >= 10 AND NEW.col1 < 20 THEN INSERT INTO partman.id_taptest_table_p10 VALUES (NEW.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3; ELSIF NEW.col1 >= 20 AND NEW.col1 < 30 THEN INSERT INTO partman.id_taptest_table_p20 VALUES (NEW.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3; ELSIF NEW.col1 >= 30 AND NEW.col1 < 40 THEN INSERT INTO partman.id_taptest_table_p30 VALUES (NEW.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3; ELSIF NEW.col1 >= 40 AND NEW.col1 < 50 THEN INSERT INTO partman.id_taptest_table_p40 VALUES (NEW.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3; ELSE v_current_partition_id := NEW.col1 - (NEW.col1 % 10); v_current_partition_name := partman.check_name_length('id_taptest_table', v_current_partition_ id::text, TRUE); SELECT count(*) INTO v_count FROM sys_catalog.sys_tables WHERE schemaname = 'partman'::name AND tablename = v_current_partition_name::n 352 第 49 章 KDB_PARTMAN ame; IF v_count > 0 THEN EXECUTE format('INSERT INTO %I.%I VALUES($1.*) ON CONFLICT (col1) DO UPDATE SET col2=EXCLUDED.col2, col3=EXCLUDED.col3', 'partman ', v_current_partition_name) USING NEW; ELSE RETURN NEW; END IF; END IF; END IF; RETURN NULL; END $function$ 插入行 INSERT INTO partman.id_taptest_table(col1,col2) VALUES(1,'insert1'); INSERT 0 0 Time: 6.012 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+-----------------------------1 | insert1 | 2017-03-27 14:32:26.59552-04 (1 row) 插入冲突行，结果为更新原有行 INSERT INTO partman.id_taptest_table(col1,col2) VALUES(1,'insert2'); INSERT 0 0 Time: 4.235 ms SELECT * FROM partman.id_taptest_table; col1 | col2 | col3 ------+---------+------------------------------1 | insert2 | 2017-03-27 14:33:00.949928-04 (1 row) 49.4.1.6.5 49.4.1.6.5.1 创建多级子分区 时间多级子分区 kdb_partman 仅在某些版本支持对本机分区集进行自分区，目前最新的版本 kdb_partman4.4.0 不支持此功能。 以下过程是先创建表，后插入数据 \d partman.time_taptest_table Table "partman.time_taptest_table" 353 第 49 章 KDB_PARTMAN Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------col1 | integer | | not null | col2 | text | | col3 | timestamp with time zone | | | not null | now() Indexes: "time_taptest_table_pkey" PRIMARY KEY, btree (col1) SELECT partman.create_parent('partman.time_taptest_table', 'col3', 'partman', 'yearly', p_premake := 2); create_parent --------------t (1 row) SELECT partman.create_sub_parent('partman.time_taptest_table', 'col3', 'partman', 'monthly', p_premake := 2); create_sub_parent ------------------t (1 row) SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename ----------------------------------time_taptest_table time_taptest_table_p2015 time_taptest_table_p2015_p2015_01 time_taptest_table_p2016 time_taptest_table_p2016_p2016_01 time_taptest_table_p2017 time_taptest_table_p2017_p2017_01 time_taptest_table_p2017_p2017_02 time_taptest_table_p2017_p2017_03 time_taptest_table_p2017_p2017_04 time_taptest_table_p2017_p2017_05 time_taptest_table_p2018 time_taptest_table_p2018_p2018_01 time_taptest_table_p2019 time_taptest_table_p2019_p2019_01 (15 rows) SELECT partman.create_sub_parent('partman.time_taptest_table_p2015', 'col3', 'partman', 'daily', p_premake : = 2); SELECT partman.create_sub_parent('partman.time_taptest_table_p2016', 'col3', 'partman', 'daily', p_premake : = 2); 354 第 49 章 KDB_PARTMAN SELECT partman.create_sub_parent('partman.time_taptest_table_p2017', 'col3', 'partman', 'daily', p_premake : = 2); SELECT partman.create_sub_parent('partman.time_taptest_table_p2018', 'col3', 'partman', 'daily', p_premake : = 2); SELECT partman.create_sub_parent('partman.time_taptest_table_p2019', 'col3', 'partman', 'daily', p_premake : = 2); SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename ----------------------------------------------time_taptest_table time_taptest_table_p2015 time_taptest_table_p2015_p2015_01 time_taptest_table_p2015_p2015_01_p2015_01_01 time_taptest_table_p2016 time_taptest_table_p2016_p2016_01 time_taptest_table_p2016_p2016_01_p2016_01_01 time_taptest_table_p2017 time_taptest_table_p2017_p2017_01 time_taptest_table_p2017_p2017_01_p2017_01_01 time_taptest_table_p2017_p2017_02 time_taptest_table_p2017_p2017_02_p2017_02_01 time_taptest_table_p2017_p2017_03 time_taptest_table_p2017_p2017_03_p2017_03_25 time_taptest_table_p2017_p2017_03_p2017_03_26 time_taptest_table_p2017_p2017_03_p2017_03_27 time_taptest_table_p2017_p2017_03_p2017_03_28 time_taptest_table_p2017_p2017_03_p2017_03_29 time_taptest_table_p2017_p2017_04 time_taptest_table_p2017_p2017_04_p2017_04_01 time_taptest_table_p2017_p2017_05 time_taptest_table_p2017_p2017_05_p2017_05_01 time_taptest_table_p2018 time_taptest_table_p2018_p2018_01 time_taptest_table_p2018_p2018_01_p2018_01_01 time_taptest_table_p2019 time_taptest_table_p2019_p2019_01 time_taptest_table_p2019_p2019_01_p2019_01_01 (28 rows) 数值间隔的多级子分区 以下过程是表中已经存在数据 \d partman.id_taptest_table Table "partman.id_taptest_table" 355 第 49 章 KDB_PARTMAN Column | Type | Collation | Nullable | Default --------+--------------------------+-----------+----------+--------------col1 | integer | | not null | col2 | text | | not null | 'stuff'::text col3 | timestamp with time zone | | | now() Indexes: "id_taptest_table_pkey" PRIMARY KEY, btree (col1) SELECT count(*) FROM partman.id_taptest_table ; count -------100000 (1 row) SELECT min(col1), max(col1) FROM partman.id_taptest_table ; min | max -----+-------1 | 100000 (1 row) SELECT partman.create_parent('partman.id_taptest_table', 'col1', 'partman', '10000', p_jobmon := false, p_ premake := 2); --------------t (1 row) SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename -------------------------id_taptest_table id_taptest_table_p100000 id_taptest_table_p110000 id_taptest_table_p120000 id_taptest_table_p80000 id_taptest_table_p90000 (6 rows) $ python partition_data.py -c host=localhost -p partman.id_taptest_table -t id -i 100 Attempting to turn off autovacuum for partition set... ... Success! Rows moved: 100 Rows moved: 100 ... 356 第 49 章 KDB_PARTMAN Rows moved: 99 ... Rows moved: 100 Rows moved: 1 Total rows moved: 100000 Running vacuum analyze on parent table... Attempting to reset autovacuum for old parent table and all child tables... ... Success! SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename -------------------------id_taptest_table id_taptest_table_p0 id_taptest_table_p10000 id_taptest_table_p100000 id_taptest_table_p110000 id_taptest_table_p120000 id_taptest_table_p20000 id_taptest_table_p30000 id_taptest_table_p40000 id_taptest_table_p50000 id_taptest_table_p60000 id_taptest_table_p70000 id_taptest_table_p80000 id_taptest_table_p90000 (14 rows) SELECT partman.create_sub_parent('partman.id_taptest_table', 'col1', 'partman', '1000', p_jobmon := false, p_premake := 2); create_sub_parent ------------------t (1 row) SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename ---------------------------------id_taptest_table id_taptest_table_p0 id_taptest_table_p0_p0 id_taptest_table_p10000 id_taptest_table_p100000 id_taptest_table_p100000_p100000 357 第 49 章 KDB_PARTMAN id_taptest_table_p100000_p101000 id_taptest_table_p100000_p102000 id_taptest_table_p10000_p10000 id_taptest_table_p110000 id_taptest_table_p110000_p110000 id_taptest_table_p120000 id_taptest_table_p120000_p120000 id_taptest_table_p20000 id_taptest_table_p20000_p20000 id_taptest_table_p30000 id_taptest_table_p30000_p30000 id_taptest_table_p40000 id_taptest_table_p40000_p40000 id_taptest_table_p50000 id_taptest_table_p50000_p50000 id_taptest_table_p60000 id_taptest_table_p60000_p60000 id_taptest_table_p70000 id_taptest_table_p70000_p70000 id_taptest_table_p80000 id_taptest_table_p80000_p80000 id_taptest_table_p90000 id_taptest_table_p90000_p98000 id_taptest_table_p90000_p99000 (30 rows) 此时，数据还在父表中 SELECT * FROM partman.check_parent() ORDER BY 1; parent_table | count ---------------------------------------+------partman.id_taptest_table_p0 | partman.id_taptest_table_p10000 | 10000 partman.id_taptest_table_p100000 | 9999 1 partman.id_taptest_table_p20000 | 10000 partman.id_taptest_table_p30000 | 10000 partman.id_taptest_table_p40000 | 10000 partman.id_taptest_table_p50000 | 10000 partman.id_taptest_table_p60000 | 10000 partman.id_taptest_table_p70000 | 10000 partman.id_taptest_table_p80000 | 10000 partman.id_taptest_table_p90000 | 10000 (11 rows) 将数据移到子表 358 第 49 章 KDB_PARTMAN python partition_data.py -c host=localhost -p partman.id_taptest_table_p0 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p10000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p20000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p30000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p40000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p50000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p60000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p70000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p80000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p90000 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p100000 -t id -i 100 SELECT * FROM partman.check_parent() ORDER BY 1; parent_table | count --------------+------(0 rows) SELECT tablename FROM sys_tables WHERE schemaname = 'partman' ORDER BY tablename; tablename ---------------------------------id_taptest_table id_taptest_table_p0 id_taptest_table_p0_p0 id_taptest_table_p0_p1000 id_taptest_table_p0_p2000 id_taptest_table_p0_p3000 id_taptest_table_p0_p4000 id_taptest_table_p0_p5000 id_taptest_table_p0_p6000 id_taptest_table_p0_p7000 id_taptest_table_p0_p8000 id_taptest_table_p0_p9000 id_taptest_table_p10000 id_taptest_table_p100000 id_taptest_table_p100000_p100000 id_taptest_table_p100000_p101000 id_taptest_table_p100000_p102000 id_taptest_table_p10000_p10000 id_taptest_table_p10000_p11000 id_taptest_table_p10000_p12000 id_taptest_table_p10000_p13000 id_taptest_table_p10000_p14000 id_taptest_table_p10000_p15000 id_taptest_table_p10000_p16000 359 第 49 章 KDB_PARTMAN id_taptest_table_p10000_p17000 id_taptest_table_p10000_p18000 id_taptest_table_p10000_p19000 id_taptest_table_p110000 id_taptest_table_p110000_p110000 id_taptest_table_p120000 id_taptest_table_p120000_p120000 id_taptest_table_p20000 id_taptest_table_p20000_p20000 id_taptest_table_p20000_p21000 id_taptest_table_p20000_p22000 id_taptest_table_p20000_p23000 id_taptest_table_p20000_p24000 id_taptest_table_p20000_p25000 id_taptest_table_p20000_p26000 id_taptest_table_p20000_p27000 id_taptest_table_p20000_p28000 id_taptest_table_p20000_p29000 id_taptest_table_p30000 id_taptest_table_p30000_p30000 id_taptest_table_p30000_p31000 id_taptest_table_p30000_p32000 id_taptest_table_p30000_p33000 id_taptest_table_p30000_p34000 id_taptest_table_p30000_p35000 id_taptest_table_p30000_p36000 id_taptest_table_p30000_p37000 id_taptest_table_p30000_p38000 id_taptest_table_p30000_p39000 id_taptest_table_p40000 id_taptest_table_p40000_p40000 id_taptest_table_p40000_p41000 id_taptest_table_p40000_p42000 id_taptest_table_p40000_p43000 id_taptest_table_p40000_p44000 id_taptest_table_p40000_p45000 id_taptest_table_p40000_p46000 id_taptest_table_p40000_p47000 id_taptest_table_p40000_p48000 id_taptest_table_p40000_p49000 id_taptest_table_p50000 id_taptest_table_p50000_p50000 id_taptest_table_p50000_p51000 id_taptest_table_p50000_p52000 id_taptest_table_p50000_p53000 360 第 49 章 KDB_PARTMAN id_taptest_table_p50000_p54000 id_taptest_table_p50000_p55000 id_taptest_table_p50000_p56000 id_taptest_table_p50000_p57000 id_taptest_table_p50000_p58000 id_taptest_table_p50000_p59000 id_taptest_table_p60000 id_taptest_table_p60000_p60000 id_taptest_table_p60000_p61000 id_taptest_table_p60000_p62000 id_taptest_table_p60000_p63000 id_taptest_table_p60000_p64000 id_taptest_table_p60000_p65000 id_taptest_table_p60000_p66000 id_taptest_table_p60000_p67000 id_taptest_table_p60000_p68000 id_taptest_table_p60000_p69000 id_taptest_table_p70000 id_taptest_table_p70000_p70000 id_taptest_table_p70000_p71000 id_taptest_table_p70000_p72000 id_taptest_table_p70000_p73000 id_taptest_table_p70000_p74000 id_taptest_table_p70000_p75000 id_taptest_table_p70000_p76000 id_taptest_table_p70000_p77000 id_taptest_table_p70000_p78000 id_taptest_table_p70000_p79000 id_taptest_table_p80000 id_taptest_table_p80000_p80000 id_taptest_table_p80000_p81000 id_taptest_table_p80000_p82000 id_taptest_table_p80000_p83000 id_taptest_table_p80000_p84000 id_taptest_table_p80000_p85000 id_taptest_table_p80000_p86000 id_taptest_table_p80000_p87000 id_taptest_table_p80000_p88000 id_taptest_table_p80000_p89000 id_taptest_table_p90000 id_taptest_table_p90000_p90000 id_taptest_table_p90000_p91000 id_taptest_table_p90000_p92000 id_taptest_table_p90000_p93000 id_taptest_table_p90000_p94000 361 第 49 章 KDB_PARTMAN id_taptest_table_p90000_p95000 id_taptest_table_p90000_p96000 id_taptest_table_p90000_p97000 id_taptest_table_p90000_p98000 id_taptest_table_p90000_p99000 (119 rows) 继续缩小粒度 SELECT partman.create_sub_parent('partman.id_taptest_table_p0', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p10000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p20000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p30000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p40000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p50000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p60000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p70000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p80000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p90000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT partman.create_sub_parent('partman.id_taptest_table_p100000', 'col1', 'partman', '100', p_jobmon := false, p_premake := 2); SELECT tablename FROM sys_tables WHERE schemaname = 'partman' order by tablename; tablename -----------------------------------------id_taptest_table id_taptest_table_p0 id_taptest_table_p0_p0 id_taptest_table_p0_p0_p0 id_taptest_table_p0_p1000 id_taptest_table_p0_p1000_p1000 id_taptest_table_p0_p2000 id_taptest_table_p0_p2000_p2000 ... id_taptest_table_p10000 362 第 49 章 KDB_PARTMAN id_taptest_table_p100000 id_taptest_table_p100000_p100000 id_taptest_table_p100000_p100000_p100000 id_taptest_table_p100000_p100000_p100100 id_taptest_table_p100000_p100000_p100200 id_taptest_table_p100000_p101000 id_taptest_table_p100000_p101000_p101000 id_taptest_table_p100000_p102000 id_taptest_table_p100000_p102000_p102000 id_taptest_table_p10000_p10000 id_taptest_table_p10000_p10000_p10000 id_taptest_table_p10000_p11000 id_taptest_table_p10000_p11000_p11000 ... id_taptest_table_p90000_p98000 id_taptest_table_p90000_p98000_p98000 id_taptest_table_p90000_p99000 id_taptest_table_p90000_p99000_p99800 id_taptest_table_p90000_p99000_p99900 (225 rows) SELECT 'python partition_data.py -c host=localhost -p '||parent_table||' -t id -i 100' FROM partman.part_ config ORDER BY parent_table; ?column? --------------------------------------------------------------------------------------------------------python partition_data.py -c host=localhost -p partman.id_taptest_table -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p0 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p0_p0 -t id -i 100 python partition_data.py -c host=localhost -p partman.id_taptest_table_p0_p1000 -t id -i 100 ... SELECT tablename FROM sys_tables WHERE schemaname = 'partman' order by tablename; tablename ----------------------------------------id_taptest_table id_taptest_table_p0 id_taptest_table_p0_p0 id_taptest_table_p0_p0_p0 id_taptest_table_p0_p0_p100 id_taptest_table_p0_p0_p200 id_taptest_table_p0_p0_p300 id_taptest_table_p0_p0_p400 id_taptest_table_p0_p0_p500 363 第 49 章 KDB_PARTMAN id_taptest_table_p0_p0_p600 id_taptest_table_p0_p0_p700 id_taptest_table_p0_p0_p800 id_taptest_table_p0_p0_p900 id_taptest_table_p0_p1000 id_taptest_table_p0_p1000_p1000 id_taptest_table_p0_p1000_p1100 id_taptest_table_p0_p1000_p1200 id_taptest_table_p0_p1000_p1300 id_taptest_table_p0_p1000_p1400 id_taptest_table_p0_p1000_p1500 id_taptest_table_p0_p1000_p1600 id_taptest_table_p0_p1000_p1700 id_taptest_table_p0_p1000_p1800 id_taptest_table_p0_p1000_p1900 id_taptest_table_p0_p2000 id_taptest_table_p0_p2000_p2000 id_taptest_table_p0_p2000_p2100 ... id_taptest_table_p90000_p98000_p98800 id_taptest_table_p90000_p98000_p98900 id_taptest_table_p90000_p99000 id_taptest_table_p90000_p99000_p99000 id_taptest_table_p90000_p99000_p99100 id_taptest_table_p90000_p99000_p99200 id_taptest_table_p90000_p99000_p99300 id_taptest_table_p90000_p99000_p99400 id_taptest_table_p90000_p99000_p99500 id_taptest_table_p90000_p99000_p99600 id_taptest_table_p90000_p99000_p99700 id_taptest_table_p90000_p99000_p99800 id_taptest_table_p90000_p99000_p99900 (1124 rows) 49.4.1.6.5.2 从触发分区迁移到本地 test/test-time-daily.sql 创建触发区分 \d+ partman.time_taptest_table Table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | integer | | not null | | plain | | col2 | text | | | extended | | col3 | timestamp with time zone | | plain | | | not null | now() | 364 第 49 章 KDB_PARTMAN Indexes: "time_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: time_taptest_table_part_trig BEFORE INSERT ON partman.time_taptest_table FOR EACH ROW EXECUTE FUNCTION partman.time_taptest_table_part_trig_func() Child tables: partman.time_taptest_table_p2020_01_27, partman.time_taptest_table_p2020_01_28, partman.time_taptest_table_p2020_01_29, partman.time_taptest_table_p2020_01_30, partman.time_taptest_table_p2020_01_31, partman.time_taptest_table_p2020_02_01, partman.time_taptest_table_p2020_02_02, partman.time_taptest_table_p2020_02_03, partman.time_taptest_table_p2020_02_04, partman.time_taptest_table_p2020_02_05, partman.time_taptest_table_p2020_02_06, partman.time_taptest_table_p2020_02_07, partman.time_taptest_table_p2020_02_08, partman.time_taptest_table_p2020_02_09, partman.time_taptest_table_p2020_02_10, partman.time_taptest_table_p2020_02_11, partman.time_taptest_table_p2020_02_12 Access method: heap 关闭触发行为 UPDATE partman.part_config SET automatic_maintenance = 'off' WHERE parent_table = 'partman.time_taptest_ table'; UPDATE partman.part_config_sub SET sub_automatic_maintenance = 'off' WHERE sub_parent = 'partman.time_ taptest_table'; UPDATE partman.part_config_sub SET sub_automatic_maintenance = 'off' WHERE sub_parent = 'partman.time_ taptest_table_p2019_12_08'; [...] 创建本地分区 CREATE TABLE partman.time_taptest_table_native (col1 int, col2 text default 'stuff', col3 timestamptz NOT NULL DEFAULT now()) PARTITION BY RANGE (col3); CREATE INDEX ON partman.time_taptest_table_native (col3); \dt partman.time_taptest_table List of relations 365 第 49 章 KDB_PARTMAN Schema | Name | Type | Owner --------------+--------------------+-------+--------------partman | time_taptest_table | table | partman_owner (1 row) \dp+ partman.time_taptest_table Access privileges Schema | Name | Type | Access privileges | Column privileges | Policies --------------+--------------------+-------+-------------------------------------+-------------------+--------partman | time_taptest_table | table | partman_owner=arwdDxt/partman_owner+| | | | | partman_basic=arwd/partman_owner +| | | | | testing=r/partman_owner | | (1 row) ALTER TABLE partman.time_taptest_table_native OWNER TO partman_owner; GRANT SELECT, INSERT, UPDATE, DELETE ON partman.time_taptest_table_native TO partman_basic; GRANT SELECT ON partman.time_taptest_table_native TO testing; 数据迁移 BEGIN; LOCK TABLE partman.time_taptest_table IN ACCESS EXCLUSIVE MODE NOWAIT; SELECT 'ALTER TABLE '||inhrelid::regclass||' NO INHERIT '||inhparent::regclass||';' FROM sys_inherits WHERE inhparent::regclass = 'partman.time_taptest_table'::regclass; ?column? ----------------------------------------------------------------------------------------------------ALTER TABLE partman.time_taptest_table_p2019_12_08 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_09 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_10 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_11 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_12 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_13 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_14 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_15 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_16 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_17 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_18 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_19 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_20 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_21 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_22 NO INHERIT partman.time_taptest_table; 366 第 49 章 KDB_PARTMAN ALTER TABLE partman.time_taptest_table_p2019_12_23 NO INHERIT partman.time_taptest_table; ALTER TABLE partman.time_taptest_table_p2019_12_24 NO INHERIT partman.time_taptest_table; SELECT ( SELECT 'ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION '||x.child_tablename||' FOR VALUES FROM ('||quote_literal(y.child_start_time)||') TO ('||quote_literal(y.child_end_time)||');' FROM partman.show_partition_info(x.child_tablename, p_parent_table := 'partman.time_taptest_table') y ) FROM (SELECT inhrelid::regclass::text AS child_tablename FROM sys_inherits WHERE inhparent::regclass = 'partman.time_taptest_table'::regclass) x; ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_01_27 FOR VALUES FROM ('2020-01-27 00:00:00-05') TO ('2020-01-28 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_01_28 FOR VALUES FROM ('2020-01-28 00:00:00-05') TO ('2020-01-29 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_01_29 FOR VALUES FROM ('2020-01-29 00:00:00-05') TO ('2020-01-30 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_01_30 FOR VALUES FROM ('2020-01-30 00:00:00-05') TO ('2020-01-31 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_01_31 FOR VALUES FROM ('2020-01-31 00:00:00-05') TO ('2020-02-01 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_01 FOR VALUES FROM ('2020-02-01 00:00:00-05') TO ('2020-02-02 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_02 FOR VALUES FROM ('2020-02-02 00:00:00-05') TO ('2020-02-03 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_03 FOR VALUES FROM ('2020-02-03 00:00:00-05') TO ('2020-02-04 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_04 FOR VALUES FROM ('2020-02-04 00:00:00-05') TO ('2020-02-05 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_05 FOR VALUES FROM ('2020-02-05 00:00:00-05') TO ('2020-02-06 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_06 FOR VALUES FROM ('2020-02-06 00:00:00-05') TO ('2020-02-07 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_07 FOR VALUES FROM ('2020-02-07 00:00:00-05') TO ('2020-02-08 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_08 FOR VALUES FROM ('2020-02-08 00:00:00-05') TO ('2020-02-09 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_09 FOR VALUES FROM ('2020-02-09 00:00:00-05') TO ('2020-02-10 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_10 FOR VALUES FROM ('2020-02-10 00:00:00-05') TO ('2020-02-11 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_11 FOR VALUES FROM ('2020-02-11 00:00:00-05') TO ('2020-02-12 00:00:00-05'); ALTER TABLE partman.time_taptest_table_native ATTACH PARTITION partman.time_taptest_table_p2020_02_12 FOR VALUES FROM ('2020-02-12 00:00:00-05') TO ('2020-02-13 00:00:00-05'); 367 第 49 章 KDB_PARTMAN \d+ partman.time_taptest_table Table "partman.time_taptest_table" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------+----------+--------------+------------col1 | integer | | not null | | plain | | col2 | text | | | extended | | col3 | timestamp with time zone | | plain | | | not null | now() | Indexes: "time_taptest_table_pkey" PRIMARY KEY, btree (col1) Triggers: time_taptest_table_part_trig BEFORE INSERT ON partman.time_taptest_table FOR EACH ROW EXECUTE FUNCTION partman.time_taptest_table_part_trig_func() Access method: heap \d+ partman.time_taptest_table_native Partitioned table "partman.time_taptest_table_native" Column | Type | Collation | Nullable | Default | Storage | Stats target | Description --------+--------------------------+-----------+----------+---------------+----------+--------------+-----------col1 | integer | | | | | col2 | text | | | 'stuff'::text | extended | | col3 | timestamp with time zone | | not null | now() | plain | plain | | Partition key: RANGE (col3) Indexes: "time_taptest_table_native_col3_idx" btree (col3) Partitions: partman.time_taptest_table_p2020_01_27 FOR VALUES FROM ('2020-01-27 00:00:00-05') TO ('2020-0128 00:00:00-05'), partman.time_taptest_table_p2020_01_28 FOR VALUES FROM ('2020-01-28 00:00:00-05') TO ('2020-0129 00:00:00-05'), partman.time_taptest_table_p2020_01_29 FOR VALUES FROM ('2020-01-29 00:00:00-05') TO ('2020-0130 00:00:00-05'), partman.time_taptest_table_p2020_01_30 FOR VALUES FROM ('2020-01-30 00:00:00-05') TO ('2020-0131 00:00:00-05'), partman.time_taptest_table_p2020_01_31 FOR VALUES FROM ('2020-01-31 00:00:00-05') TO ('2020-0201 00:00:00-05'), partman.time_taptest_table_p2020_02_01 FOR VALUES FROM ('2020-02-01 00:00:00-05') TO ('2020-0202 00:00:00-05'), partman.time_taptest_table_p2020_02_02 FOR VALUES FROM ('2020-02-02 00:00:00-05') TO ('2020-0203 00:00:00-05'), partman.time_taptest_table_p2020_02_03 FOR VALUES FROM ('2020-02-03 00:00:00-05') TO ('2020-0204 00:00:00-05'), partman.time_taptest_table_p2020_02_04 FOR VALUES FROM ('2020-02-04 00:00:00-05') TO ('2020-0205 00:00:00-05'), 368 第 49 章 KDB_PARTMAN partman.time_taptest_table_p2020_02_05 FOR VALUES FROM ('2020-02-05 00:00:00-05') TO ('2020-0206 00:00:00-05'), partman.time_taptest_table_p2020_02_06 FOR VALUES FROM ('2020-02-06 00:00:00-05') TO ('2020-0207 00:00:00-05'), partman.time_taptest_table_p2020_02_07 FOR VALUES FROM ('2020-02-07 00:00:00-05') TO ('2020-0208 00:00:00-05'), partman.time_taptest_table_p2020_02_08 FOR VALUES FROM ('2020-02-08 00:00:00-05') TO ('2020-0209 00:00:00-05'), partman.time_taptest_table_p2020_02_09 FOR VALUES FROM ('2020-02-09 00:00:00-05') TO ('2020-0210 00:00:00-05'), partman.time_taptest_table_p2020_02_10 FOR VALUES FROM ('2020-02-10 00:00:00-05') TO ('2020-0211 00:00:00-05'), partman.time_taptest_table_p2020_02_11 FOR VALUES FROM ('2020-02-11 00:00:00-05') TO ('2020-0212 00:00:00-05'), partman.time_taptest_table_p2020_02_12 FOR VALUES FROM ('2020-02-12 00:00:00-05') TO ('2020-0213 00:00:00-05') ALTER TABLE partman.time_taptest_table RENAME TO time_taptest_table_old; ALTER TABLE partman.time_taptest_table_native RENAME TO time_taptest_table; CREATE TABLE partman.time_taptest_table_default (LIKE partman.time_taptest_table INCLUDING ALL); ALTER TABLE partman.time_taptest_table ATTACH PARTITION partman.time_taptest_table_default DEFAULT; CREATE TABLE partman.partman_time_taptest_table (LIKE partman.time_taptest_table); ALTER TABLE partman.partman_time_taptest_table OWNER TO partman_owner; ALTER TABLE partman.partman_time_taptest_table ADD PRIMARY KEY (col1); UPDATE partman.part_config SET partition_type = 'native', template_table = 'partman.partman_time_taptest_ table' WHERE parent_table = 'partman.time_taptest_table'; COMMIT; 49.4.1.6.6 迁移已有数据表到 partman 1. 禁用 run_maintenance() 2. 将被迁移表设置为不可写 3. 将表改为和时间相关的名字，如果分区集的命名方式与所包含的相关数据不同，或者根本不相关，则必须改为 根据控制列中的最小值进行重命名。 369 第 49 章 KDB_PARTMAN -- 将表改为和时间相关的名字 select 'ALTER TABLE '||n.nspname||'.'||c.relname||' RENAME TO '||substring(c.relname from 1 for 4)||'_p'|| to_char(to_timestamp(substring(c.relname from 5), 'YYYYMMDD'), 'IYYY')||'w'||to_char(to_ timestamp(substring(c.relname from 5), 'YYYYMMDD'), 'IW')||';' from sys_inherits h join sys_class c on h.inhrelid = c.oid join sys_namespace n on c.relnamespace = n.oid where h.inhparent::regclass = 'tracking.hits'::regclass order by c.relname; -- 命名方式与所包含的相关数据不同 insert into tracking.hits_aa values (1, generate_series('2016-01-03 01:00:00'::timestamptz, '2016-01-09 23: 00:00'::timestamptz, '1 hour'::interval)); insert into tracking.hits_bb values (2, generate_series('2016-01-10 01:00:00'::timestamptz, '2016-01-16 23: 00:00'::timestamptz, '1 hour'::interval)); insert into tracking.hits_cc values (3, generate_series('2016-01-17 01:00:00'::timestamptz, '2016-01-23 23: 00:00'::timestamptz, '1 hour'::interval)); DO $rename$ DECLARE v_min_val bigint; v_row record; v_sql text; BEGIN -- Adjust your parent table name in the for loop query FOR v_row IN SELECT n.nspname AS child_schema, c.relname AS child_table FROM sys_inherits h JOIN sys_class c ON h.inhrelid = c.oid JOIN sys_namespace n ON c.relnamespace = n.oid WHERE h.inhparent::regclass = 'tracking.hits'::regclass ORDER BY c.relname LOOP -- Substitute your control column's name here in the min() function v_sql := format('SELECT min(id) FROM %I.%I', v_row.child_schema, v_row.child_table); EXECUTE v_sql INTO v_min_val; -- Adjust the numerical value after the % to account for whatever your partitioning interval is. v_min_val := v_min_val - (v_min_val % 1000); -- Build the sql statement to rename the child table v_sql := format('ALTER TABLE %I.%I RENAME TO %I' , v_row.child_schema 370 第 49 章 KDB_PARTMAN , v_row.child_table , substring(v_row.child_table from 1 for 4)||'_p'||v_min_val::text); -- I just have it outputing the ALTER statement for review. If you'd like this code to actually run it, uncomment the EXECUTE below. RAISE NOTICE '%', v_sql; -- EXECUTE v_sql; END LOOP; END $rename$; 4. 迁移 BEGIN; DROP TRIGGER myoldtrigger ON tracking.hits; SELECT partman.create_parent('tracking.hits', 'start', 'partman', 'weekly'); COMMIT; \d+ tracking.hits Table "tracking.hits" Column | Type | Modifiers | Storage | Stats target | Description --------+-----------------------------+-----------+---------+--------------+------------id | integer | not null | plain | | start | timestamp without time zone | not null | plain | | Triggers: hits_part_trig BEFORE INSERT ON tracking.hits FOR EACH ROW EXECUTE PROCEDURE tracking.hits_part_trig_func() Child tables: tracking.hits_p2015w53, tracking.hits_p2016w01, tracking.hits_p2016w02, tracking.hits_p2016w03, tracking.hits_p2016w04, tracking.hits_p2016w05, tracking.hits_p2016w06, tracking.hits_p2016w07, tracking.hits_p2016w08, tracking.hits_p2016w09 49.5 插件 kdb_partman 卸载方法 用户在不需要使用 kdb_partman 插件的时候，可以使用 DROP EXTENSION 命令将 kdb_partman 插件卸载。 371 第 49 章 KDB_PARTMAN 示例： drop extension kdb_partman; 49.6 插件 kdb_partman 升级方法 kdb_partman 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 372 第 50 章 KDB_PROTECT 50章 kdb_protect 第 50.1 插件 kdb_protect 简介 kdb_protect 插件是 KingbaseES 的一个扩展插件。主要功能是提供保护 database、schema、table 等逻辑对象 不被 DROP 的能力。 • 插件名为 kdb_protect • 插件版本 v1.0 50.2 插件 kdb_protect 加载方式 使用时需要在命令行执行 create extension kdb_protect; 示例： create extension kdb_protect; 50.3 插件 kdb_protect 的参数配置 无需配置任何参数。 50.4 插件 kdb_protect 的使用方法 加载插件 kdb_protect 后，按照如下方式使用相应功能。 373 第 50 章 KDB_PROTECT 50.4.1 kdb_protect.protect_add 添加被保护对象到保护表中。 语法 kdb_protect.protect_add(text name, char type); kdb_protect.protect_add(text name, char type, bool iscascade); 参数 name：被保护对象的名字 type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) iscascade：是否级联。只对 db、schema 有效。 返回值 成功返回’t’，失败返回’f’ 或报错 示例 select kdb_protect.protect_add('table1', 't'); select kdb_protect.protect_add('table1', 't', true); 50.4.2 kdb_protect.protect_add_oid 添加被保护对象到保护表中。 语法 kdb_protect.protect_add_oid(Oid objid, char type); kdb_protect.protect_add_oid(Oid objid, char type, bool iscascade); 参数 objid：被保护对象的 oid type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) iscascade：是否级联。只对 db、schema 有效。 返回值 成功返回’t’，失败返回’f’ 或报错 示例 374 第 50 章 KDB_PROTECT select kdb_protect.protect_add_oid(16394, 't'); select kdb_protect.protect_add_oid(16394, 't', true); 50.4.3 kdb_protect.protect_remove 从保护表中删除被保护对象。 语法 kdb_protect.protect_remove(text name, char type); kdb_protect.protect_remove(text name, char type, bool iscascade); 参数 name：被保护对象的名字 type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) iscascade：是否级联。只对 db、schema 有效。 返回值 成功返回’t’，失败返回’f’ 或报错 示例 select kdb_protect.protect_remove('table1.mysch', 't'); select kdb_protect.protect_remove('table1.mysch', 't', true); 50.4.4 kdb_protect.protect_remove_oid 从保护表中删除被保护对象。 语法 kdb_protect.protect_remove_oid(Oid objid, char type); 参数 objid：被保护对象的 oid type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) 返回值 成功返回’t’，失败返回’f’ 或报错 375 第 50 章 KDB_PROTECT 示例 select kdb_protect.protect_remove_oid(16385, 't'); 50.4.5 kdb_protect.protect_remove_all 删除保护表中所有被保护对象。 语法 kdb_protect.protect_remove_all(); 参数 无 返回值 成功返回’t’，失败返回’f’ 或报错 示例 select kdb_protect.protect_remove_all(); 50.4.6 kdb_protect.protect_show() 显示所有被保护对象。 语法 kdb_protect.protect_show(); 参数 无 返回值 成功返回保护的对象信息，失败报错 示例 select * from kdb_protect.protect_show(); 50.4.7 kdb_protect.protect_show_detail() 显示所有被保护对象（更详细信息）。 376 第 50 章 KDB_PROTECT 语法 kdb_protect.protect_show_detail(); 参数 无 返回值 成功返回保护的对象信息，失败报错 示例 select * from kdb_protect.protect_show_detail(); 50.4.8 kdb_protect.protect_show_one() 显示一个被保护对象。 语法 kdb_protect.protect_show_one(text name, char type); 参数 objid：被保护对象的 oid type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) 返回值 成功返回保护的对象信息，失败报错 示例 select * from kdb_protect.protect_show_one('table1', 't'); 50.4.9 kdb_protect.protect_show_one_detail(text name, char type) 显示一个被保护对象（更详细信息）。 语法 kdb_protect.protect_show_one_detail(text name, char type); 377 第 50 章 KDB_PROTECT 参数 objid：被保护对象的 oid type：被保护对象的类型，如下： ’d’ --database(数据库) ’s’ --schema(模式) ’t’ --table(表/分区表) ’v’ --view/materialized view(视图/物化视图) ’f’ --function/procedure(函数/存储过程) 返回值 成功返回保护的对象信息，失败报错 示例 select * from kdb_protect.protect_show_one_detail('table1', 't'); 50.5 插件 kdb_protect 卸载方法 卸载时 drop extension kdb_protect 即可。 示例： drop extension kdb_protect; 50.6 插件 kdb_protect 升级方法 kdb_protect 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 378 第 51 章 KDB_RAW 51章 kdb_raw 第 51.1 插件 kdb_raw 简介 kdb_raw 定义了一套对于 raw 数据类型的操作。支持 utl_raw、utl_enode 和 utl_i18n 内置包。参见《PL/SQL 系统包和类型参考手册》中的 UTL_RAW 包，UTL_ENCODE 包，UTL_I18N 包。 • 插件名为 kdb_raw • 插件版本 V1.0 51.2 插件 kdb_raw 加载方式 KingbaseES 默认不加载 kdb_raw 扩展插件，请使用以下命令加载插件和创建扩展： CREATE EXTENSION kdb_raw; 51.3 插件 kdb_raw 的参数配置 无需配置任何参数 51.4 插件 kdb_raw 的使用方法 51.4.1 UTL_ENCODE 包 UTL_ENCODE 系统包提供对于 RAW 数据类型的编码转换操作。 379 第 51 章 KDB_RAW 51.4.1.1 BASE64_DECODE 函数 BASE64_DECODE 函数读取基于 base64 编码的 raw 并将其解码为原始 raw 值并返回。 语法 UTL_ENCODE.BASE64_DECODE(r IN RAW) RETURN RAW; 参数说明 r 待解码的 raw 字节串。 示例 DROP FUNCTION IF EXISTS test0050(); \set SQLTERM / CREATE OR REPLACE FUNCTION test0050() RETURNS RAW AS DECLARE v1 RAW := '\x404142434445'; DECLARE v2 RAW; BEGIN v2 = UTL_ENCODE.BASE64_ENCODE(v1); v2 = UTL_ENCODE.BASE64_DECODE(v2); RETURN v2; END; / CREATE FUNCTION \set SQLTERM ; SELECT * FROM test0050(); test0050 ---------------404142434445 (1 行记录) 51.4.1.2 BASE64_ENCODE 函数 BASE64_ENCODE 函数将 RAW 的二进制形式编码成为 BASE 64 的元素并以 RAW 的形式返回，返回 RAW。 语法 UTL_ENCODE.BASE64_ENCODE(r IN RAW) RETURN RAW; 参数说明 380 第 51 章 KDB_RAW r 待转换的 raw 字节串。 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0050() RETURNS RAW AS DECLARE v1 RAW := '\x404142434445'; DECLARE v2 RAW; BEGIN v2 = UTL_ENCODE.BASE64_ENCODE(v1); RETURN v2; END; / CREATE FUNCTION \set SQLTERM ; SELECT * FROM test0050(); test0050 -------------------5145464351305246 (1 行记录) 51.4.1.3 QUOTED_PRINTABLE_DECODE 函数 QUOTED_PRINTABLE_DECODE 函数把输入的 QUOTED PRINTABLE 格式字节串解码为原始的 RAW 字 节串。 语法 UTL_ENCODE.UOTED_PRINTABLE_DECODE(r IN RAW) RETURN RAW; 参数说明 r 待转换的 raw 字节串。 示例 SELECT UTL_RAW.CAST_TO_VARCHAR2(UTL_ENCODE.QUOTED_PRINTABLE_DECODE('6161613D304161')) FROM dual; cast_to_varchar2 ------------------ 381 第 51 章 KDB_RAW aaa + a 51.4.1.4 QUOTED_PRINTABLE_ENCODE 函数 QUOTED_PRINTABLE_ENCODE 函数把输入的 RAW 字节串编码成 QUOTED PRINTABLE 格式字节串。 语法 UTL_ENCODE.QUOTED_PRINTABLE_ENCODE(r IN RAW) RETURN RAW; 参数说明 r 待转换的 raw 字节串。 示例 SELECT UTL_ENCODE.QUOTED_PRINTABLE_ENCODE('09') FROM dual; quoted_printable_encode ------------------------3D3039 51.4.2 UTL_RAW 包 UTL_RAW 系统包提供定义了一套对于 RAW 数据类型的操作。 51.4.2.1 BIT_AND 函数 BIT_AND 函数按位做与运算，返回 RAW。 语法 UTL_RAW.BIT_AND ( r1 IN RAW, r2 IN RAW ) RETURN RAW 参数说明 r1 RAW 类型，参与运算的第一个参数值。 r2 382 第 51 章 KDB_RAW RAW 类型，参与运算的第二个参数值。 使用说明 1. 输入参数有一个为 NULL 则返回 NULL； 2. 长度较长的参数，和长度较短参数等长部分按位做与运算，超出部分直接附加前述计算结果后。 返回值 RAW 类型，按位与运算的结果。 示例 SELECT UTL_RAW.BIT_AND(HEXTORAW('0103'),HEXTORAW('02')) FROM DUAL; bit_and --------0003 51.4.2.2 BIT_COMPLEMENT 函数 BIT_COMPLEMENT 函数按位做补运算，返回 RAW。 语法 UTL_RAW.BIT_COMPLEMENT ( r IN RAW ) RETURN RAW 参数说明 r RAW 类型，参与运算的参数值。 使用说明 输入参数为 NULL 则返回 NULL。 返回值 RAW 类型，按位做补运算的结果。 示例 SELECT UTL_RAW.BIT_COMPLEMENT(HEXTORAW('01')) FROM DUAL; bit_complement ---------------FE 383 第 51 章 KDB_RAW 51.4.2.3 BIT_OR 函数 BIT_OR 函数按位做或运算，返回 RAW。 语法 UTL_RAW.BIT_OR ( r1 IN RAW, r2 IN RAW ) RETURN RAW 参数说明 r1 RAW 类型，参与运算的第一个参数值。 r2 RAW 类型，参与运算的第二个参数值。 使用说明 1. 输入参数有一个为 NULL 则返回 NULL； 2. 长度较长的参数，和长度较短参数等长部分按位做或运算，超出部分直接附加前述计算结果后。 返回值 RAW 类型，按位做或运算的结果。 示例 SELECT UTL_RAW.BIT_OR(HEXTORAW('01'),HEXTORAW('0308')) FROM DUAL; bit_or -------0308 51.4.2.4 BIT_XOR 函数 BIT_XOR 函数按位做异或运算，返回 RAW。 语法 UTL_RAW.BIT_XOR ( r1 IN RAW, r2 IN RAW ) RETURN RAW 参数说明 r1 RAW 类型，参与运算的第一个参数值。 384 第 51 章 KDB_RAW r2 RAW 类型，参与运算的第二个参数值。 使用说明 1. 输入参数有一个为 NULL 则返回 NULL； 2. 长度较长的参数，和长度较短参数等长部分按位做异或运算，超出部分直接附加前述计算结果后。 返回值 RAW 类型，按位异或运算的结果。 示例 SELECT UTL_RAW.BIT_XOR(HEXTORAW('01'),HEXTORAW('0304')) FROM DUAL; bit_xor --------0204 51.4.2.5 CAST_FROM_BINARY_DOUBLE 函数 CAST_FROM_BINARY_DOUBLE 函数将 DOUBLE 类型数字转换成 RAW 类型。 语法 UTL_RAW.CAST_FROM_BINARY_DOUBLE( n IN DOUBLE [ , endianess IN INTEGER ] ) RETURN RAW 参数说明 n DOUBLE 类型，待转换的 DOUBLE 类型。 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN。缺省值为 1。非此 3 种值报错。 使用说明 1. 输入是 NULL 返回 NULL； 2. 返回值 8 字节，显示 16 位 16 进制字符。 返回值 RAW 类型，RAW 表示 IEEE 754 double-precision 编码格式。 示例 385 第 51 章 KDB_RAW SELECT UTL_RAW.CAST_FROM_BINARY_DOUBLE(2.33) FROM DUAL; cast_from_binary_double ------------------------4002A3D70A3D70A4 51.4.2.6 CAST_FROM_BINARY_FLOAT 函数 CAST_FROM_BINARY_FLOAT 函数将 FLOAT 类型数字转换成 RAW 类型。 语法 UTL_RAW.CAST_FROM_BINARY_FLOAT( n IN FLOAT [ , endianess IN INTEGER ] ) RETURN RAW 参数说明 n FLOAT 类型，待转换的 FLOAT 类型。 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN。缺省值为 1。非此 3 种值报错。 使用说明 1. 输入是 NULL 返回 NULL； 2. 返回值 4 字节，显示 8 位 16 进制字符。 返回值 RAW 类型，RAW 表示 IEEE 754 single-precision 编码格式。 示例 SELECT UTL_RAW.CAST_FROM_BINARY_FLOAT(2.33) FROM DUAL; cast_from_binary_float ------------------------40151EB8 51.4.2.7 CAST_FROM_BINARY_INTEGER 函数 CAST_FROM_BINARY_INTEGER 函数将整数类型按内部字节表示转换成 RAW 类型。 语法 386 第 51 章 KDB_RAW UTL_RAW.CAST_FROM_BINARY_INTEGER ( n IN INTEGER [, endianess IN INTEGER] ) RETURN RAW 参数说明 n INTEGER 类型，待转换的整数值。 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN。缺省值为 1。非此 3 种值报错。 使用说明 1. 输入是 NULL 返回 NULL； 2. 最小值-2147483648，小于最小值报错； 3. 最大值 2147483647，大于最大值报错； 4. 返回值 4 字节，显示 8 位 16 进制字符。 返回值 RAW 类型 示例 SELECT UTL_RAW.CAST_FROM_BINARY_INTEGER(100,1) FROM DUAL; cast_from_binary_integer -------------------------00000064 51.4.2.8 CAST_FROM_NUMBER 函数 CAST_FROM_NUMBER 函数将 NUMBER 类型数字转换成 RAW 类型。 语法 UTL_RAW.CAST_FROM_NUMBER( n IN NUMBER ) RETURN RAW 参数说明 n NUMBER 类型，待转换的 NUMBER 值。 使用说明 387 第 51 章 KDB_RAW 1. 输入是 NULL 返回 NULL； 2. 正数范围 1e-130 到 1e126，不包括 1e126，大于等于 1e126 报错，小于 1e-130 都返回 80； 3. 负数范围-1e126 到-1e-130，不包括-1e126，小于等于-1e126，大于-1e-130 都返回 80； 4. 返回值 1-22 字节，显示 2-44 位 16 进制字符。 返回值 RAW 类型 示例 SELECT UTL_RAW.CAST_FROM_NUMBER(2.33) FROM DUAL; cast_from_number ------------------------C10322 51.4.2.9 CAST_TO_BINARY_DOUBLE 函数 CAST_TO_BINARY_DOUBLE 函数将 RAW 字节串为对应表示的 DOUBLE 值。 语法 UTL_RAW.CAST_TO_BINARY_DOUBLE ( r IN RAW [, endianess IN INTEGER] ) RETURN DOUBLE 参数说明 r RAW 类型，待转换的 RAW 值。r 表示 IEEE 754 double-precision 编码格式。 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN。缺省值为 1。非此 3 种值报错。 使用说明 1. 如果 RAW 超过 8 字节，只取前 8 个字节； 2. 如果 RAW 不足 8 个字节报错； 3. 如果结果是-0，则返回 +0；如果结果是 NaN，返回 NaN。 返回值 DOUBLE 类型 示例 388 第 51 章 KDB_RAW SELECT UTL_RAW.CAST_TO_BINARY_DOUBLE(hextoraw('4002A3D70A3D70A4')) FROM DUAL; cast_to_binary_double -------------------------2.33 51.4.2.10 CAST_TO_BINARY_FLOAT 函数 CAST_TO_BINARY_FLOAT 函数将 RAW 字节串为对应表示的 FLOAT 值。 语法 UTL_RAW.CAST_TO_BINARY_FLOAT ( r IN RAW [, endianess IN INTEGER] ) RETURN FLOAT 参数说明 r RAW 类型，待转换的 RAW 值。r 表示 IEEE 754 single-precision 编码格式。 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN。缺省值为 1。非此 3 种值报错。 使用说明 1. 如果 RAW 超过 4 字节，只取前 4 个字节； 2. 如果 RAW 不足 4 个字节报错； 3. 如果结果是-0，则返回 +0；如果结果是 NaN，返回 NaN。 返回值 FLOAT 类型 示例 SELECT UTL_RAW.CAST_TO_BINARY_FLOAT(hextoraw('40151EB8')) FROM DUAL; cast_to_binary_float -------------------------2.33 51.4.2.11 CAST_TO_BINARY_INTEGER 函数 CAST_TO_BINARY_INTEGER 函数转换 RAW 值字节序列对应的整数。 389 第 51 章 KDB_RAW 语法 UTL_RAW.CAST_TO_BINARY_INTEGER ( n IN RAW [,endianess IN INTEGER] ) RETURN RAW 参数说明 n RAW 类型，待转换的 RAW 值 endianess INTEGER 类型，值表示类型：1 代表 BIG_ENDIAN，2 代表 LITTLE_ENDIAN，3 代表当前机器的 ENDIAN，缺省值 1。非此 3 种值报错。 使用说明 输入 RAW 超过 8 位 16 进制字符： 1. endianess=3，返回 0； 2. endian=1,2，如果 RAW 输出字符串长度是奇数，保留最高 1 位字符计算值，如果 RAW 输出字符串长度是偶 数，保留最高 2 位字符计算值。 返回值 RAW 类型 示例 SELECT UTL_RAW.CAST_TO_BINARY_INTEGER('6400',1) FROM DUAL; cast_to_binary_integer -----------------------25600 51.4.2.12 CAST_TO_NUMBER 函数 CAST_TO_NUMBER 函数将 RAW 类型数字转换成 NUMBER 类型。 语法 UTL_RAW.CAST_TO_BINARY_INTEGER ( r IN RAW [, endianess IN INTEGER] ) RETURN INTEGER 参数说明 r RAW 类型，待转换的 RAW 值。 390 第 51 章 KDB_RAW 使用说明 1. 输入是 NULL 返回 NULL； 2. 如果输入字节串不符合编码规则或不是数字，则报错。 返回值 INTEGER 类型 示例 SELECT UTL_RAW.CAST_TO_NUMBER(hextoraw('C10322')) FROM DUAL; cast_to_number -------------------------2.33 51.4.2.13 CAST_TO_RAW 函数 CAST_TO_RAW 函数将 VARCHAR2 类型转换为 RAW 类型，返回 RAW 类型。 语法 UTL_RAW.CAST_TO_VARCHAR2(v IN VARCHAR2) RETURN RAW; 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0040() RETURNS RAW AS DECLARE v1 VARCHAR2 := 'abcd'; DECLARE v3 RAW; BEGIN v3 = UTL_RAW.CAST_TO_RAW(v1); RETURN v3; END; / \set SQLTERM ; SELECT * FROM test0040(); test0040 -----------61626364 (1 row) \set SQLTERM / CREATE OR REPLACE FUNCTION test0040() RETURNS RAW AS 391 第 51 章 KDB_RAW DECLARE v1 VARCHAR2 := 'abcd'; DECLARE v3 RAW; BEGIN v3 = UTL_RAW.CAST_TO_RAW(v1); RETURN v3; END; / \set SQLTERM ; SELECT * FROM test0040(); test0040 -----------61626364 (1 行记录) 51.4.2.14 CAST_TO_VARCHAR2 函数 CAST_TO_VARCHAR2 函数将 RAW 类型转换为 VARCHAR2 类型，返回 VARCHAR2 类型。 语法 UTL_RAW.CAST_TO_VARCHAR2(r IN RAW) RETURN VARCHAR2; 示例 -- test UTL_RAW.CAST_TO_VARCHAR2(null) \set SQLTERM / CREATE OR REPLACE FUNCTION test0022() RETURNS BOOLEAN AS DECLARE v1 RAW ; DECLARE v3 VARCHAR2; BEGIN v3 = UTL_RAW.CAST_TO_VARCHAR2(v1); RETURN (v3 IS NULL); END; / \set SQLTERM ; SELECT * FROM test0022(); test0022 ---------t (1 行记录) 392 第 51 章 KDB_RAW 51.4.2.15 COMPARE 函数 COMPARE 函数比较两个 RAW 值，返回第一个不相等的字节位置。 语法 UTL_RAW.COMPARE ( r1 IN RAW, r2 IN RAW [, pad IN RAW] ) RETURN INTEGER 参数说明 r1 RAW 类型，待比较的第一个输入 RAW 值。 r2 RAW 类型，待比较的第二个输入 RAW 值。 pad RAW 类型，填充的字节，多个字节取第一个使用，默认为 00 。 使用说明 1. 两个输入 RAW 可以为 NULL 或长度 0； 2. 长度较短的输入 RAW 值拼接 pad 指定的第一个字节，默认为 00； 3. 如果两个输入 RAW 都为 NULL 或完全一样返回 0；否则返回第一个不相等字节的位置，从 1 开始计数。 返回值 integer 类型，第一个不相等的字节位置。 示例 SELECT UTL_RAW.COMPARE('ABCD', 'AB', 'CD') FROM DUAL; compare --------0 SELECT UTL_RAW.COMPARE(HEXTORAW('ABA'), HEXTORAW('ABC')) FROM DUAL; compare --------2 393 第 51 章 KDB_RAW 51.4.2.16 CONCAT 函数 CONCAT 函数连接最多 12 个 RAW 类型，并返回拼接后的结果。 语法 UTL_RAW.CONCAT ( r1 IN RAW [, r2 IN RAW] [, r3 IN RAW] [, r4 IN RAW] [, r5 IN RAW] [, r6 IN RAW] [, r7 IN RAW] [, r8 IN RAW] [, r9 IN RAW] [, r10 IN RAW] [, r11 IN RAW] [, r12 IN RAW] ) RETURN RAW 参数说明 r1-r12 RAW 类型，待拼接的输入 RAW 值。 使用说明 1. 输入 RAW 参数最多支持 12 个； 2. 结果长度超过 RAW 允许最大长度将报错。 返回值 RAW 类型，拼接后的结果值。 示例 SELECT UTL_RAW.CONCAT('AB','CD','EF',NULL,'1234') FROM DUAL; concat -----------ABCDEF1234 51.4.2.17 CONVER 函数 CONVER 函数把源字符集下的字节数据转换为等价的目标字符集下的字节数据。 语法 394 第 51 章 KDB_RAW UTL_RAW.CONVERT(r IN RAW, to_charset IN VARCHAR2, from_charset IN VARCHAR2） RETURN RAW 参数说明 r RAW 类型。 to_charset 目标字符集名称。 from_charset 源字符集名称。 使用说明 把 from_set 字符集下 r 代表的字符串转换成 to_set 字符集下的字节串。如果转换后的字节串超出 raw 允许的 最大长度，则自动截取到最大长度。 1. 字符集名称以 kes 支持的为主，可使用 oracle 和 kes 支持的字符集名称，不区分大小写，不支持的字符集报 错； 2. 结果超过 raw 允许的最大长度自动截断到最大长度； 3. 支持的 oracle 字符集名称及映射的 kes 字符集名称如下： {"th8tisascii", "ascii"}, {"ja16euc", "eucjp"}, {"ja16euctilde", "eucjp"}, {"zht32euc", "euctw"},{"al32utf8", "utf8"}, {"we8iso8859p1", "latin1"}, {"ee8iso8859p2", "latin2"}, {"se8iso8859p3", "latin3"},{"nee8iso8859p4", "latin4"}, {"we8iso8859p9", "latin5"}, {"ne8iso8859p10", "latin6"}, {"blt8iso8859p13", "latin7"},{"cel8iso8859p14", "latin8"}, {"we8iso8859p15", "latin9"},{"ar8mswin1256", "win1256"}, {"vn8mswin1258", "win1258"},{"cl8mswin1251", "win1251"}, {"we8mswin1252", "win1252"},{"ee8mswin1250", "win1250"}, {"el8mswin1253", "win1253"},{"tr8mswin1254", "win1254"}, {"iw8mswin1255", "win1255"},{"blt8mswin1257", "win1257"}, {"cl8koi8u", "koi8u"}, {"cl8koi8r", "koi8r"},{"zhs16gbk", "gbk"}, {"ja16sjis", "shiftjis"},{"ja16sjistilde", "shiftjis"}, {"zht16mswin950", "big5"}, {"ko16mswin949", "uhc"}, {"ru8pc866", "win866"}, {"cl8iso8859p5", "iso88595"},{"ar8iso8859p6", "iso88596"}, {"el8iso8859p7", "iso88597"}, {"iw8iso8859p8", "iso88598"} 示例 select UTL_RAW.CONVERT(UTL_RAW.CAST_TO_RAW('中国'), 'ZHS16GBK', 'AL32UTF8') from dual; convert 395 第 51 章 KDB_RAW ---------D6D0B9FA 51.4.2.18 COPIES 函数 COPIES 函数返回 RAW 字符串拼接 n 次形成的 RAW 值。 语法 UTL_RAW.COPIES(r IN RAW, n IN NUMBER) RETURN RAW 参数说明 r RAW 类型值。 n 拼接次数。 使用说明 1. n 取四舍五入后的整数值，次数 n 小于 1 报错； 2. 输入 r 为 NULL 或长度 0 报错，结果长度超出 raw 允许的最大长度报错。 示例 SELECT UTL_RAW.COPIES(HEXTORAW('01'),2) FROM DUAL; copies ----------0101 51.4.2.19 LENGTH 函数 LENGTH 函数获取 RAW 类型参数的字节值, 返回 INT4 类型。 语法 UTL_RAW.LENGTH(r IN RAW) RETURN INT4; 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION test0030() RETURNS INT AS 396 第 51 章 KDB_RAW DECLARE v1 RAW := '68656C6C6FE4BABAE5A4A7E98791E4BB93'; DECLARE v2 INT; BEGIN V2 = UTL_RAW.LENGTH(v1); RETURN V2; END; / \set SQLTERM ; SELECT * FROM test0030(); test0030 ---------17 (1 行记录) 51.4.2.20 OVERLAY 函数 OVERLAY 函数使用指定的 raw 数据覆盖目标 raw 数据的部分内容，返回覆盖后的 raw 数据。 语法 UTL_RAW.OVERLAY(overlay_str IN RAW, target IN RAW, pos IN NUMBER, len IN NUMBER, pad IN RAW) RETURN RAW 参数说明 overlay_str 目标待覆盖的 RAW 值。 target 输入的 RAW 值。 pos 指定覆盖的起始位置，默认值为 1。 len 指定覆盖长度，长度小于 0 报错；长度为 null 则默认为 overlay_str 长度。 pad 填充的 RAW 值。如果 len 超过 overlay_str 的长度，或 pos 位置超出 target 的长度，超出部分填充的 raw 值，缺省为 NULL。 397 第 51 章 KDB_RAW 使用说明 把 target 值从 pos 位置起始长度为 len 的部分替换为 overlay_str 指定的 raw。 1. 如果 overlay_str 长度小于 len 则增补 pad 指定的第一个字节； 2. 如果 overlay_str 长度大于 len 超出部分忽略； 3. 如果起始位置超出指定 target 长度，则先用 pad 第一个字节补充，再拼接 overlay_str； 4. overlay_str 为 NULL 或长度为 0 报错； 5. target 未指定报错； 6. 结果超出 raw 允许的最大长度报错； 7. 起始位置小于 1 报错；为 null 则等价于 1； 8. 指定长度小于 0 报错；长度为 null 则为 overlay_str 长度； 9. pos 和 len 截取整数计算。 示例 SELECT UTL_RAW.OVERLAY(hextoraw('aaaaaaaa'),hextoraw('bbbbbbbb'),2,2) FROM dual; overlay -----------BBAAAABB 51.4.2.21 REVERSE 函数 REVERSE 函数把输入 RAW 值的字节颠倒顺序后返回结果。 语法 UTL_RAW.REVERSE (r IN RAW ) RETURN RAW 参数说明 r：RAW 类型，输入 RAW 值。 使用说明 输入 r 为 NULL 或长度为 0 会报错。 返回值 RAW 类型，颠倒顺序后的结果。 示例 398 第 51 章 KDB_RAW SELECT UTL_RAW.REVERSE('0102030') FROM DUAL; reverse ---------30201000 51.4.2.22 SUBSTR 函数 SUBSTR 函数截取输入 RAW 值中从 pos 开始长度为 len 的子串，并返回子串。 语法 UTL_RAW.SUBSTR (r IN RAW , pos IN INTEGER [, len IN INTEGER] ) RETURN RAW 参数说明 r RAW 类型，输入 RAW 值。 pos integer 类型，截取的起始位置。 len integer 类型，截取长度。 使用说明 1. 起始位置 pos = 0 或大于 RAW 长度报错； 2. 指定长度 len 小于 1 或大于起始位置后剩余长度报错； 3. 起始位置 pos 大于 0，从 r 开头计数；小于 0，从 r 结尾计数； 4. 不指定长度 len，则截取剩余所有长度； 5. 输入 r 为 NULL 则返回 NULL。 返回值 RAW 类型，截取的子串。 示例 SELECT UTL_RAW.SUBSTR('01020304', 4, 1) FROM DUAL; substr -------04 399 第 51 章 KDB_RAW 51.4.2.23 TRANSLATE 函数 TRANSLATE 函数把输入的 raw 数据中字节按映射规则替换。 语法 UTL_RAW.TRANSLATE (r IN RAW, from_set IN RAW, to_set IN RAW) RETURN RAW 参数说明 r RAW 类型，输入 RAW 值。 from_set 被替换的源 RAW 值。 to_set 指定替换为目标 RAW 值。 使用说明 把输入参数 r 中字节按 from_set 中出现的位置替换为 to_set 对应位置的字节。 1. 如果字节在 from_set 出现，并且在 to_set 中有对应位置的字节，则替换为 to_set 中该对应字节；如果同一字 节在 from_set 中出现多次，以第一次出现位置的对应关系进行替换； 2. 如果字节在 from_set 出现，并且在 to_set 中没有对应位置的字节，则从结果中删除； 3. 如果字节没有在 from_set 出现，则保留在结果中； 4. 如果 to_set 比 from_set 长，则多出部分忽略； 5. 任何输入参数为 NULL 或长度为 0 报错。 返回值 RAW 类型。 示例 SELECT UTL_RAW.TRANSLATE(hextoraw('01020304'),hextoraw('01020304'),hextoraw('0a0b0c0d')) FROM DUAL; translate ----------0A0B0C0D 51.4.2.24 TRANSLITERATE 函数 TRANSLITERATE 函数把输入的 raw 数据中字节按映射规则替换。 400 第 51 章 KDB_RAW 语法 UTL_RAW.TRANSLITERATE (r IN RAW, to_set IN RAW,from_set IN RAW, pad IN RAW ) RETURN RAW 参数说明 r RAW 类型，输入 RAW 值。 to_set 指定替换为目标 RAW 值。 from_set 被替换的源 RAW 值。 pad 填充的 RAW 值。to_set 比 from_set 短的情况默认使用的替换字节，缺省为 NULL。 使用说明 1. 如果字节在 from_set 出现，并且在 to_set 中有对应位置的字节，则替换为 to_set 中该对应字节；如果同一字 节在 from_set 中出现多次，以第一次出现位置的对应关系进行替换； 2. 如果字节在 from_set 出现，并且在 to_set 中没有对应位置的字节，则替换为 pad 参数的第一个字节； 3. 如果字节没有在 from_set 出现，则保留在结果中； 4. 如果 from_set 为 NULL，默认为 00…ff； 5. 输入参数 r 为 NULL 或长度为 0 报错。 返回值 RAW 类型。 示例 SELECT UTL_RAW.TRANSLITERATE( hextoraw('01020304'),hextoraw('0a0b0c0d'), hextoraw('010203'),hextoraw('5555')) FROM DUAL; transliterate --------------0A0B0C04 401 第 51 章 KDB_RAW 51.4.2.25 XRANGE 函数 XRANGE 函数截取指定的起始和结束 RAW 数据之间的连续字节 RAW 值，并返回 RAW 值。 语法 UTL_RAW.XRANGE(start_byte IN RAW, end_byte IN RAW ) RETURN RAW 参数说明 start_byte 起始 RAW 字节，缺省为’00’。 end_byte 结束 RAW 字节，缺省为’FF’。 使用说明 start_byte 默认 00，end_byte 默认 ff，只取第一个字节。 返回值 RAW 类型。 示例 SELECT UTL_RAW.XRANGE(hextoraw('01'),hextoraw('04')) FROM DUAL; xrange --------------01020304 51.4.3 UTL_I18 包 UTL_I18N 系统包提供对于 RAW 数据类型的编码转换操作。 51.4.3.1 RAW_TO_CHAR 函数 RAW_TO_CHAR 函数将 raw 数据按指定字符集转换成字符串。 语法 UTL_I18N.RAW_TO_CHAR ( data IN RAW, src_charset IN VARCHAR2 DEFAULT NULL) RETURN VARCHAR2; 402 第 51 章 KDB_RAW 参数说明 data 待转换的 raw 字节串。 src_charset 指定字符集名称。 使用说明 1. 如果 data 为 NULL 或长度为 0，或 src_charset 为非法字符集名称，返回 NULL。 2. 如果 src_charset 为 NULL，则取当前数据库字符集。 示例 SELECT UTL_I18N.RAW_TO_CHAR('D6D0B9FA', 'ZHS16GBK') FROM dual; raw_to_char ------------中国 51.4.3.2 STRING_TO_RAW 函数 STRING_TO_RAW 函数将把某个字符集下的字符串转换成指定字符集后的字节序列，返回 RAW。 语法 UTL_I18N.STRING_TO_RAW ( data IN VARCHAR2 CHARACTER SET ANY_CS, dst_charset IN VARCHAR2 DEFAULT NULL) RETURN RAW; 参数说明 data 字符类型数据。 dst_charset 指定字符集名称。 使用说明 1. 如果 data 为 NULL 或长度为 0，或 dst_charset 为非法字符集名称，返回 NULL； 2. 如果 dst_charset 为 NULL，则取当前数据库字符集。 示例 403 第 51 章 KDB_RAW SELECT UTL_I18N.STRING_TO_RAW('中国', 'ZHS16GBK') FROM dual; string_to_raw --------------D6D0B9FA 51.5 插件 kdb_raw 卸载方法 执行如下命令： drop extension kdb_raw; 51.6 插件 kdb_raw 升级方法 kdb_raw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 404 第 52 章 KDB_SCHEDULE 52章 kdb_schedule 第 52.1 插件 kdb_schedule 简介 kdb_schedule 是 KingbaseES 的一个扩展插件。主要功能是基于后台进程来实现自动作业功能。kdb_schedule 插件提供了 DBMS_JOB 和 DBMS_SCHEDULER 包，其中定义了与自动作业功能相关的存储过程和函数。 • 插件名为 kdb_schedule • 插件版本 V1.0 52.2 插件 kdb_schedule 加载方式 使用 kdb_shcedule 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启数据库。 示例： shared_preload_libraries = 'kdb_schedule' # (change requires restart) 52.3 插件 kdb_schedule 的参数配置 以下三个配置选项可以在 kingbase.conf 文件中指定： • job_queue_processes 允许用户启动的最大并发数，当其值设置为 0 时，表示不启动自动作业功能, 默认为 0， 不开启自动作业。 • sys_job.log_level 用于设置 JOB 后 台 进 程 的 日 志 级 别， 更 改 后 需 要 重 新 加 载 配 置 文 件， 可 选 项： LOG_ERROR，LOG_WARNING，LOG_DEBUG，默认为 LOG_ERROR。 • sys_job.poll_time 用于设置轮询系统表间隔时间, 单位秒，默认值为 10 秒。 405 第 52 章 KDB_SCHEDULE 注意: kdb_shcedule 目前不支持 windows 环境下使用。在特殊环境下（申威...)，初始化数据库时，提示用户 kdb_schedule.so 缺失库文件时，需用户手动 export LD_LIBRARY_PATH 为数据库 lib 目录。 52.4 插件 kdb_schedule 的使用方法 52.4.1 DBMS_JOB 模式下存储过程 DBMS_JOB 模式提供调度和管理作业任务的功能。该包功能可以由 DBMS_SCHDULE 替代。 DBMS_JOB 具有如下限制： a. 需要创建 kdb_schedule 扩展。 b. 仅支持 PL/SQL 类型的任务。 c. 仅支持本地任务。 d. 间隔时间采用日历表示法。 下表列出了 DBMS_JOB 子程序并简要的表述了它们。 表 52.4.1: DBMS_JOB 软件包子程序 子程序名称 说明 BROKEN 存储过程 中止一个处于可执行状态的 job CHANGE 存储过程 更改 job 的运行参数 INSTANCE 存储过程 增加 job 执行的连接串信息。 INTERVAL 存储过程 更改 job 运行的时间 NEXT_DATE 存储过程 更改 job 下一次的运行时间 REMOVE 存储过程 删除一个 job RUN 存储过程 立即运行指定的 job SUBMIT 存储过程 创建一个 job WHAT 存储过程 更改 job 执行的动作 406 第 52 章 KDB_SCHEDULE 52.4.1.1 BROKEN 存储过程 此程序将 job 设置为中止。设置为中止的 job 不会再运行。 语法格式 DBMS_JOB.BROKEN( job INTEGER, broken BOOLEAN, next_date TIMESTAMP DEFAULT now()); 参数说明 表 52.4.2: broken 参数 参数 描述 job 由系统分配的 job 的 ID。 broken 将 job 设置为 enable 或者 disable。true 为 disable，false 为 enable。 next_date job 运行的下一个日期。 示例 call dbms_job.submit(1, 'CREATE TABLE T1(A int)', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false); call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456'); call dbms_job.broken(1,TRUE,now()); 52.4.1.2 CHANGE 存储过程 此过程更改 job 中的属性信息。 语法格式 DBMS_JOB.CHANGE( job INTEGER, what TEXT, next_date TIMESTAMP, interva TEXT, instance INTEGER DEFAULT 0, force BOOLEAN DEFAULT FALSE); 参数说明 407 第 52 章 KDB_SCHEDULE 表 52.4.3: change 参数 参数 描述 job 由系统分配的 job 的 ID。 what job 要运行的 PL/SQL。 next_date job 运行的下一个日期。 interva job 运行的间隔时间。 instance 暂不支持，默认为 0。 force 暂不支持，默认为 FALSE。 示例 call dbms_job.change(1, 'CREATE TABLE T1(a INT);', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', 0, false); 52.4.1.3 INTERVAL 存储过程 此过程更改 job 中的间隔时间属性。 语法格式 DBMS_JOB.INTERVAL( job INTEGER, interva TEXT); 参数说明 表 52.4.4: interval 参数 参数 描述 job 由系统分配的 job 的 ID。 interva job 运行的间隔时间。 示例 call dbms_job.interval(1, 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10'); 408 第 52 章 KDB_SCHEDULE 52.4.1.4 NEXT_DATE 存储过程 此过程更改 job 中的下次运行时间信息。 语法格式 DBMS_JOB.NEXT_DATE( job INTEGER, next_date TIMESTAMP); 参数说明 表 52.4.5: next_date 参数 参数 描述 job 由系统分配的 job 的 ID。 next_date job 运行的下一个日期。 示例 call dbms_job.next_date(1, now()); 52.4.1.5 REMOVE 存储过程 此过程删除一个 job。 语法格式 DBMS_JOB.REMOVE( job INTEGER); 参数说明 表 52.4.6: remove 参数 参数 描述 job 由系统分配的 job 的 ID。 示例 call dbms_job.remove(1); 409 第 52 章 KDB_SCHEDULE 52.4.1.6 RUN 存储过程 此过程运行一个 job。 语法格式 DBMS_JOB.RUN( job INTEGER); 参数说明 表 52.4.7: RUN 参数 参数 描述 job 由系统分配的 job 的 ID。 示例 call dbms_job.submit(1, 'CREATE TABLE T1(A int)', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false); call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456'); call dbms_job.run(1); 52.4.1.7 SUBMIT 存储过程 此过程创建一个 job。 语法格式 DBMS_JOB.SUBMIT( OUT job INTEGER, what text, next_date TIMESTAMP DEFAULT now(), interva text DEFAULT NULL, no_parse BOOLEAN DEFAULT FALSE, instance INTEGER DEFAULT 0, force BOOLEAN DEFAULT FALSE); 参数说明 410 第 52 章 KDB_SCHEDULE 表 52.4.8: SUBMIT 参数 参数 描述 job 由系统分配的 job 的 ID。 what job 要运行的 PL/SQL。 next_date job 运行的下一个日期。 interva job 运行的间隔时间。 no_parse 暂不支持，默认为 FALSE。 instance 暂不支持，默认为 0。 force 暂不支持，默认为 FALSE。 示例 \set SQLTERM / DECLARE JOBID INT; BEGIN DBMS_JOB.SUBMIT(jobid, 'CREATE TABLE T1(A int)', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false); END; / \set SQLTERM ; 52.4.1.8 WHAT 存储过程 此过程更改 job 执行的行为信息。 语法格式 DBMS_JOB.WHAT( job INTEGER, what TEXT); 参数说明 411 第 52 章 KDB_SCHEDULE 表 52.4.9: what 参数 参数 描述 job 由系统分配的 job 的 ID。 what job 要运行的 PL/SQL。 示例 call dbms_job.what(1, 'CREATE TABLE T1(a INT);'); 52.4.1.9 INSTANCE 存储过程 此过程增加 job 执行的连接串信息。 语法格式 DBMS_JOB.INSTANCE( job INTEGER, instance TEXT); 参数说明 表 52.4.10: instance 参数 参数 描述 job 由系统分配的 job 的 ID。 instance job 要运行数据库的连接串。 示例 call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456'); 52.4.2 DBMS_SCHEDULER 模式下函数 DBMS_SCHEDULER 模式提供调度和管理作业任务的功能。该包提供了 DBMS_JOB 包的功能，并有所增强。 DBMS_SCHEDULER 具有如下限制： a. 需要创建 kdb_schedule 扩展。 b. 间隔时间采用日历表示法。 412 第 52 章 KDB_SCHEDULE 下表列出了 DBMS_SCHEDULRE 子程序并简要的表述了它们。 52.4.2.1 CREATE_PROGRAM 存储过程 创建一个 job 任务的程序。 语法格式 DBMS_SCHEDULER.CREATE_PROGRAM( program_name TEXT, program_type TEXT, program_action TEXT, acconnstr TEXT, acdbname TEXT, number_of_arguments INTEGER DEFAULT 0, enabled BOOLEAN DEFAULT FALSE, comments TEXT DEFAULT NULL); 参数说明 表 52.4.11: CREATE_PROGRAM 参数 参数 描述 program_name 程序的名字。 program_type 程 序 的 类 型。 有 下 列 类 型：PLSQL_BLOCK、STORED_ 过 存 储 程、SQL_SCRIPT、EXECUTABLE、EXTERNAL_SCRIPT、 BACKUP_SCRIPT program_action 程序的动作。 acconnstr 数据库连接串。 acdbname 数据库名称。 number_of_arguments 程序动作的参数，暂不支持, 0 为默认值。 enabled 程序的状态，true 启动状态，false 禁用状态。 comments 程序的注释信息。 示例 call DBMS_SCHEDULER.CREATE_PROGRAM('program1', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'test', 0, true, 'this is test program'); 413 第 52 章 KDB_SCHEDULE 52.4.2.2 DROP_PROGRAM 存储过程 删除一个 job 任务的程序。 语法格式 DBMS_SCHEDULER.DROP_PROGRAM( program_name TEXT, force BOOLEAN DEFAULT FALSE); 参数说明 表 52.4.12: DROP_PROGRAM 参数 参数 描述 program_name 程序的名字。 force 暂不支持，默认值为 false。 示例 call dbms_scheduler.drop_program('program1', true); 52.4.2.3 CREATE_SCHEDULE 存储过程 创建一个 job 任务的调度程序。 语法格式 DBMS_SCHEDULER.CREATE_SCHEDULE( schedule_name TEXT, start_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, repeat_interval TEXT DEFAULT NULL, end_date TIMESTAMP WITH TIME ZONE DEFAULT NULL, comments TEXT DEFAULT NULL); 参数说明 414 第 52 章 KDB_SCHEDULE 表 52.4.13: CREATE_SCHEDULE 参数 参数 描述 schedule_name 调度程序的名字。 start_date 调度程序的开始时间 repeat_interval 调度程序的间隔时间 end_date 调度程序的结束时间 comment 调度程序的注释信息 示例 call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule1', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule'); 52.4.2.4 DROP_SCHEDULE 存储过程 删除一个 job 任务的调度程序。 语法格式 DBMS_SCHEDULER.DROP_SCHEDULE( schedule_name TEXT, force BOOLEAN DEFAULT FALSE); 参数说明 表 52.4.14: DROP_SCHEDULE 参数 参数 描述 schedule_name 调度程序的名字。 force 暂不支持，默认值为 false。 示例 call DBMS_SCHEDULER.DROP_SCHEDULE('schedule1', true); 52.4.2.5 EVALUATE_CALENDAR_STRING 存储过程 计算符合规则的下一个日期。 415 第 52 章 KDB_SCHEDULE 语法格式 DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING( calendar_string TEXT, start_date TIMESTAMP WITH TIME ZONE, return_date_after TIMESTAMP WITH TIME ZONE, OUT next_run_date TIMESTAMP WITH TIME ZONE); 参数说明 表 52.4.15: EVALUATE_CALENDAR_STRING 参数 参数 描述 calendar_string 调度规则。 start_date 开始时间。 return_date_after 最近一次的执行时间。 next_run_date 下一次运行的时间。返回参数 示例 \set SQLTERM / DECLARE next_run_date TIMESTAMP; BEGIN DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING('freq=yearly;interval=5;bymonth=10; bymonthday=10;byhour=10;byminute=10;bysecond=10','','',next_run_date); DBMS_OUTPUT.PUT_LINE(next_run_date); END; / \set SQLTERM ; 52.4.2.6 CREATE_JOB 存储过程 创建一个 job 任务。 语法格式 DBMS_SCHEDULER.CREATE_JOB( job_name TEXT, program_name TEXT, schedule_name TEXT, job_class TEXT DEFAULT 'Routine Maintenance', enabled BOOLEAN DEFAULT FALSE, 416 第 52 章 KDB_SCHEDULE auto_drop BOOLEAN DEFAULT TRUE, comments TEXT DEFAULT NULL, credentail_name TEXT DEFAULT NULL, destination_name TEXT DEFAULT NULL); 参数说明 表 52.4.16: CREATE_JOB 参数 参数 描述 job_name job 的名字。 program_name 程序的名字。 schedule_name 调度程序的名字。 job_class job 的类型，默认 Routine Maintenance。 enabled job 的状态。true 启用，false 禁用 auto_drop job 完成后自动删除，暂不支持，默认 true comment job 的注释信息 credentail_name 暂不支持，默认为 NULL destination_name 暂不支持，默认为 NULL 示例 call DBMS_SCHEDULER.CREATE_PROGRAM('program1', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'kingbase', 0, true, 'this is test program'); call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule1', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule'); call DBMS_SCHEDULER.CREATE_JOB('job', 'program1', 'schedule1', 'Routine Maintenance', false, true, 'this is test job'); 52.4.2.7 DROP_JOB 存储过程 删除一个 job 任务。 语法格式 DBMS_SCHEDULER.DROP_JOB( job_name TEXT, force BOOLEAN DEFAULT FALSE, 417 第 52 章 KDB_SCHEDULE defer BOOLEAN DEFAULT FALSE, commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR'); 参数说明 表 52.4.17: DROP_JOB 参数 参数 描述 job_name job 的名字。 force 暂不支持，默认值为 false。 defer 暂不支持，默认值为 false。 commit_semantice 暂不支持，默认值为 STOP_ON_FIRST_ERROR。 示例 call DBMS_SCHEDULER.DROP_JOB('job', false, false, 'STOP_ON_FIRST_ERROR'); 52.4.2.8 RUN_JOB 存储过程 运行一个 job 任务。 语法格式 DBMS_SCHEDULER.RUN_JOB( job_name TEXT, use_current_session BOOLEAN DEFAULT TRUE); 参数说明 表 52.4.18: RUN_JOB 参数 参数 描述 job_name job 的名字。 use_current_session 暂不支持，默认值为 true。 示例 call DBMS_SCHEDULER.CREATE_PROGRAM('program2', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'kingbase', 0, true, 'this is test program'); call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule2', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule'); 418 第 52 章 KDB_SCHEDULE call DBMS_SCHEDULER.CREATE_JOB('job1', 'program2', 'schedule2', 'Routine Maintenance', false, true, 'this is test job'); call DBMS_SCHEDULER.RUN_JOB('job1', true); 52.4.2.9 DISABLE 存储过程 禁用一个 job 任务。 语法格式 DBMS_SCHEDULER.DISABLE( name TEXT, force BOOLEAN DEFAULT FALSE, commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR'); 参数说明 表 52.4.19: DISABLE 参数 参数 描述 name job 的名字。 force 暂不支持，默认值为 false。 commit_semantics 暂不支持，默认值为 STOP_ON_FIRST_ERROR。 示例 call DBMS_SCHEDULER.DISABLE('job1', false, 'STOP_ON_FIRST_ERROR'); 52.4.2.10 ENABLE 存储过程 启用一个 job 任务。 语法格式 DBMS_SCHEDULER.ENABLE( name TEXT, commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR'); 参数说明 419 第 52 章 KDB_SCHEDULE 表 52.4.20: ENABLE 参数 参数 描述 name job 的名字。 commit_semantics 暂不支持，默认值为 STOP_ON_FIRST_ERROR。 示例 call DBMS_SCHEDULER.ENABLE('job1', 'STOP_ON_FIRST_ERROR'); 52.4.3 日历表示法 日历表示法是用来定义重复间隔的实现方法，DBMS_JOB 和 DBMS_SCHEDULER 中的时间定义使用该语 法。 语法格式 repeat_interval = regular_schedule regular_schedule = frequency_clause [";" interval_clause] [";" bymonth_clause] [";" byweekno_clause] [";" byyearday_clause] [";" bydate_clause] [";" bymonthday_clause] [";" byday_clause] [";" byhour_clause] [";" byminute_clause] [";" bysecond_clause] frequency_clause = "FREQ" "=" ( predefined_frequency predefined_frequency = "YEARLY" | "MONTHLY" | "WEEKLY" | "DAILY" | "HOURLY" | "MINUTELY" | "SECONDLY" interval_clause = "INTERVAL" "=" intervalnum intervalnum = 1 through 99 bymonth_clause = "BYMONTH" "=" monthlist monthlist = month ( "," month)* month = numeric_month | char_month numeric_month = 1 | 2 | 3 ... 12 char_month = "JAN" | "FEB" | "MAR" | "APR" | "MAY" | "JUN" | "JUL" | "AUG" | "SEP" | "OCT" | "NOV" | "DEC" bymonthday_clause = "BYMONTHDAY" "=" monthday_list monthday_list = monthday ( "," monthday)* monthday = [minus] monthdaynum monthdaynum = 1 through 31 byhour_clause = "BYHOUR" "=" hour_list hour_list = hour ( "," hour)* hour = 0 through 23 byminute_clause = "BYMINUTE" "=" minute_list minute_list = minute ( "," minute)* minute = 0 through 59 byscond_clause = "BYSECOND" "=" second_list 420 第 52 章 KDB_SCHEDULE second_list = second ( "," second)* second = 0 through 59 参数说明 表 52.4.21: 参数含义 参数 描述 FREQ 重复时间的类型。这里有 yearly、monthly、weekly、daily、hourly、minutely INTERVAL 重复的频率，默认值是 1。 BYMONTH 指定月份。 BYMONTHDAY 指定一月中的某一天。 BYHOUR 指定一天中的某一个小时。 BYBYMINTUE 指定一个小时中的秒一分。 BYSECOND 指定一分钟内的某一秒。 示例 每天早上 10 点 FREQ=DAILY;BYHOUR=10;BYMINUTE=0;BYSECOND=0; 每个隔 7 天早上 10 点 FREQ=DAILY;INTERVAL=7;BYHOUR=10;BYMINUTE=0;BYSECOND=0; 每年 10 月 1 号早上 10 点 FREQ=YEARLY;BYMONTH=10;BYMONTHDAY=1;BYHOUR=10;BYMINUTE=0;BYSECOND=0; 52.5 插件 kdb_schedule 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 421 第 52 章 KDB_SCHEDULE 52.6 插件 kdb_schedule 升级方法 kdb_schedule 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 422 第 53 章 KDB_TINYINT 53章 kdb_tinyint 第 53.1 插件 kdb_tinyint 简介 插件 kdb_tinyint 是初始化内置，基本类型，支持 tinyint 类型。 • 插件名为 kdb_tinyint • 插件版本 V1.0 53.2 插件 kdb_tinyint 加载方式 默认已经创建，如果没有创建，需要在命令行执行 create extension kdb_tinyint; 示例： create extension kdb_tinyint; 53.3 插件 kdb_tinyint 的参数配置 无需配置任何参数。 53.4 插件 kdb_tinyint 的使用方法 加载插件 kdb_tinyint 后，按照如下方式使用相应功能。 423 第 53 章 KDB_TINYINT 53.4.1 conversion functions support 支持 tinyint 类型和数值及字符类型之间转换。 语法 create cast (int4 as tinyint) with function tinyint(int4) as assignment; create cast (tinyint as int4) with function int4(tinyint) as implicit; create cast (bool as tinyint) with function tinyint(bool) as assignment; create cast (tinyint as bool) with function bool(tinyint) as assignment; create cast (int2 as tinyint) with function tinyint(int2) as assignment; create cast (tinyint as int2) with function int2(tinyint) as implicit; create cast (int8 as tinyint) with function tinyint(int8) as assignment; create cast (tinyint as int8) with function int8(tinyint) as implicit; create cast (float4 as tinyint) with function tinyint(float4) as assignment; create cast (tinyint as float4) with function float4(tinyint) as implicit; create cast (float8 as tinyint) with function tinyint(float8) as assignment; create cast (tinyint as float8) with function float8(tinyint) as implicit; create cast (numeric as tinyint) with function tinyint(numeric) as assignment; create cast (tinyint as numeric) with function tinyinttonumeric(tinyint) as implicit; create cast (bpchar as tinyint) with function tinyint(bpchar) as implicit; create cast (tinyint as bpchar) with function text(tinyint) as assignment; create cast (varchar as tinyint) with function tinyint(varchar) as implicit; create cast (tinyint as varchar) with function text(tinyint) as assignment; create cast (bpcharbyte as tinyint) with function tinyint(bpcharbyte) as implicit; create cast (tinyint as bpcharbyte) with function text(tinyint) as assignment; create cast (varcharbyte as tinyint) with function tinyint(varcharbyte) as implicit; create cast (tinyint as varcharbyte) with function text(tinyint) as assignment; create cast (text as tinyint) with function tinyint(text) as implicit; create cast (tinyint as text) with function text(tinyint) as implicit; 示例 select '127'::tinyint::int2 as result; result -------127 select '127'::tinyint::int4 as result; result -------127 select '127'::tinyint::int8 as result; result -------- 424 第 53 章 KDB_TINYINT 127 53.4.2 operator functions support tinyint 类型和 tinyint、int2、int4、int8 之间支持算术操作符 +-*/和比较操作符 =、<>、<、<=、>、>= 操 作。支持 tinyint 类型和 money 之间 * 操作。 示例 select tinyint '8' + int2 '5' as result; result -------13 select tinyint '8' - tinyint '5' as result; result -------3 select tinyint '8' * tinyint '5' as result; result -------40 select tinyint '8' / tinyint '5' as result; 53.4.3 index suppor tinyint 类型支持 btree、bitmap、hash、gin、brin 类型索引。 示例 create table tinyint_ind(a tinyint); CREATE TABLE insert into tinyint_ind values(generate_series(-128, 127)); INSERT 0 256 create index btree_index on tinyint_ind using btree(a); CREATE INDEX 425 第 53 章 KDB_TINYINT 53.4.4 mathematics functions support tinyint 类型支持支持 mod、abs、and、or、xor、shl、shr、not、um、up 函数。 示例 select mod(20::tinyint,3); mod ----2 53.5 插件 kdb_tinyint 卸载方法 系统启动自带插件，无法卸载。 53.6 插件 kdb_tinyint 升级方法 kdb_tinyint 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 426 第 54 章 KDB_UTILS_FUNCTION 第 54.1 54章 kdb_utils_function 插件 kdb_utils_function 简介 kdb_utils_function 是 KingbaseES 中的一个扩展插件，能够实现工具函数的功能，如：KingbaseES 版本信息函 数，若干字符串函数，若干 xml 函数以及行列转换函数等。 • 插件名为 kdb_utils_function • 插件版本 V1.3 54.2 插件 kdb_utils_function 加载方式 KingbaseES 默认不加载 kdb_utils_function 扩展插件，用户可以使用如下命令手工加载。 示例： create extension kdb_utils_function; 54.3 插件 kdb_utils_function 配置参数 无需配置任何参数 54.4 在使用 插件 kdb_utils_function 使用方法 kdb_utils_function 里 提 供 的 函 数 之 前， 我 们 需 要 将 他 添 加 到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库，或者使用 CREATE EXTENSION 命令在使用时创 建。 427 第 54 章 KDB_UTILS_FUNCTION shared_preload_libraries = 'kdb_utils_function' # (change requires restart) 或者在 ksql 中使用： CREATE EXTENSION kdb_utils_function; 语句在使用时创建。 54.4.1 函数列表 表 表 54.4.1 列出了 kdb_utils_function 扩展所提供的函数。 表 54.4.1: 扩展函数列表 插件名称 用途 appendchildxml(xml,text,xml) 参考 appendchildxml appendchildxml(xml,text,xml,text[]) 参考 appendchildxml deletexml(xml,text) 参考 deletexml deletexml(xml,text,text[]) 参考 deletexml existsnode(xml,text) 参考 existsnode existsnode(xml,text,text[]) 参考 existsnode extractvalue(xml,text) 参考 extractvalue extractvalue(xml,text,text[]) 参考 extractvalue get_kingbasees_version() 获取 KingbaseES 发生版本信息 insertchildxmlafter(xml,text,text,text) 参考 insertchildxmlafter insertchildxmlafter(xml,text,text,text,text[]) 参考 insertchildxmlafter insertchildxmlafter(xml,text,text,xml) 参考 insertchildxmlafter insertchildxmlafter(xml,text,text,xml,text[]) 参考 insertchildxmlafter insertchildxmlbefore(xml,text,text,text) 参考 insertchildxmlbefore insertchildxmlbefore(xml,text,text,text,text[]) 参考 insertchildxmlbefore insertchildxmlbefore(xml,text,text,xml) 参考 insertchildxmlbefore insertchildxmlbefore(xml,text,text,xml,text[]) 参考 insertchildxmlbefore insertchildxml(xml,text,text,text) 参考 insertchildxml 见续表 428 第 54 章 KDB_UTILS_FUNCTION 表 54.4.1 – 续表 插件名称 用途 insertchildxml(xml,text,text,text,text[]) 参考 insertchildxml insertchildxml(xml,text,text,xml) 参考 insertchildxml insertchildxml(xml,text,text,xml,text[]) 参考 insertchildxml insertxmlafter(xml,text,text,text) 参考 insertxmlafter insertxmlafter(xml,text,text,text,text[]) 参考 insertxmlafter insertxmlafter(xml,text,text,xml) 参考 insertxmlafter insertxmlafter(xml,text,text,xml,text[]) 参考 insertxmlafter insertxmlbefore(xml,text,text,text) 参考 insertxmlbefore insertxmlbefore(xml,text,text,text,text[]) 参考 insertxmlbefore insertxmlbefore(xml,text,text,xml) 参考 insertxmlbefore insertxmlbefore(xml,text,text,xml,text[]) 参考 insertxmlbefore updatexml(xml,text,text) 参考 updatexml updatexml(xml,text,text,text[]) 参考 updatexml updatexml(xml,text,xml) 参考 updatexml lnnvl(boolean) 参考 LNNVL max(character varying) 参考 聚集函数 min(character varying) 参考 聚集函数 nanvl(double precision,double precision) NaN 值判断函数，返回第一个非 NaN 值的参数值 nanvl(numeric,numeric) NaN 值判断函数，返回第一个非 NaN 值的参数值 nanvl(real,real) NaN 值判断函数，返回第一个非 NaN 值的参数值 group_concat(anyarray,text) 参考 GROUP_CONCAT nlssort(text,text) 参考 nlssort wm_concat(text) 参考 聚集函数 varchar_larger(character varying,character 参考 字符串函数和操作符 varying) 见续表 429 第 54 章 KDB_UTILS_FUNCTION 表 54.4.1 – 续表 插件名称 用途 varchar_smaller(character varying,character 参考 字符串函数和操作符 varying) 示例 -- 安装 kdb_utils_function CREATE EXTENSION kdb_utils_function; -- 使用 get_kingbasees_version() select get_kingbasees_version(); get_kingbasees_version -----------------------------------------------------------------KingBaseES V9.0. (c) Kingbase Corporation. All rights reserved. (1 row) 54.5 插件 backtrace 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。或者使用 DROP EXTENSION 命 令进行卸载。 示例： DROP EXTENSION kdb_utils_function; 插件 backtrace 升级方法： 430 第 55 章 KDB_XMLTYPE 55章 kdb_xmltype 第 55.1 插件 kdb_xmltype 简介 kdb_xmltype 是 KingbaseES 的一个扩展插件，主要用于定义 Oracle 兼容 XMLTYPE 类型和相关的操作函数。 • 插件名为 kdb_xmltype • 插件版本 V1.0.0 55.2 插件 kdb_xmltype 加载方式 KingbaseES 默认不加载 kdb_xmltype 扩展插件，请使用以下命令加载插件和创建扩展： CREATE EXTENSION kdb_xmltype; 注意: 创建扩展前，需要关闭禁用多态函数参数，执行’set ora_forbid_func_polymorphism to off;’ 。 55.3 插件 kdb_xmltype 的参数配置 无需配置任何参数 431 第 55 章 KDB_XMLTYPE 55.4 插件 kdb_xmltype 的使用方法 55.4.1 XMLTYPE 类型 kdb_xmltype 插件定义了 Oracle 兼容的 XMLTYPE 类型，该类型是一个对象类型。XMLTYPE 类型位于 sys 模式下，为数据库系统依赖，禁止删除。 XMLTYPE 类型可以用于定义表和视图的列类型，也可用于定义函数或者过程的参数和返回值类型。XMLTYPE 类型与已有 xml 类型兼容，支持所有 xml 类型处理函数。XMLTYPE 类型支持 XML 格式检查，对输入的 非良好格式将报错。 CREATE OR REPLACE TYPE xmltype AS OBJECT ( xml_data xml, constructor function xmltype(self in out xmltype) return self as result, constructor function xmltype(xml_string in text) return self as result ); XMLTYPE 函数的典型用法举例如下： CREATE TABLE tab_xml (a int, b xmltype); INSERT INTO tab_xml VALUES (1, '12'); INSERT INTO tab_xml VALUES (2, xmltype('34')); SELECT * FROM tab_xml; DROP TABLE tab_xml; 55.4.1.1 输入输出 XMLTYPE 类型的输入输出函数与 record 类型的输入输出函数有相同的参数。 不同于 record 类型，XMLTYPE 类型的输入函数的第一个参数只能接受 XML 字符串（例如：’1’）， 而不能接受用小括号包围的 XML 字符串（例如：’(1)’），后一情况被视为不合格的 XML 字符串。 对于不合格的 XML 字符串，xml 解析器的行为受 GUC 参数 xmloption 控制。当 xmloption=content 时（默认 值），xml 解析器将不合格的输入字符串当作 XML 元素内容；当 xmloption=document 时，XML 解析器对不合格 的输入字符串报错处理。对于空字符串或空值 NULL，均会被 XML 解析器作为 NULL 处理，生成的实例为 NULL。 不同于 record 类型，XMLTYPE 类型的输出函数返回结果是 XML 字符串，而不是用小括号 () 包围的 XML 字 符串。 XMLTYPE 类型的构造函数，接受一个 text 类型的 XML 字符串，返回一个 XMLTYPE 类型实例。构造函数对 输入参数的解析规则与 XMLTYPE 类型的输入函数完全相同。 432 第 55 章 KDB_XMLTYPE 55.4.1.2 数据存储 XMLTYPE 类型属于一种内置的对象类型，它的数据存储格式与 record 类型相同。 55.4.1.3 操作符 XMLTYPE 类型不支持任何操作符，这一点与内置 xml 类型相同。 55.4.1.4 类型转换 XMLTYPE 类型支持与内置 xml 类型之间的双向隐式转换，支持与 text/bpchar/varchar 类型之间的双向隐式赋 值转换。 55.4.1.5 索引 不支持在 XMLTYPE 类型列上直接创建列索引，但可以使用 xml 函数 extractvalue 创建基于函数的索引。 55.4.1.6 xml 函数 基于 XMLTYPE 类型与内置 xml 类型之间的双向隐式转换规则，所有接受内置 xml 类型为参数的函数，也均可 接受 XMLTYPE 类型的参数。 55.5 XMLTYPE 成员函数 55.5.1 createXML 函数 创建并返回一个 XMLType 实例，用于传入数据的字符串和 CLOB 参数必须包含格式正确且有效的 XML 文档。 语法 1、通过字符串创建一个 XMLType 实例。 STATIC FUNCTION createXML( xmlData IN varchar2) RETURN XMLType deterministic; 2、通过 clob 创建一个 XMLType 实例。 STATIC FUNCTION createXML( xmlData IN clob) RETURN XMLType deterministic; 433 第 55 章 KDB_XMLTYPE 参数说明 • xmlData：传入的 xml 数据。目前只支持传入 clob 和 varchar2 两种。 示例 create table tab_xml(a int, b xmltype); insert into tab_xml values (1, xmlType.createXML('1'::varchar2)); insert into tab_xml values (2, xmlType.createXML('2'::clob)); select * from tab_xml ; drop table tab_xml ; 55.5.2 existsnode 函数 检查 XML 中是否存在结点。如果 XPath 为 NULL 或文档为空，则返回 0，否则返回 1。 语法 MEMBER FUNCTION existsNode( xpath IN varchar2) RETURN number deterministic; 参数说明 • xpath：Xpath 表达式 示例 select xmltype('12').existsnode('/a/b/text()') from dual; \set SQLTERM / declare v1 xmltype; begin v1 := xmltype('12'); select v1.existsnode('/a/b/text()') from dual; end; / \set SQLTERM ; 434 第 55 章 KDB_XMLTYPE 55.5.3 extract 函数 用于提取 XMLType 片段，并返回包含结果节点的 XMLType 实例。如果 XPath 未产生任何节点，则返回 NULL。 语法 MEMBER FUNCTION extract( xpath IN varchar2) RETURN XMLType deterministic; 参数说明 • xpath：XPath 表达式 示例 select xmltype('12').extract('/a/b') from dual; \set SQLTERM / declare v1 xmltype; begin v1 := xmltype('12'); select v1.extract('/a/b/text()') from dual; end; / \set SQLTERM ; 55.5.4 getclobval 函数 以 CLOB 的形式获取 XMLType 实例的值。 语法 MEMBER FUNCTION getClobVal() RETURN clob deterministic; 参数说明 无 示例 select xmltype('12').extract('/a/b/text()').getclobval() from dual; \set SQLTERM / declare 435 第 55 章 KDB_XMLTYPE v1 xmltype; begin v1 := xmltype('12'); select v1.getclobval() from dual; select v1.extract('/a/b/text()').getclobval() from dual; end; / \set SQLTERM ; 55.5.5 getnumberval 函数 返回一个数值，该值的格式与 XMLType 实例所指向的文本值一致。XMLType 必须是包含数值的有效文本节 点。 语法 MEMBER FUNCTION getNumberVal() RETURN number deterministic; 参数说明 无 示例 select xmltype('12').extract('/a/b/text()').getnumberval() from dual; \set SQLTERM / declare v1 xmltype; begin v1 := xmltype('12'); select v1.extract('/a/b/text()').getnumberval() from dual; end; / \set SQLTERM ; 55.5.6 getstringval 函数 以字符串形式获取 XMLType 实例的内容。如果 XML 文档是一个文本结点，则返回文本本身。如果 XML 文档 超过 VARCHAR2 最大值 (10485760)，那么运行时就会报错。 语法 436 第 55 章 KDB_XMLTYPE MEMBER FUNCTION getStringVal() RETURN varchar2 deterministic; 参数说明 无 示例 [HAVING condition] select xmltype(’12’).extract(’/a/b/text()’).getstringval() from dual; set SQLTERM / declare v1 xmltype; begin select v1.getstringval() from dual; v1 := xmltype(’12’); select v1.extract(’/a/b/text()’).getstringval() from dual; end; / set SQLTERM ; 55.5.7 XMLSEQUENCE 函数 kdb_xmltype 插件定义了 Oracle 兼容的 XMLSEQUENCE 函数，该函数接受一个 xml 类型的 XML 实例，返 回一个包含所有顶层 XML 节点的可变数组。 语法 XMLSEQUENCE(xml_instance xml) returns xmlsequencetype 参数说明 XMLSEQUENCE 函数、函数返回值的类型都位于 sys 模式下。返回值 xmlsequencetype 类型是 XMLTYPE 类 型的可变数组。当输入数据为 NULL 时，函数返回 0 行，而不是空值。 示例 XMLSEQUENCE 函数的典型用法是和 TABLE 函数联合使用，用法举例： 以下例子展示了 XMLSEQUENCE 函数怎样将具有多个元素的 xml 文档分割为 VARRAY 单元素文档，之后再 用 TABEL 函数构造了一个表对象。 CREATE TABLE tab_xml (a int, b xml); INSERT INTO tab_xml VALUES (1, '12'); INSERT INTO tab_xml VALUES (2, xml ('34')); SELECT t.* FROM tab_xml, table(xmlsequence(extract(b, '/a/*'))) AS t; DROP TABLE tab_xml; 437 第 55 章 KDB_XMLTYPE 55.5.8 VALUE 函数 kdb_xmltype 插件定义了 Oracle 兼容的 VALUE 函数，该函数接受一个范围表别名作为参数，返回 record 类型 的对象实例。对象实例的类型与表的 record 类型相同。 语法 CREATE OR REPLACE FUNCTION value(x record) RETURNS record CREATE OR REPLACE FUNCTION value(x xmltype) RETURNS xmltype 参数说明 VALUE 函数有两个重载版本，当输入数据为空值 NULL 时，这两个版本函数均返回空值 NULL。 示例 VALUE 函数的典型用法举例： 以下例子创建了 persons 表和 subjects 表, 分别使用 VALUE 函数返回 person_t 对象和 xmltype 对象实例。 CREATE TYPE person_t AS OBJECT (name varchar2(100), ssn number); CREATE TABLE persons OF person_t; INSERT INTO persons VALUES (person_t('Bob', 1234)); INSERT INTO persons VALUES (person_t('Joe', 32456)); INSERT INTO persons VALUES (person_t('Tim', 5678)); SELECT value(t) FROM persons t; DROP TABLE persons; DROP TYPE person_t; CREATE TABLE subjects OF xmltype; INSERT INTO subjects VALUES ('math'); INSERT INTO subjects VALUES ('english'); INSERT INTO subjects VALUES ('chinese'); SELECT value(t) FROM subjects t; DROP TABLE subjects; 55.6 插件 kdb_xmltype 卸载方法 请使用以下命令卸载 kdb_xmltype 插件。 示例： DROP EXTENSION kdb_xmltype; 438 第 55 章 KDB_XMLTYPE 55.7 插件 kdb_xmltype 升级方法 kdb_xmltype 扩展插件随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 439 第 56 章 KINGBASE_FDW 56章 kingbase_fdw 第 56.1 插件 kingbase_fdw 简介 kingbase_fdw 模块提供了外部数据包装器 kingbase_fdw，它可以被用来访问存储在外部 KingbaseES 服务器中 的数据。 这个模块提供的功能大体上覆盖了较老的 dblink 模块的功能。但是 kingbase_fdw 提供了更透明且更兼容标准的 语法来访问远程表，并且可以在很多情况下给出更好的性能。 要使用 kingbase_fdw 来为远程访问做准备： • 使用 CREATE EXTENSION 来安装 kingbase_fdw 扩展。 • 使用 CREATE SERVER 创建一个外部服务器对象，它用来表示你想连接的每一个远程数据库。指定除了 user 和 password 之外的连接信息作为该服务器对象的选项。 • 使用 CREATE USER MAPPING 创建一个用户映射，每一个用户映射都代表你想允许一个数据库用户访问一 个外部服务器。指定远程用户名和口令作为用户映射的 user 和 password 选项。 • 为每一个你想访问的远程表使用 CREATE FOREIGN TABLE 或者 IMPORT FOREIGN SCHEMA 创建一个 外部表。外部表的列必须匹配被引用的远程表。但是，如果你在外部表对象的选项中指定了正确的远程名称， 你可以使用不同于远程表的表名和/或列名。 现在只需要从一个外部表 SELECT 来访问存储在它的底层的远程表中的数据。也可以使用 INSERT、UPDATE 或 DELETE 修改远程表（当然，在用户映射中已经指定的远程用户必须具有做这些事情的权限）。 注意当前 kingbase_fdw 缺少对于带 ON CONFLICT DO UPDATE 子句的 INSERT 语句的支持。不过，它支持 ON CONFLICT DO NOTHING 子句，已提供的唯一索引推断说明会被省略。另请注意 kingbase_fdw 支持 UPDATE 语句在分区表上执行的行移动调用，但是它目前不处理这样的情况：选择将移动行插入到的远程分区也是稍后将更新 的 UPDATE 目标分区。 通常推荐一个外部表的列被声明为与被引用的远程表列完全相同的数据类型和排序规则（如果可用）。尽管 kingbase_fdw 目前已经能够容忍在需要时执行数据类型转换，但是当类型或排序规则不匹配时可能会发生奇怪的语 义异常，因为远程服务器解释 WHERE 子句时可能会与本地服务器有所不同。 注意一个外部表可以被声明比底层的远程表较少的列，或者使用一种不同的列序。与远程表的列匹配是通过名字 而不是位置进行的。 440 第 56 章 KINGBASE_FDW • 插件名为 kingbase_fdw • 插件版本 V1.0.0 56.2 插件 kingbase_fdw 的加载方式 在 ksql 中运行： CREATE EXTENSION kingbase_fdw; 56.3 插件 kingbase_fdw 的参数配置 56.3.1 连接选项 一个使用 kingbase_fdw 外部数据包装器的外部服务器可以使用和 libpq 在连接字符串中能接受的选项，如对象 名称选项所述，不过不允许这些选项： • user 和 password（应该在用户映射中指定这些） • client_encoding（这是自动从本地服务器编码设置） • fallback_application_name（总是设置为 kingbase_fdw） 只有超级用户可以在不经过口令认证的情况下连接到外部服务器，因此应总是为属于非超级用户的用户映射指定 password 选项。 56.3.2 对象名称选项 这些选项可以被用来控制使用在被发送到远程 KingbaseES 服务器的 SQL 语句中使用的名称。 当一个外部表被使用不同于底层远程表的名称创建时，就需要这些选项。 • schema_name 这个选项给出用在远程服务器之上的外部表的模式名称，它可以为一个外部表指定。如果这个选项被 忽略，该外部表的模式名称将被使用。 • table_name 这个选项给出用在远程服务器上的外部表给出表名，它可以为一个外部表指定。如果这个选项被忽 略，该外部表的名字将被使用。 • column_name 441 第 56 章 KINGBASE_FDW 这个选项给出用在远程服务器上列的列名，它可以为一个外部表的一个列指定。如果这个选项被忽 略，该列的名字将被使用。 56.3.3 代价估计选项 kingbase_fdw 通过在远程服务器上执行查询来检索远程数据，因此理想的扫描一个外部表的估计代价应该是在 远程服务器上完成它的花销，外加一些通信开销。得到这样一个估计的最可靠的方法是询问远程服务器并加上一些通 信开销—但是对于简单查询，不值得为获得一个代价估计而额外使用一次远程查询。因此 kingbase_fdw 提供了下列 选项来控制如何完成代价估计： • use_remote_estimate 这个选项控制 kingbase_fdw 是否发出 EXPLAIN 命令来获得代价估计，它可以为一个外部表或一 个外部服务器指定。一个外部表的设置会覆盖它的服务器的任何设置，但是只用于这个表。默认值是 false。 • fdw_startup_cost 这个选项是一个要被加到那个服务器上所有外部表扫描的估计启动代价的数字值。这表示建立一个连 接、在远端解析和规查询的额外负荷等。默认值是 100。 • fdw_tuple_cost 这个选项是一个数字值，它被用作表示某个服务器上外部表扫描时，每元组额外代价，它可以为某个 外部服务器单独指定。表示在服务器之间数据传输的额外负荷。用户可以增加或减少这个数来反映到 远程服务器更高或更低的网络延迟。默认值是 0.01。 当 use_remote_estimate 为真时，kingbase_fdw 从远程服务器获得行计数和代价估计，然后在代价估计上加上 fdw_startup_cost 和 fdw_tuple_cost。当 use_remote_estimate 为假时，kingbase_fdw 执行本地行计数和代价估 计，并且接着在代价估计上加上 fdw_startup_cost 和 fdw_tuple_cost。这种本地估计不会很准确，除非有远程表统 计数据的本地拷贝可用。在外部表上运行 ANALYZE 是更新本地统计数据的方法，这将执行远程表的一次扫描并接 着计算和存储统计数据，就好像表在本地一样。保留本地统计数据可能是一种有用的方法来减少一个远程表的预查询 规划负荷—但是如果远程表被频繁更新，本地统计数据将很快就被废弃。 56.3.4 远程执行选项 默认情况下，只有使用了内建操作符和函数的 WHERE 子句才会被考虑在远程服务器上执行。 涉及非内建函数的子句将会在取完行后在本地进行检查。如果这类函数在远程服务器上可用并且可以用来产生和 本地执行时一样的结果，则可以通过将这种 WHERE 子句发送到远程执行来提高性能。可以用下面的选项控制这种 行为： • extensions 这个选项是一个用逗号分隔的已安装的 KingbaseES 扩展名称列表，这些扩展在本地和远程服务器上 具有兼容的版本。属于一个该列表中扩展的 immutable 函数和操作符将被考虑转移到远程服务器上执 行。这个选项只能为外部服务器指定，无法逐个表指定。 442 第 56 章 KINGBASE_FDW 在使用 extensions 选项时，用户应该负责确保列出的扩展在本地和远程服务器上都存在且保持一致。 否则，远程查询可能失败或者行为异常。 • fetch_size 这个选项指定在每次获取行的操作中 kingbase_fdw 应该得到的行数。可以为一个外部表或者外部服 务器指定这个选项。在表上指定的选项将会覆盖在服务器级别上指定的选项。默认值为 100。 56.3.5 可更新性选项 默认情况下，所有使用 kingbase_fdw 的外部表都被假定是可更新的。这可以使用下列选项覆盖： • updatable 这个选项控制 kingbase_fdw 是否允许外部表被使用 INSERT、UPDATE 和 DELETE 命令更新。它 可以为一个外部表或一个外部服务器指定。一个表级选项会覆盖一个服务器级选项。默认值是 true。 当然，如果远程表实际上并非可更新的，将产生一个错误。这个选项的使用主要是允许在不查询远程 服务器的情况下在本地抛出错误。但是要注意 information_schema 视图会根据这个选项的设置报告 一个 kingbase_fdw 外部表是可更新的（或者不可更新），而不需要远程服务器的任何检查。 56.3.6 导入选项 kingbase_fdw 能使用 IMPORT FOREIGN SCHEMA 导入外部表定义。这个命令会在本地服务器上创建外部表 定义，这个定义能匹配存在于远程服务器上的表或者视图。如果要被导入的远程表有用户自定义数据类型的列，本地 服务器上也必须具有相同名称的兼容类型。 导入行为可以用下列选项自定义（在 IMPORT FOREIGN SCHEMA 命令中给出）： • import_collate 这个选项控制是否在从外部服务器导入的外部表定义中包括列的 COLLATE 选项。默认是 true。如果远程服务 器具有和本地服务器不同的排序规则名集合，可能需要关闭这个选项，在不同的操作系统上运行时很可能就是 这样。 • import_default 这个选项控制是否在从外部服务器导入的外部表定义中包括列的 DEFAULT 表达式。默认是 false。如果启用这 个选项，要当心在远程服务器和本地服务器上计算表达式的方式不同，nextval() 常会导致这类问题。如果导入 的默认值表达式使用了一个本地不存在的函数或者操作符，IMPORT 将整个失败。 • import_not_null 这个选项控制是否在从外部服务器导入的外部表定义中包括列的 NOT NULL 约束。默认是 true。 注意除 NOT NULL 之外的约束将不会从远程表中导入。虽然 KingbaseES 确实支持外部表上的 CHECK 约束， 但不会自动导入它们，因为存在本地和远程服务器计算约束表达式方式不同的风险。CHECK 约束中的任何这类不一 致都可能导致查询优化中很难检测的错误。因此，如果你希望导入 CHECK 约束，你必须手工来做，并且你应该仔细 地验证每一个这种约束的语义。有关处理外部表上 CHECK 约束的更多细节，请见 CREATE FOREIGN TABLE。 443 第 56 章 KINGBASE_FDW 自动排除作为其他表的分区的表或外部表。分区表被导入，除非它们是其他表的分区。由于所有数据都可以通过 作为分区层次根的分区表来访问，所以这种方法应该允许访问所有数据而不创建额外的对象。 56.4 插件 kingbase_fdw 的使用 这里是一个用 kingbase_fdw 创建外部表的例子。首先安装该扩展： CREATE EXTENSION kingbase_fdw; 然后使用 CREATE SERVER 创建一个外部服务器。在这个例子中我们希望连接到一个位于主机 192.83.123.89 上并且监听 5432 端口的 KingbaseES 服务器。在该远程服务器上要连接的数据库名为 foreign_db： CREATE SERVER foreign_server FOREIGN DATA WRAPPER kingbase_fdw OPTIONS (host '192.83.123.89', port '5432', dbname 'foreign_db'); 需要用 CREATE USER MAPPING 定义一个用户映射来标识在远程服务器上使用哪个角色： CREATE USER MAPPING FOR local_user SERVER foreign_server OPTIONS (user 'foreign_user', password 'password'); 现在就可以使用 CREATE FOREIGN TABLE 创建外部表了。在这个例子中我们希望访问远程服务器上名为 some_schema.some_table 的表。它的本地名称是 foreign_table： CREATE FOREIGN TABLE foreign_table ( id integer NOT NULL, data text ) SERVER foreign_server OPTIONS (schema_name 'some_schema', table_name 'some_table'); CREATE FOREIGN TABLE 中声明的列数据类型和其他性质必须要匹配实际的远程表。列名也必须匹配，不过 也可以为个别列附上 column_name 选项以表示它们在远程服务器上对应哪个列。在很多情况中，要手工构造外部表 定义，使用 IMPORT FOREIGN SCHEMA 会更好。 56.5 插件 kingbase_fdw 的卸载 在 ksql 中运行： DROP EXTENSION kingbase_fdw; 444 第 56 章 KINGBASE_FDW 56.6 插件 kingbase_fdw 的升级 kingbase_fdw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 445 第 57 章 KINGBASE_VERSION 57章 kingbase_version 第 57.1 插件 kingbase_version 简介 kingbase_version 支持查询 KingbaseES 的构建版本号。 • 插件名为 kingbase_version • 插件版本 V1.0 57.2 插件 kingbase_version 加载方式 该插件为内置加载。 57.3 插件 kingbase_version 参数配置 无需配置任何参数。 57.4 插件 kingbase_version 使用方法 57.4.1 bulid_version 获取 kingbase 的构建版本号。 语法 bulid_version( ) RETURNS text。 示例 446 第 57 章 KINGBASE_VERSION TEST=# select build_version(); build_version --------------4c5e415 (1 行记录) 57.5 插件 bulid_version 卸载方法 无 57.6 插件 bulid_version 升级方法 bulid_version 扩展插件通常随 KingbaseES 安装包一并升级。通常情况下用户无法单独升级插件。 447 第 58 章 KTRACK 58章 ktrack 第 58.1 插件 ktrack 简介 ktrack 是 KingbaseES 的一个扩展插件，作为块级别增量备份引擎为物理备份工具提供基础支持。 启用插件后，插件功能自动运行，并提供 SQL 函数供查询使用。 • 插件名为 ktrack • 插件版本 V2.2 58.2 插件 ktrack 加载方式 将 ktrack 追加到 kingbase.conf 的 shared_preload_libraries 配置项中，同时新增一行设置 ktrack.map_size，重 启数据库后执行 create extension ktrack; 语句。 shared_preload_libraries = 'ktrack' ktrack.map_size = 1024 58.3 插件 ktrack 的参数配置 ktrack 使用 ktrack.map_size 设置的值设定存储块变化信息的文件的大小（单位为 MB），最大为 1024；改变该 值需要重启数据库，之前存储的块变化信息会丢失（该值不变时重启数据库信息不会丢失）。 58.4 插件 ktrack 的使用方法 启用 ktrack 插件后，可使用如下四个 SQL 函数做查询。 • ktrack_version() : 返回 ktrack 的版本信息 448 第 58 章 KTRACK • ktrack_init_lsn() : 返回 ktrack 开始记录块变化信息的 LSN • ktrack_get_pagemapset() : 返回自指定 LSN 以来发生改变的块信息 • ktrack_get_change_stat() : 返回自指定 LSN 以来发生改变的块信息的统计信息 select ktrack_version(); ktrack_version ---------------2.2 (1 row) select ktrack_init_lsn(); ktrack_init_lsn ----------------0/3000028 (1 row) select path, pagecount, pagemap from ktrack_get_pagemapset('0/2417EBA8'); path | pagecount | pagemap ------------------+-----------+-------------------------base/15900/49171 | 1 | \x0100000000000000000000 (1 row) select * from ktrack_get_change_stat('0/2417EBA8'); files | pages | size, MB -------+-------+-----------------------1 | 1 | 0.03125000000000000000 (1 row) 58.5 插件 ktrack 卸载方法 连接到数据库执行 DROP 插件操作，删除 kingbase.conf 文件中 shared_preload_libraries 内的 ktrack 参数， 删除 ktrack.map_size 设置，重启数据库。 drop extension ktrack; shared_preload_libraries = '' 58.6 插件 ktrack 升级方法 ktrack 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 449 第 59 章 LO 59章 lo 第 59.1 插件 lo 简介 在使用大对象（BLOB）数据时，JDBC/ODBC 等标准接口假设 BLOB 数据直接存储在对应表中，所以在数据 被修改或删除时旧的 BLOB 数据也会被删除。而在 KingbaseES 中，使用 lo 方式存储的大对象数据是独立的对象， 有独立的存储。表中的数据行通过 OID 引用 lo 数据，并且支持多行数据引用同一个 lo 数据，所以在行数据删除时 系统并不会自动删除 lo 数据。所以在使用标准 JDBC/ODBC 接口时 lo 数据并不会被自动删除，导致遗留了没有引 用的“孤儿”lo 数据。 lo 插件提供了触发器在引用了 lo 数据的行被修改或删除时自动调用 lo_unlink，同时提供了包装 oid domain 的 lo 数据类型。注意 lo 触发器不一定要在用 lo 数据类型的情况下才可以使用，lo 数据类型只是用来方便跟踪系统中使 用 lo 触发器管理的 lo 数据。 • 插件名为 lo • 插件版本 V1.1 59.2 插件 lo 加载方式 CREATE EXTENSION lo; 59.3 插件 lo 的参数配置 无需配置任何参数。 450 第 59 章 59.4 LO 插件 lo 的使用方法 CREATE TABLE image (title text, raster lo); CREATE TRIGGER t_raster BEFORE UPDATE OR DELETE on image FOR EACH ROW EXECUTE FUNCTION lo_manage(raster); lo 触发器在 DROP TABLE 或 TRUNCATE TABLE 时不会生效；有些应用会自动创建和管理表，这种情况下 触发器也不会被创建。在以上这些情况下还是可能产生“孤儿”lo。定期运行 vacuumlo 可以帮助处理这些 lo 对象。 59.5 插件 lo 卸载方法 DROP EXTENSION lo; 59.6 插件 lo 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION lo UPDATE TO '1.1'; 451 第 60 章 MYSQL_FDW 60章 mysql_fdw 第 60.1 插件 mysql_fdw 简介 mysql_fdw 是 KingbaseES 的一个扩展插件，它提供了一个外部数据包装器，可以方便高效的访问 MySQL 数据 库。 要使用 mysql_fdw 来为远程访问做准备： • 使用 CREATE EXTENSION 来安装 mysql_fdw 扩展。 • 使用 CREATE SERVER 创建一个外部服务器对象，它用来表示你想连接的每一个远程数据库。指定除了 user 和 password 之外的连接信息作为该服务器对象的选项。 • 使用 CREATE USER MAPPING 创建一个用户映射，每一个用户映射都代表你想允许一个数据库用户访问一 个外部服务器。指定远程用户名和口令作为用户映射的 user 和 password 选项。 • 为每一个你想访问的远程表使用 CREATE FOREIGN TABLE 或者 IMPORT FOREIGN SCHEMA 创建一个 外部表。外部表的列必须匹配被引用的远程表。但是, 如果你在创建外部表对象的 OPTIONS 中指定了正确的 SERVER 名称，你可以使用不同于远程表的表名或列名。 现在只需要从一个外部表使用 SELECT 语句来访问存储在它的 mysql 中的数据。也可以使用 INSERT、UPDATE 或 DELETE 修改远程表（当然，在用户映射中已经指定的远程用户必须具有做这些事情的权限）。 通常推荐一个外部表的列被声明为与被引用的远程表列完全相同的数据类型和排序规则（如果可用）。尽管 mysql_fdw 目前已经能够容忍在需要时执行数据类型转换，但是当类型或排序规则不匹配时可能会发生奇怪的语义 异常，因为远程服务器解释 WHERE 子句时可能会与本地服务器有所不同。 • 插件名为 mysql_fdw • 插件版本 V1.1 60.2 插件 mysql_fdw 加载方式 使用 CREATE EXTENSION mysql_fdw; 加载插件。 452 第 60 章 MYSQL_FDW CREATE EXTENSION mysql_fdw; 60.3 插件 mysql_fdw 的参数配置 无需配置任何参数。 60.4 插件 mysql_fdw 的使用方法 60.4.1 连接 mysql_fdw 会缓存与 MySQL 的连接，因为每个查询创建 MySQL 的成本很高。当 KingbaseES 会话结束时，所 有连接都将自动关闭。 60.4.2 列 定义外部表时，MySQL 表的列将按定义顺序映射到 KingbaseES 外部表的列上。 mysql_fdw 将只在发送到 MySQL 查询语句中包含在 KingbaseES 查询实际中需要的那些列。 60.4.3 数据类型 必须使用 mysql_fdw 可以转换的数据类型定义 KingbaseES 列（参考下面的类型转换表）。如果 MySQL 值超 过 KingbaseES 列的大小（如 varchar 列的长度或者最大值），将会报错。 下面这些类型之间的转换将由 mysql_fdw 自动处理： 453 第 60 章 MYSQL_FDW 表 60.4.1: mysql_fdw 支持的类型转换 Mysql type Possible Kingbase types TINYINT int2 SMALLINT int4 INT int8 FLOAT float4 DOUBLE float8, numeric STRING varchar, bpchar, text, json, name,anyenum DATE date TIMESTAMP time, timestamp, timestamptz BLOB bytea LONG bit 如果一个数字被转换成布尔值，0 意味着 false，其他的都是 true。 60.4.4 CREATE SERVER 使用 CREATE SERVER 创建一个外部服务器对象，它用来表示你想连接的每一个远程数据库。指定除了 user 和 password 之外的连接信息作为该服务器对象的选项。 • host: MySQL 服务器的 IP 地址，默认是 127.0.0.1。 • port: MySQL 服务器的端口，默认是 3306。 • secure_auth: 启用或者禁用安全连接，默认是启用。 • init_command: 连接 MySQL 服务器所执行的 SQL 语句。 • use_remote_estimate: 控制 mysql_fdw 是否向远程发出 explain 命令来获取代价估算，默认不开启。 • reconnect: 如果发现已有连接丢失，启用或禁用 MySQL 的自动连接。默认是禁用自动连接。 • ssl_key: 客户端私钥证书的路径。 • ssl_cert: 客户端公钥证书的路径。 • ssl_ca: 所信任的 CA 证书的路径。 • ssl_capath: 所信任的 SSL CA 证书所在目录的路径名。 • ssl_cipher: SSL 加密所允许的加密列表。 454 第 60 章 MYSQL_FDW • fetch_size: 该选项指每次获取操作中应该获取的行数，它可以由外表或者外部服务器来指定，表上的设置该值 能够覆盖服务器上的值，默认是 100。 60.4.5 CREATE USER MAPPING 使用 CREATE USER MAPPING 创建一个用户到外部 mysql 服务器的一个用户映射。 OPTIONS 如下： • username: 连接 MySQL 数据库的用户名。 • password: 对用连接用户的密码。 60.4.6 CREATE FOREIGN TABLE 使用 CREATE FOREIGN TABLE 创建一个用户到外部 mysql 服务器的一个用户表映射。 OPTIONS 如下： • dbname: MySQL 数据库的数据库名。 • table_name: MySQL 数据库中的表名，默认与外表名相同。 • max_blob_size: 最大的 blob size，超过 64KB 后将被截断，取值范围为 0-64KB； • fetch_size: 同 server 的参数，默认值 100。 60.4.7 WHERE 条件和 ORDER BY 子句 KingbaseES 将使用 WHERE 子句的所有适用部分作为扫描的过滤器。mysql_fdw 构造的 MySQL 查询将包 含与这些筛选条件相对应的 WHERE 子句，只要这样的条件可以安全地转换为 MySQL SQL。这个特性，也称为 WHERE 子句的下推，可以极大地减少从 MySQL 检索到的行数，并使 MySQL 的优化器能够选择一个好的计划来 访问所需的表。 60.4.8 外部表之间的 JOIN mysql_fdw 可以向下推连接到 MySQL 服务器，也就是说，来自同一个 MySQL 服务器的两张外部表之间的 JOIN 被下推到同一个外部服务器，而不是返回两张表的所有行并在本地服务器执行 JOIN。 发生这种情况时有一些限制： • 两个表必须在同一外部服务器上定义。 • 目前只包括关系操作符和算术操作符的 JOIN 连接被下推。 • JOIN 必须在 SELECT 语句中。 455 第 60 章 MYSQL_FDW • mysql_fdw 必须能够下推所有 JOIN 条件和 WHERE 子句。 • 只支持内，左/右外连接，暂不支持全外，半和反连接。 • 当连接子句中含有外部表与本地表混合 JOIN 时，优先外表与外表做连接，本地表与本地表做连接。 使用 ANALYZE 收集两个外部表的表统计信息以确定最佳 JOIN 策略非常重要。 60.4.9 聚合函数的下推 mysql_fdw 将聚合函数下推至远端 MySQL 服务器，而不是获取所有行在本地执行聚合函数。 发生这种情况时有一些限制： -目前下推的聚合函数只包括：max，min，sum，avg 和 count 聚合函数，从而避免了下推了 MySQL 中不支持 的聚合函数。 -聚合函数中的 filters 和 order by 不会被下推。 -当聚集函数中含有其他聚集函数如：random() 不会下推 60.4.10 修改外部数据 mysql_fdw 支持在外部表上插入、更新和删除。 要使 INSERT/UPDATE 和 DELETE 工作，必须设置 MySQL 表第一列必须唯一。这些列用于标识外部表行， 因此请确保列上都设置了该选项。 如果在 INSERT 过程中省略外表列，则该列将设置为 KingbaseES 外表的 DEFAULT 子句中定义的值（如果没有 DEFAULT 子句，则设置为 NULL）。不使用相应 MySQL 列上的默认子句。如果 KingbaseES 外部表不包含 MySQL 表的所有列，则 MySQL DEFAULT 子句将用于外部表定义中未包含的列。 当修改外部数据工作时，性能不是特别好，特别是当许多行受到影响时，因为（由于外部数据包装器的工作方 式）必须单独处理每一行。 60.4.11 EXPLAIN KingbaseES 的 EXPLAIN 将显示实际发出给 MySQL 的查询。EXPLAIN VERBOSE 将显示 MySQL 的执行计 划。 60.4.12 支持 IMPORT FOREIGN SCHEMA 以下是导入外部 SCHEMA 支持的选项： • schema_case：控制导入模式名的大小写转换 可能的值为： 456 第 60 章 MYSQL_FDW • keep：保留 MySQL 的名字，通常用大写,（这是默认值）。 • lower：将所有表名和列名转换为小写。 • smart：只翻译在 Mysql 中都是大写的名称。 • import_default：用于判断是否导入默认值。 默认值是 false，即不导入 MySQL 的默认值。 • import_not_null：用于判断是否导入 NOT NULL 默认值是 false，即不导入 NOT NULL 约束。 MYSQL SCHEMA 名称必须与 MySQL 中的名称完全相同。由于 KingbaseES 在处理之前将名称转换为小写， 因此必须用双引号保护 SCHEMA 名称（例如“SCOTT”）。 LIMIT TO 或 EXCEPT 子句中的表名必须按照上述大小写折叠后在 KingbaseES 中出现的方式编写。 60.5 插件 mysql_fdw 的卸载方法 使用 DROP EXTENSION mysql_fdw; 卸载插件. DROP EXTENSION mysql_fdw; 60.6 插件 mysql_fdw 升级方法 mysql_fdw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 457 第 61 章 MYSQL_JSON 61章 mysql_json 第 61.1 插件 mysql_json 简介 mysql_json 是 KingbaseES 的一个扩展插件，主要定义了兼容 mysql 的 json 系列操作函数。 • 插件名为 mysql_json • 插件版本 V1.0.0 61.2 插件 mysql_json 加载方式 KingbaseES 默认不加载 mysql_json 扩展插件，请使用以下命令加载插件： CREATE EXTENSION mysql_json; 注意： 创建扩展前，需要关闭禁用多态函数参数，执行’set ora_forbid_func_polymorphism to off;’ 。 61.3 插件 mysql_json 的参数配置 无需配置任何参数。 61.4 插件 mysql_json 的使用方法 创建插件后提供一组 json 操作函数。 下表列出了 mysql_json 插件支持的函数并简要的表述了它们。 458 第 61 章 MYSQL_JSON 表 61.4.1: mysql_json 支持的类型转换 函数 简介 json_array_append 末尾添加数组元素 json_array_insert 插入数组元素 json_contains 判断是否包含某个 json 值 json_contains_patch 判断某个路径下是否包含 json 值 json_depth 返回 json 文档的最大深度 json_extract 提取 json 值 json_insert 插入新值，但不替换存在的旧值 json_keys 提取 json 中的键值为 json 数组 json_length 返回 json 文档的长度 json_merge_patch 多个 json 进行合并，相同键名，后面的覆盖前面的。 json_merge_preserve 多个 json 进行合并，相同键名，则键值组成新的对象。 json_quote 将 json 转成 json 字符串类型 json_remove 删除 json 数据 json_replace 替换值，只替换已存在的旧值 json_search 按给定字符串关键字搜索 json，返回匹配的路径 json_set 设置值（替换旧值，并插入不存在的新值） json_type 返回 json 值的类型 json_unquote 去除 json 字符串的引号，将值转成 string 类型 json_valid 判断是否为合法 json 文档 61.4.1 json_array_append 函数 功能描述 将值附加到 JSON 文档中指定数组的末尾并返回结果。 语法格式 459 第 61 章 MYSQL_JSON JSON_ARRAY_APPEND(json_doc, path, val[,path, val]...) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名，字符串符合 json 结构 path 指定路径，可以指定多个路径，需要符合 jsonpath 格式。注：只有指定 path 为 $/$[0] 时为有效格 式。 待插入的值，可以为列名，给定值可以为任意类型 val 返回值说明 • NULL：json_doc 或 path 参数中任何一个为 NULL，则返回 NULL； • JSON 类型 INTEGER：json_doc 为 JSON 类型 INTEGER，指定 path 不存在。 • JSON 类型 DOUBLE：json_doc 为 JSON 类型 DOUBLE，指定 path 不存在。 • JSON 类型 UNSIGNED INTEGER：json_doc 为 JSON 类型 UNSIGNED INTEGER，指定 path 不存在。 • JSON 类型 DECIMAL：json_doc 为 JSON 类型 DECIMAL，指定 path 不存在。 • JSON 类型 STRING：json_doc 为 JSON 类型 STRING，指定 path 不存在。 • JSON 类型 BOOLEAN：json_doc 为 JSON 类型 BOOLEAN，指定 path 不存在。 • JSON 类型 ARRAY：json_doc 为有效 JSON 格式，指定 path 存在。 • JSON 对象：json_doc 为 JSON 对象，指定 path 不存在。 注：如果 JSON 文档不是有效的 JSON 格式或者 path 不符合路径表达式，或者 path 中包含 * 或 ** 通配符， 则返回错误。 示例 select json_array_append('1', '$[0]', '{"a"：1}'); 61.4.2 json_array_insert 函数 功能描述 更新 JSON 文档，将值插入到 JSON 文档中指定数组中，并返回修改后的文档。指定多个 path 的时候，按照从 左到右顺序，每插入一个值，重新计算文档结构，后续 path 对应新文档中 path。 语法格式 460 第 61 章 MYSQL_JSON JSON_ARRAY_INSERT(json_doc, path,val[, path,val]...) 参数说明 参数名称 描述 json_doc 更新字符串，可以为列名, 字符串符合 json 结构 path 指定路径，可以指定多个路径；只能使用 json 数组类型 path 结构，其余方式报错。 val 待插入的值，可以为列名，给定值可以为任意类型 返回值说明 • NULL：json_doc 或 path 参数中任何一个为 NULL，则返回 NULL。 • JSON 类型 INTEGER：json_doc 为 JSON 类型 INTEGER。 • JSON 类型 DOUBLE：json_doc 为 JSON 类型 DOUBLE。 • JSON 类型 UNSIGNED INTEGER：json_doc 为 JSON 类型 UNSIGNED INTEGER。 • JSON 类型 DECIMAL：json_doc 为 JSON 类型 DECIMAL。 • JSON 类型 STRING：json_doc 为 JSON 类型 STRING。 • JSON 类型 BOOLEAN：json_doc 为 JSON 类型 BOOLEAN。 • JSON 类型 ARRAY：json_doc 为有效 JSON 格式，指定 path 存在。 注：如果 JSON 文档不是有效的 JSON 格式或者 path 不符合路径表达式，或者 path 中包含 * 或 ** 通配符， 则返回错误。 示例 select json_array_insert('[]', '$[0]', '{"a"：1}'); 61.4.3 json_contains 函数 功能描述 不指定路径时查找在 target 文档最外层是否包含 candidate；指定路径时查找在 target 文档的 path 路径下，是 否包含 candidate。 语法格式 JSON_CONTAINS(target, candidate[,path]) 参数说明 461 第 61 章 MYSQL_JSON 参数名称 描述 target 待检查目标字符串，可以为列名，字符串需要符合 json 结构 candidate 指定查找字符串，可以为列名，字符串需要符合 json 结构 path target 中路径或 NULL。 注：按照入参顺序检查参数格式，当参数为 NULL 时，不检查后续格式，直接返回 NULL；但 target 和 candidate 不符合 json 格式时，返回错误。 返回值说明 • NULL：target 或 candidate 为 NULL，或 target 中指定的 path 路径不存在 • boolean：target 中包含 candidate 返回 true，否则返回 false 注：如果 target 或 candidate 不是有效 JSON 格式，则返回错误。 示例 select json_contains('"abc"', '"abc"', '$[0]'); 61.4.4 json_contains_patch 函数 功能描述 返回 JSON 文档中是否包含指定 path。 语法格式 JSON_CONTAINS_PATH(json_doc, one_or_all, path[, path] ...) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名，字符串符合 json 结构。 one_or_all One: 如果文档中至少存在一个路径返回 true，否则返回 false；all: 如果所有路径都存在于文档中返回 true，否则返回 false。 path 至少指定一个 path，可以指定多个 path。path 中可以使用 */**通配符，*代表对象节点，**代表数 组。 返回值说明 • NULL：json_doc 或 path 为 NULL; 462 第 61 章 MYSQL_JSON • boolean： – one：如果文档中至少存在一个路径返回 true，否则返回 false – all：如果所有路径都存在于文档中返回 true，否则返回 false。 注：如果参数不是有效 JSON 格式，则返回错误。 示例 select json_contains_path('[1,2,[3,4,5,6]]', 'all', NULL); 61.4.5 json_depth 函数 功能描述 返回 JSON 文档的最大深度。 • 非空数组/非空 json 对象：非最底层，每加一层嵌套，深度加一。 • 当最底层为空数组/空对象深度累加 1； • 非空数组/非空对象深度累加 2； • 当 json 文档有多个分支时，最大深度分支作为 json 文档深度； 语法格式 JSON_DEPTH(json_doc) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名。字符串需符合 json 结构，json_doc 字符串最大长度 1G 返回值说明 • NULL：json_doc 为 NULL; • Integer： – JSON_DOC 为有效的 json 格式, 返回 json_doc 最大深度； – 空数组/空对象/标量均返回 1； 注：如果参数不是有效 JSON 格式，则返回错误。 示例 select json_depth('{"a"：1, "b"：2}'); 463 第 61 章 MYSQL_JSON 61.4.6 json_extract 函数 功能描述 返回 JSON 指定 path 对应的值。 语法格式 JSON_EXTRACT(json_doc, path[, path] ...) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名，字符串符合 json 结构。json_doc 的长度最长不能超过 1G。 path 指定的路径，可以指定一个，也可以指定多个。 返回值说明 • NULL：json_doc 或任何指定 path 为 NULL；或者指定的 path 全部不存在 • JSON 类型 INTEGER：指定 path 对应值为 integer 类型 • JSON 类型 DOUBLE：指定 path 对应值为 double 类型 • JSON 类型 UNSIGNED INTEGER：指定 path 对应值为 unsigned integer 类型 • JSON 类型 DECIMAL：指定 path 对应值为 decimal 类型 • JSON 类型 STRING：指定 path 对应值为 string 类型 • JSON 类型 BOOLEAN：指定 path 对应值为 boolean 类型 • JSON 类型 ARRAY：指定 path 对应值为 array 类型；或者指定多个 path 返回多个结果，使用 array 返回。 • JSON：指定 path 对应值为 json 类型 示例 select json_extract('"1.0"', '$**[0]'); 61.4.7 json_insert 函数 功能描述 更新 JSON 文档，将其插入文档中的数组中并返回修改后的文档。 语法格式 464 第 61 章 MYSQL_JSON JSON_INSERT(json_doc, path,val[,path, val]...) 参数说明 参数名称 描述 json_doc 待变更的 Json 文档； path 更新 JSON 文档路径; val 更新路径对应的值; 返回值说明 • NULL：json_doc 参数或任何指定 path 为 NULL，返回 NULL；当指定 path 为根目录 ($), 并且指定值为 NULL，返回 NULL； • json 基本类型/标量：更新结果为 json 基本类型/标量，则返回 json 基本类型/标量； • json 类型数组：更新结果为 json 数组，则返回 json 基本 json 数组； • json 对象；更新结果为 json 对象，则返回 json 基本 json 对象； 注：如果 json_doc 参数不是有效的 JSON 文档，或者任何 path 参数不是有效的 path 表达式，或者包含 * 或 ** 通配符，则会发生错误。 示例 select json_insert('[]', '$[last]', 1); 61.4.8 json_keys 函数 功能描述 更新 JSON 文档，将其插入文档中的数组中并返回修改后的文档。 语法格式 JSON_INSERT(json_doc, path,val[,path, val]...) 参数说明 465 第 61 章 MYSQL_JSON 参数名称 描述 json_doc 待变更的 Json 文档； path 更新 JSON 文档路径; val 更新路径对应的值; 返回值说明 • NULL：json_doc 参数或任何指定 path 为 NULL，返回 NULL；当指定 path 为根目录 ($), 并且指定值为 NULL，返回 NULL； • json 基本类型/标量：更新结果为 json 基本类型/标量，则返回 json 基本类型/标量； • json 类型数组：更新结果为 json 数组，则返回 json 基本 json 数组； • json 对象；更新结果为 json 对象，则返回 json 基本 json 对象； 注：如果 json_doc 参数不是有效的 JSON 文档，或者任何 path 参数不是有效的 path 表达式，或者包含 * 或 ** 通配符，则会发生错误。 示例 select json_insert('[]', '$[last]', 1); 61.4.9 json_length 函数 功能描述 返回 json 文档的长度，如果不给定 path，返回最上层 Key 个数；如果给定 path，返回指定 path 层 Key 个数。 • 标量：长度为 1； • 数组：长度为数组元素的数量； • JSON 对象：长度为 JSON 的成员数量。 语法格式 JSON_LENGTH(json_doc[,path]) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名；字符串符合 json 结构。json_doc 字符串最大长度 1G path 指定的路径 466 第 61 章 MYSQL_JSON 返回值说明 • NULL：JSON_DOC 为空，或 path 指定路径不存在 • Integer：如果不给定 path，返回 json_doc 文档长度。 注：如果参数不是有效 JSON 格式或给定 path 格式错误，则返回错误。 示例 select json_length('["1", {"a"：1}, true, null, false]'); 61.4.10 json_length 函数 功能描述 返回 json 文档的长度，如果不给定 path，返回最上层 Key 个数；如果给定 path，返回指定 path 层 Key 个数。 • 标量：长度为 1； • 数组：长度为数组元素的数量； • JSON 对象：长度为 JSON 的成员数量。 语法格式 JSON_LENGTH(json_doc[,path]) 参数说明 参数名称 描述 json_doc 待测试的字符串，可以为列名；字符串符合 json 结构。json_doc 字符串最大长度 1G path 指定的路径 返回值说明 • NULL：JSON_DOC 为空，或 path 指定路径不存在 • Integer：如果不给定 path，返回 json_doc 文档长度。 注：如果参数不是有效 JSON 格式或给定 path 格式错误，则返回错误。 示例 select json_length('["1", {"a"：1}, true, null, false]'); 467 第 61 章 MYSQL_JSON 61.4.11 json_merge_preserve 函数 功能描述 合并两个或多个 JSON 文档并返回合并的结果。 语法格式 JSON_MERGE_PRESERVE(json_doc, json_doc[,json_doc]...) 参数说明 参数名称 描述 json_doc 合并字符串，可以为列名；字符串符合 json 结构 返回值说明 • NULL：如果任何参数为 NULL，或者指定的 path 不存在，则返回 NULL； • JSON 类型数组：如果多个 json_doc 都不是 json 对象，返回 json 类型数组 • JSON 对象：所有 json_doc 都是 json 对象，返回 json 对象。 注：如果任何参数不是有效 JSON 格式，则返回错误。 示例 select json_merge_preserve('1', '[1,2,3]'); 61.4.12 json_merge_preserve 函数 功能描述 将字符串用双引号引起来并转义内部引号和其他字符来将字符串转换为 JSON 值，然后将结果作为 JSON 格式 字符串返回。 语法格式 JSON_quote(string) 参数说明 参数名称 描述 strng 待转换字符串，可为字符串，NULL 返回值说明 468 第 61 章 MYSQL_JSON • NULL：如果 string 为 NULL，则返回 NULL； • JSON 类型 string：如果输入为字符串，则返回 json 格式字符串。 示例 select json_quote('true'); 61.4.13 json_remove 函数 功能描述 从 JSON 文档中删除数据并返回结果。 语法格式 JSON_REMOVE(json_doc,path[, path]...) 参数说明 参数名称 描述 json_doc 要查询的 Json 文档； path 指定删除路径，可以指定多个路径。 返回值说明 • NULL：json_doc，path 参数中任何一个为 NULL，则返回 NULL; • json 基本类型/标量：更新结果为 json 基本类型/标量，则返回 json 基本类型/标量； • json 类型数组：更新结果为 json 数组，则返回 json 基本 json 数组； • json 对象；更新结果为 json 对象，则返回 json 基本 json 对象； 注：如果 json_doc 参数不是有效的 JSON 文档，或者任何 path 参数不是有效的 path 表达式，或者是 $ 或包含 * 或 ** 通配符，则会发生错误。 示例 select json_remove('12345', '$[0]', '$[1]'); 61.4.14 json_remove 函数 功能描述 替换 JSON 文档中的现有值并返回结果。 469 第 61 章 MYSQL_JSON 语法格式 JSON_REPLACE(json_doc, path,val[,path, val]...) 参数说明 参数名称 描述 json_doc 要更新的 Json 文档； path 更新 JSON 文档路径； val 更新路径对应的值，必须符合 json 格式； 返回值说明 • NULL：json_doc 参数或任何指定 path 为 NULL，返回 NULL；当指定 path 为根目录 ($), 并且指定值为 NULL，返回 NULL； • json 基本类型/标量：更新结果为 json 基本类型/标量，则返回 json 基本类型/标量； • json 类型数组：更新结果为 json 数组，则返回 json 基本 json 数组； • json 对象；更新结果为 json 对象，则返回 json 基本 json 对象； 注：如果 json_doc 参数不是有效的 JSON 文档或任何 path 参数不是有效的 path 表达式或包含 * 或 ** 通配 符，则会发生错误。 示例 select json_replace('123', '$.a', 1); 61.4.15 json_search 函数 功能描述 返回符合查询条件的 key 对应的 JSON 路径所组成的数组，若不存在，则返回 NULL。 语法格式 JSON_SEARCH(json_doc, one_or_all, search_str[,escape_char[, path]...]) 参数说明 470 第 61 章 MYSQL_JSON 参 数 描述 名称 json_doc要查询的 Json 文档； one_or_all 查询的终止条件 one：搜索在第一个匹配项后终止，并返回一个路径字符串。all：搜索返回所有匹配的路 径字符串，因此不包括重复的路径。如果有多个字符串，它们将自动包装为一个数组。数组元素的顺序是 不确定的. search_str 搜索参数，在 search_str 中，通配符% 和 _ 可以如同在 LIKE 上一样运行，其中% 用于匹配多个字符 （包括 0 个），_ 则仅可匹配一个字符； 指定转义符，escape_char 参数指定时要求必须是常量（为空或者一个字符），当 escape_char 参数为 es- cape_char NULL 或者不指定的情况下，系统默认使用作为转义字符； path 指定检索路径，可以指定多个路径 返回值说明 • NULL：json_doc，search_str，或 path 参数中任何一个为 NULL，则返回 NULL; 文档中不存在 path, 返回 NULL;search_str 未找到, 返回 NULL; • json 类型 ARRAY：返回多个 key 列表； • json 类型 String：返回单个 key； 示例 select json_search('"abc"', 'all', 'abc'); 61.4.16 json_set 函数 功能描述 在 JSON 文档中插入或更新数据并返回结果。 语法格式 JSON_SET(json_doc, path,val[,path, val]...) 参数说明 471 第 61 章 MYSQL_JSON 参数名称 描述 json_doc 要查询的 Json 文档； path 更新 JSON 文档路径 val 更新路径对应的值 返回值说明 • NULL：json_doc 参数或任何指定 path 为 NULL，返回 NULL；当指定 path 为根目录 ($), 并且指定值为 NULL，返回 NULL； • json 基本类型/标量：更新结果为 json 基本类型/标量，则返回 json 基本类型/标量； • json 类型数组：更新结果为 json 数组，则返回 json 基本 json 数组； • json 对象；更新结果为 json 对象，则返回 json 基本 json 对象； 注：如果 json_doc 参数不是有效的 JSON 文档，或者任何 path 参数不是有效的 path 表达式或包含 * 或 ** 通 配符，则会发生错误。 示例 select json_set('123', '$[1]', 1); select json_set('[]', '$[0]', json_object('a', 1)); set @js = '[1,2,3,4]';select json_set(@js, '$[last]', 1); set @js = '{}';select json_set(@js, '$[last]', 1); set @js = '{"a"：{"b"：1}, "c"：2}'; select json_set(@js, '$.d', json_array(1,2,3), '$.a.c', json_array(1,2,3)); 61.4.17 json_type 函数 功能描述 返回 JSON 值类型 语法格式 JSON_TYPE(json_val) 参数说明 参数名称 描述 json_val 待测试的字符串，可以为列名；字符串符合 json 结构； 472 第 61 章 MYSQL_JSON 返回值说明 • JSON 类型：OBJECT，ARRAY，BOOLEAN，NULL • 数字类型：INTEGER，DOUBLE，DECIMAL • 时间类型：DATETIME，DATE，TIME • 字符串类型：STRING • 二进制类型：BLOB，BIT • 其他类型：OPAQUE 注：如果参数不符合 json 结构，则返回错误。 示例 select json_type('123456789012345678901234567890'); select json_type('"a"'); select json_type('[]'); select json_type('[1,"a", true, null]'); 61.4.18 json_unquote 函数 功能描述 取消引用 JSON 值，并以字符串的形式返回。 语法格式 JSON_unquote(json_value) 参数说明 参数名称 描述 json_value 待测试的字符串，可以为列名；字符串符合 json 结构。 返回值说明 • NULL：如果 json_value 为 NULL，则返回 NULL • string 类型字符串：如果 json_doc 为有效的 json 格式，则返回转换之后的字符串。 注：如果该值以双引号开头和结尾，但不是有效的 JSON 字符串，则返回错误。 示例 473 第 61 章 MYSQL_JSON select json_unquote('"a"'); select json_unquote("a"); select json_unquote('["a", "b", "c"]'); select json_unquote('[{"a"：1}]'); select json_unquote('{"a"：1, "b"：{}}}'); 61.4.19 json_valid 函数 功能描述 判断 val 是否有良好的 json 结构。 语法格式 JSON_VALID(val) 参数说明 参数名称 描述 val 待测试的字符串，可以为列名，数据类型可以为字符串、数字或空值。 返回值说明 • boolean 类型：合法 json 格式返回 true，非法 json 格式返回 false， • NULL：参数为 NULL 则返回 NULL 示例 select json_valid('1'); select json_valid('"aa"'); 61.5 插件 mysql_json 的卸载方法 通过 drop extension 来卸载插件。 DROP EXTENSION mysql_json; 474 第 61 章 MYSQL_JSON 61.6 插件 mysql_json 升级方法 mysql_json 扩展插件随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 475 第 62 章 ORACLE_FDW 62章 oracle_fdw 第 62.1 插件 oracle_fdw 简介 oracle_fdw 是 KingbaseES 的一个扩展插件，它提供了一个外部数据包装器，可以方便高效的访问 oracle 数据 库，包括 WHERE 条件和所需列的下推以及全面的 EXPLAIN 支持。 62.2 插件 oracle_fdw 的加载方式 在 ksql 中运行： create extension oracle_fdw 62.3 插件 oracle_fdw 的参数配置 62.3.1 Foreign data wrapper 参数 • nls_lang (可选) 将 Oracle 的 NLS_LANG 环境变量设置为此值。NLS_LANG 的格式为” language_territory.charset” (例如 AMERICAN_AMERICA.AL32UTF8)。这必须与你的数据库编码匹配。如果未设置此值，oracle_fdw 将自动做正确 的事情，如果他不能，则发出警告。仅当你知道自己在做什么时才设置此选项。 62.3.2 Foreign server 参数 • dbserver (必填) 远程数据库的 Oracle 数据库连接字符串. 这个可以是 Oracle 支持的任何形式，只要你的 Oracle 客户端进行了相 应的配置。将此设置为本地 (”BEQUEATH”) 连接的空字符串 476 第 62 章 ORACLE_FDW • isolation_level (可选，默认值是 serializable) 在 Oracle 数据库中使用的事物隔离级别。该值可以是 serializable, read_committed, read_only 请注意，单个 KingbaseES 语句期间可以多次查询 Oracle 表 (例如，在一个 nested loop join 期间)。为了确保不会 出现由并发事务的竞争条件引起的不一致，事务隔离级别必须保证事务读取稳定性。只有 Oraclede SERIALIZABLE 或者 READ ONLY 隔离级别才能保证这一点 不行的是，oracle 的 SERIALIZABLE 实现的相当糟糕，并在意外情况下导致序列化错误 (ORA-08177)，例如插 入到表中。使用 READ COMMITTED 事务可以解决此问题，但存在不一致的风险。如果你想使用它，请检查你的 执行计划是否可以多次执行外部扫描。 • nchar (boolean 类型，可选，默认值是 off) 将此选项设置为 on 会在 Oracle 端选择跟昂贵的字符转换。如果你使用单字节 Oracle 数据库字符集，但 NCHAR 或 NVARCHAR2 列包含数据库字符集中无法表示的字符，则这是必填的 将 nchar 设置为 on 会对性能产生显著的影响，并且会在 Update 语句中导致 ORA-01461 错误，当该语句设置的 字符串超过 2000 字节时 (如果你又 MAX_STRING_SIZE=EXTENDED，则为 16383)。此错误似乎是 Oracle 的错 误。 62.3.3 User mapping 参数 • user (必填) 会话的 Oracle 用户名 如果你不想在 KingbaseES 数据库中存储 Oracle 凭据 (一种简单的方法是使用外部密码存储)，请将其设置为外 部身份验证的空字符串 • password (必填) Oracle 用户的密码 62.3.4 Foreign table 参数 • table (必填) Oracle 表名。此名称必须与 Oracle 系统目录中出现的完全相同，因此通常只包含大写字母 要基于任意 Oracle 查询定义外部表，请将此选项设置为括号中的查询，例如 OPTIONS (table '(SELECT col FROM tab WHERE val = ''string'')') 在这汇总情况下不要设置 scheam 选项 INSERT、UPDATE 和 DELETE 将作用于简单查询中定义的外部表；如 果你想避免这种情况 (或对更复杂的查询造成混淆 Oracle 错误消息)，请使用 table 选项 readonly • dblink (可选) Oracle database link 的名字。这个名称必须与 Oracle 系统目录中出现的完全相同，因此通常只包含大写字母 477 第 62 章 ORACLE_FDW • schema (可选) 表的 scheam。对应访问不属于连接 Oracle 用户的表很有用。此名称必须要 Oracle 系统目录中出现的完全相同， 因此通常只包含大写字母 • max_long (可选，默认值是 32767) Oracle 表中 LONG, LONG RAW, XMLTYPE 类型的列的最大长度。可能的值是 1 到 1073741823 之间的整数 (kingbase 中一个字节的最大大小)。此内存量至少分配两次，因此大量的值将消耗大量内存 • readonly (可选，默认值是 false) INSERT, UPDATE, DELETE 只允许操作这个选项没有被设置成 yes/on/true 的表 • sample_percent (可选，默认值是”100”) 此选项仅影响 ANALYZE 处理，可用于在合理的时间内 ANALYZE 非常大的表 该值必须介于 0.000001 和 100 之间，并定义将随机选择以计算 KingbaseES 表统计信息的 Oracle 表块的百分 比。这是使用 Oracle 中 SAMPLE BLOCK(x) 子句完成的 对于使用 Oracle 查询定义的表，ANALYZE 将失败并出现 ORA-00933，而对于使用复杂 Oracle 视图定义的表， ANALYZE 可能会失败并出现 ORA-01446 • prefetch (可选，默认值是 200) 设置在外部表扫描期间通过 kingbase 与 Oracle 之间单次往返获取的行数。这个是使用 Oracle 行预取实现的。该 值必须介于 0 和 10240 之间，其中零值禁用预取 较高的值可以提高性能，但是会在 kingbase 服务器上使用更多的内存 请注意，由于 Oracle 的限制，如果 Oracle 查询涉及 BLOB, CLOB 或 BFILE 列，行预取将不起作用。因此， 如果你获取许多行，对外部表上此类列的查询将执行的很差 62.3.5 列参数 • key (可选，默认值是 false) 如果被设置成了 yes/on/true，Oracle 表中对应的列被认为是主键列。为了让 UPDATE, DELETE 工作，必须将 所有的主键列都设置上这个选项 • strip_zero (可选，默认值是 false) 如果设置为 yes/on/true，ASCII 0 字符将在传输过程中从字符串中删除。此类字符在 Oracle 中有效，但是在 KingbaseES 中无效，因此再被 oracle_fdw 读取时会导致错误。此选项仅针对 character，character varying 和 text 类型的列 62.4 插件 oracle_fdw 的使用方法 oracle_fdw 需要依赖 GLIBC 2.9 及以上的版本才能运行。 478 第 62 章 ORACLE_FDW 62.4.1 Oracle 权限 Oracle 用户需要 CREATE SESSION 权限和对指定表或视图的 SELECT 权限。 对于 EXPLAIN VERBOSE，用户还需要对 V$SQL 和 V$SQL_PLAN 的 SELECT 权限。 62.4.2 连接 oracle_fdw 会缓存与 oracle 的连接，因为每个查询创建 oracle 的成本很高。当 KingbaseES 会话结束时，所有 连接都将自动关闭。 函数 oraclr_colse_connections() 可用于关闭所有缓存的 oracle 连接。这对于长时间运行的不经常访问外部表的 会话非常有用。可以避免阻塞并开放 oracle 所需的资源。对于正在修改 oracle 数据的事务中不能使用此函数。 62.4.3 列 定义外部表时，oracle 表的列将按定义顺序映射到 kingbase 列。 oracle_fdw 将只在 oracle 查询中包含 kingbase 查询实际需要的那些列。 kingbase 表可以比 oracle 表有更多或更少的列。如果有更多的列，并且使用了这些列，将会收到警告并返回空 值。 如果要更新或删除，请确保在属于表主键的所有列上都设置了 key 选项，否则将导致错误。 62.4.4 数据类型 必须使用 oracle_fdw 可以转换的数据类型定义 kingbase 列（参考下面的类型转换表）。此限制仅在实际使用列 时才强制执行，因此只要不访问不可转换的数据类型，就可以为它们定义伪列（此方法仅适用于 SELECT，而不适 用于修改外部数据）。如果 oracle 值超过 kingbase 列的大小（如 varchar 列的长度或者最大值），将会报错。 下面这些类型之间的转换将由 oracle_fdw 自动处理： 479 第 62 章 ORACLE_FDW 表 62.4.1: oracle_fdw 支持的类型转换 Oracle type Possible Kingbase types CHAR char, varchar, text NCHAR char, varchar, text VARCHAR char, varchar, text VARCHAR2 char, varchar, text, json NVARCHAR2 char, varchar, text CLOB char, varchar, text, json LONG char, varchar, text RAW uuid, bytea BLOB bytea BFILE bytea (read-only) LONG RAW bytea NUMBER numeric, float4, float8, char, varchar, text NUMBER(n,m) with m<=0 numeric, float4, float8, int2, int4, int8, boolean, char, varchar, text FLOAT numeric, float4, float8, char, varchar, text BINARY_FLOAT numeric, float4, float8, char, varchar, text BINARY_DOUBLE numeric, float4, float8, char, varchar, text DATE date, timestamp, timestamptz, char, varchar, text TIMESTAMP date, timestamp, timestamptz, char, varchar, text TIMESTAMP WITH TIME ZONE date, timestamp, timestamptz, char, varchar, text TIMESTAMP WITH LOCAL TIME ZONE date, timestamp, timestamptz, char, varchar, text INTERVAL YEAR TO MONTH interval, char, varchar, text INTERVAL DAY TO SECOND interval, char, varchar, text XMLTYPE xml, char, varchar, text MDSYS.SDO_GEOMETRY geometry 如果一个数字被转换成布尔值，0 意味着 false，其他的都是 true。 480 第 62 章 ORACLE_FDW 插入或更新 XMLTYPE 只适用于不超过 VARCHAR2 数据类型的最大长度（4000 或 32767，取决于 MAX_STRING_SIZE 参数）的值。 oracle_fdw 目前不支持 NCLOB，因为 Oracle 无法自动将其转换为客户端编码。 如果需要的转换的类型不在上述列表中，请在 Oracle 或 KingbaseES 中定义适当的视图。 62.4.5 WHERE 条件和 ORDER BY 子句 kingbase 将使用 WHERE 子句的所有适用部分作为扫描的过滤器。Oracle_fdw 构造的 Oracle 查询将包含与这 些筛选条件相对应的 WHERE 子句，只要这样的条件可以安全地转换为 Oracle SQL。这个特性，也称为 WHERE 子 句的下推，可以极大地减少从 Oracle 检索到的行数，并使 Oracle 的优化器能够选择一个好的计划来访问所需的表。 同样，ORDERBY 子句将尽可能下推到 Oracle。请注意，按字符串排序的 ORDER-BY 条件不会被下推，因为 KingbaseES 和 Oracle 中的排序顺序不能保证相同。 要利用它，请尝试对外部表使用简单的条件。选择与 Oracle 类型相对应的 kingbase 列数据类型，否则条件将无 法转换。 表达式 now()、transaction_timestamp()、current_timestamp、current_date 和 localtimestamp 将被正确翻 译。 EXPLAIN 的输出将显示所使用的 Oracle 查询，因此可以看到哪些条件被转换为 Oracle 以及如何转换。 62.4.6 外部表之间的 JOIN oracle_fdw 可以向下推连接到 oracle 服务器，也就是说，两个外部表之间的连接将导致在 oracle 端执行连接的 单个 oracle 查询。 发生这种情况时有一些限制： • 两个表必须在同一外部服务器上定义。 • 三个或更多表之间的 JOIN 不会被向下推。 • JOIN 接必须在 SELECT 语句中。 • oracle_fdw 必须能够下推所有 JOIN 条件和 WHERE 子句。 • 没有 JOIN 条件的交叉 JOIN 不会向下推。 • 如果一个 JOIN 被下推，ORDER BY 子句将不会被下推。 使用 ANALYZE 收集两个外部表的表统计信息以确定最佳 JOIN 策略非常重要。 62.4.7 修改外部数据 oracle_fdw 支持在外部表上插入、更新和删除。这在默认情况下是允许的，并且可以通过设置 readonly table 选 项来禁用。 481 第 62 章 ORACLE_FDW 要使 UPDATE 和 DELETE 工作，必须设置与 Oracle 表的主键列对应的列的 key column 选项。这些列用于标 识外部表行，因此请确保在属于主键的所有列上都设置了该选项。 如果在 INSERT 过程中省略外表列，则该列将设置为 kingbase 外表的 DEFAULT 子句中定义的值（如果没有 DEFAULT 子句，则设置为 NULL）。不使用相应 Oracle 列上的默认子句。如果 kingbase 外部表不包含 Oracle 表 的所有列，则 Oracle DEFAULT 子句将用于外部表定义中未包含的列。 INSERT、UPDATE 和 DELETE 上的 RETURNING 子句受支持，但 Oracle 数据类型为 LONG 和 LONG RAW 的列除外（RETURNING 子句中 Oracle 不支持这些数据类型）。 用 AFTER 和 FOR 为每行定义的触发器要求外表中没有 Oracle 数据类型为 LONG 或 LONG RAW 的列。这是 因为这样的触发器使用了上面提到的 RETURNING 子句。 当修改外部数据工作时，性能不是特别好，特别是当许多行受到影响时，因为（由于外部数据包装器的工作方 式）必须单独处理每一行。 事务被转发到 Oracle，因此 BEGIN、COMMIT、ROLLBACK 和 SAVEPOINT 按预期工作。不支持涉及 Oracle 的准备语句。有关详细信息，请参见“内部构件”一节。 由于 oracle_fdw 默认情况下使用序列化事务，因此数据修改语句可能导致序列化失败： ORA-08177: can’t serialize access for this transaction 如果并发事务修改了表，并且在长时间运行的事务中更可能发生这种情况。这些错误可以通过它们的 SQLSTATE（40001）来识别。使用 oracle_fdw 的应用程序应该重试由于此错误而失败的事务。 可以使用不同的事务隔离级别，有关讨论，请参阅外部服务器选项。 62.4.8 EXPLAIN kingbase 的 EXPLAIN 将显示实际发出给 Oracle 的查询。EXPLAIN VERBOSE 将显示 Oracle 的执行计划（该 计划不适用于 Oracle server 9i 或更早版本）。 62.4.9 ANALYZE 可以使用 ANALYZE 收集外部表的统计信息。这得到了 oracle_fdw 的支持。 如果没有统计信息，kingbase 就无法估计外部表上查询的行数，这可能会导致选择错误的执行计划。 kingbase 不会像对普通表那样使用 autovacuum 守护进程自动收集外部表的统计信息，因此在创建外部表之后以 及远程表发生重大更改时，对外部表运行 ANALYZE 尤为重要。 分析 Oracle 外部表将导致完整的顺序表扫描。可以使用 table 选项 sample_percent，通过只使用 Oracle 表的一 个示例来加快速度。 62.4.10 PostGIS 支持 数据类型 geometry 仅在安装 PostGIS 时可用。 482 第 62 章 ORACLE_FDW 仅支持二维和三维的 POINT, LINE, POLYGON, MULTIPOINT, MULTILINE, MULTIPOLYGONT 等几何体 类型。不支持空的 PostGIS 几何图形，因为它们在 Oracle Spatial 中没有等效的几何图形。 Oracle SRID 的空值将转换为 0，反之亦然。对于 Oracle SRID 和 PostGIS SRID 之间的其他转换，请创建一个 srid.map 文件在 kingbase 的 share 目录中。该文件的每一行都应包含一个 Oracle SRID 和相应的 PostGIS SRID，用 空格隔开。保持文件小以获得良好的性能。 支持 IMPORT FOREIGN SCHEMA 62.4.11 除了导入外部 SCHEMA 的文档外，还应考虑以下内容： 导入外部 SCHEMA 将为 ALL_TAB_COLUMNS 中的所有对象创建外部表。包括表、视图和物化视图，但不包 括同义词。 以下是导入外部 SCHEMA 支持的选项： • case：控制导入期间表名和列名的大小写折叠 可能的值为： – keep：保留甲骨文中的名字，通常用大写。 – lower：将所有表名和列名转换为小写。 – smart：只翻译在 Oracle 中都是大写的名称（这是默认值）。 • collation：用于 case 选项中的 lower 和 smart 值 默认值是 default，这是数据库的默认排序规则。只支持 sys_catalog SCHEMA 中的排序规则。有关 可能值的列表，请参 sys_collation 目录中的 collname 值。 • dblink：访问 SCHEMA 的 Oracle 数据库链接 此名称必须完全按照 Oracle 系统目录中的名称书写，因此通常仅由大写字母组成。 • readonly：在所有导入的表上设置 readonly 选项 • max_long：在所有导入的表上设置 max_long 选项 • sample_percent：在所有导入的表上设置 sample_percent 选项 • prefetch：在所有导入的表上设置 prefetch 选项 Oracle SCHEMA 名称必须与 Oracle 中的名称完全相同，因此通常使用大写。由于 kingbase 在处理之前将名称 转换为小写，因此必须用双引号保护 SCHEMA 名称（例如“SCOTT”）。 LIMIT TO 或 EXCEPT 子句中的表名必须按照上述大小写折叠后在 kingbase 中出现的方式编写。 请注意，导入外部 SCHEMA 不适用于 oracle server 8i。 注意: oracle_fdw 目前不支持批量导入大量数据，如需导入数据，请使用 oracle 数据导入工具进行操作。在使用 oracle_fdw 时，其内部函数会将 WHERE 子句中的条件进行倒序处理，因此会导致 WHERE 条件的执行顺序与本地 483 第 62 章 ORACLE_FDW 执行的 WHERE 条件顺序相反。如果 WHERE 子句中引用了序列，那么会因条件倒序引发结果与预期不符的情况， 使用需要注意应避开此类情况。 62.4.12 示例 CREATE EXTENSION oracle_fdw; -- TWO_TASK or ORACLE_HOME and ORACLE_SID must be set in the server's environment for this to work CREATE SERVER oracle FOREIGN DATA WRAPPER oracle_fdw OPTIONS (dbserver '//serverip:port/orcl', isolation_ level 'read_committed'); CREATE USER MAPPING FOR PUBLIC SERVER oracle OPTIONS (user 'C##WQ', password '123'); -- drop the Oracle tables if they exist DO $$BEGIN SELECT oracle_execute('oracle', 'DROP TABLE C##WQ.typetest1 PURGE'); EXCEPTION WHEN OTHERS THEN NULL; END;$$; DO $$BEGIN SELECT oracle_execute('oracle', 'DROP TABLE C##WQ.gis PURGE'); EXCEPTION WHEN OTHERS THEN NULL; END;$$; SELECT oracle_execute( 'oracle', E'CREATE TABLE C##WQ.typetest1 (\n' ' id ' NUMBER(5)\n' CONSTRAINT typetest1_pkey PRIMARY KEY,\n' ' c CHAR(10 CHAR),\n' ' nc NCHAR(10),\n' ' vc VARCHAR2(10 CHAR),\n' ' nvc NVARCHAR2(10),\n' ' lc CLOB,\n' ' r RAW(10),\n' ' u RAW(16),\n' ' lb BLOB,\n' ' lr LONG RAW,\n' ' b NUMBER(1),\n' ' num NUMBER(7,5),\n' ' fl BINARY_FLOAT,\n' ' db BINARY_DOUBLE,\n' 484 第 62 章 ORACLE_FDW ' d DATE,\n' ' ts TIMESTAMP WITH TIME ZONE,\n' ' ids INTERVAL DAY TO SECOND,\n' ' iym INTERVAL YEAR TO MONTH\n' ') SEGMENT CREATION IMMEDIATE' ); oracle_execute ---------------(1 row) SELECT oracle_execute( 'oracle', E'CREATE TABLE C##WQ.gis (\n' ' id NUMBER(5) PRIMARY KEY,\n' ' g MDSYS.SDO_GEOMETRY\n' ') SEGMENT CREATION IMMEDIATE' ); oracle_execute ---------------(1 row) -- gather statistics SELECT oracle_execute( 'oracle', E'BEGIN\n' ' DBMS_STATS.GATHER_TABLE_STATS (''C##WQ'', ''TYPETEST1'', NULL, 100);\n' 'END;' ); oracle_execute ---------------(1 row) SELECT oracle_execute( 'oracle', E'BEGIN\n' ' DBMS_STATS.GATHER_TABLE_STATS (''C##WQ'', ''GIS'', NULL, 100);\n' 'END;' ); oracle_execute ---------------(1 row) 485 第 62 章 ORACLE_FDW -- create the foreign tables CREATE FOREIGN TABLE typetest1 ( id integer OPTIONS (key 'yes') NOT NULL, q double precision, c character(10), nc character(10), vc character varying(10), nvc character varying(10), lc text, r bytea, u uuid, lb bytea, lr bytea, b boolean, num numeric(7,5), fl float, db double precision, d date, ts timestamp with time zone, ids interval, iym interval ) SERVER oracle OPTIONS (table 'TYPETEST1'); ALTER FOREIGN TABLE typetest1 DROP q; -- a table that is missing some fields CREATE FOREIGN TABLE shorty ( id integer OPTIONS (key 'yes') NOT NULL, c character(10) ) SERVER oracle OPTIONS (table 'TYPETEST1'); -- a table that has some extra fields CREATE FOREIGN TABLE longy ( id integer OPTIONS (key 'yes') NOT NULL, c character(10), nc character(10), vc character varying(10), nvc character varying(10), lc text, r bytea, u uuid, lb bytea, lr bytea, b boolean, num numeric(7,5), fl float, db double precision, 486 第 62 章 ORACLE_FDW d date, ts timestamp with time zone, ids interval, iym interval, x integer ) SERVER oracle OPTIONS (table 'TYPETEST1'); INSERT INTO typetest1 (id, c, nc, vc, nvc, lc, r, u, lb, lr, b, num, fl, db, d, ts, ids, iym) VALUES ( 1, 'fixed char', 'nat''l char', 'varlena', 'nat''l var', 'character large object', bytea('\xDEADBEEF'), uuid('055e26fa-f1d8-771f-e053-1645990add93'), bytea('\xDEADBEEF'), bytea('\xDEADBEEF'), TRUE, 3.14159, 3.14159, 3.14159, '1968-10-20', '2009-01-26 15:02:54.893532 PST', '1 day 2 hours 30 seconds 1 microsecond', '-6 months' ); INSERT INTO shorty (id, c) VALUES (2, NULL); INSERT INTO typetest1 (id, c, nc, vc, nvc, lc, r, u, lb, lr, b, num, fl, db, d, ts, ids, iym) VALUES ( 3, E'a\u001B\u0007\u000D\u007Fb', E'a\u001B\u0007\u000D\u007Fb', E'a\u001B\u0007\u000D\u007Fb', E'a\u001B\u0007\u000D\u007Fb', E'a\u001B\u0007\u000D\u007Fb ABC' || repeat('X', 9000), bytea('\xDEADF00D'), uuid('055f3b32-a02c-4532-e053-1645990a6db2'), bytea('\xDEADF00DDEADF00DDEADF00D'), bytea('\xDEADF00DDEADF00DDEADF00D'), FALSE, -2.71828, -2.71828, -2.71828, '0044-03-15 BC', '0044-03-15 12:00:00 BC', 487 第 62 章 ORACLE_FDW '-2 days -12 hours -30 minutes', '-2 years -6 months' ); INSERT INTO typetest1 (id, c, nc, vc, nvc, lc, r, u, lb, lr, b, num, fl, db, d, ts, ids, iym) VALUES ( 4, 'short', 'short', 'short', 'short', 'short', bytea('\xDEADF00D'), uuid('0560ee34-2ef9-1137-e053-1645990ac874'), bytea('\xDEADF00D'), bytea('\xDEADF00D'), NULL, 0, 0, 0, NULL, NULL, '23:59:59.999999', '3 years' ); 62.5 插件 oracle_fdw 的卸载方法 在 ksql 中运行： drop extension oracle_fdw 62.6 插件 oracle_fdw 的升级方法 oracle_fdw 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 488 第 63 章 OWA_UTIL 第 63.1 63章 owa_util 插件 owa_util 简介 插件 owa_util 是 KingbaseES 的一个扩展插件。插件 owa_util 功能是提供 owa_util 系统包。 owa_util 系统包提供了 WHO_CALLED_ME 过程。 • 插件名为 owa_util • 插件版本 V1.0 63.2 插件 owa_util 加载方式 该插件为初始化数据库实例时默认创建。 63.3 插件 owa_util 的参数配置 owa_util 扩展插件无需配置任何参数。 63.4 插件 owa_util 使用方法 63.4.1 返回过程调用者的信息 语法 OWA_UTIL.WHO_CALLED_ME( owner OUT VARCHAR2, name OUT VARCHAR2, 489 第 63 章 OWA_UTIL lineno OUT NUMBER, caller_t OUT VARCHAR2); 功能描述 这个过程返回有关调用它的 PL/SQL 代码单元的信息（以输出参数的形式）。 参数说明 参数 描述 owner 该程序单元的拥有者 name 程序单元的名称 lineno 程序单元中发出调用的行号 caller_t 进行调用的程序单元的类型。可能有：匿名块、触发器、包体、类型体、过程和函数。过程和函数仅适 用于独立的过程和函数 注意: • 如果调用程序单元是在包中子程序，那么 name 就是包名。 • 如果调用程序单元是独立的过程或函数，那么 name 就是过程或函数的名称。 • 如果调用程序单元是匿名块的一部分，那么 name 则为 NULL。 63.4.2 示例 将 who_called_me 子程序作为 proc1 过程的一部分，只要有 PL/SQL 程序单元调用 proc1，那么可以得到 proc1 的 owner、name、lineno 和 caller_t。若是匿名块调用 proc1, 那么 owner 和 name 则为 NULL。 示例如下: \set SQLTERM / create or replace procedure proc1(id number) as owner_name varchar2(100); caller_name varchar2(100); line_number number; caller_type varchar2(100); begin owa_util.who_called_me(owner_name,caller_name,line_number,caller_type); dbms_output.put_line('[id]:' || id || ' ' || '[caller_type]:' || caller_type || ' ' 490 第 63 章 OWA_UTIL || '[owner_name]:' || owner_name || ' ' || '[caller_name]:' || caller_name || ' ' || '[line_number]:' || line_number || ' ' ); end; / set serverout on begin proc1(1); end; / \set SQLTERM ; [id]:1 63.5 [caller_type]:ANONYMOUS BLOCK [owner_name]: [caller_name]: [line_number]:2 插件 owa_util 卸载方法 无法卸载。 63.6 插件 owa_util 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.0 升级到 1.1： ALTER EXTENSION owa_util UPDATE TO '1.1'; 491 第 64 章 PAGEINSPECT 64章 pageinspect 第 64.1 插件 pageinspect 简介 pageinspect 提供函数可以查看数据库页面的内容，对于问题排查、故障处置都很有用。所有函数默认只能被超 级用户使用。 • 插件名为 pageinspect • 插件版本 V1.8 64.2 插件 pageinspect 加载方式 CREATE EXTENSION pageinspect; 64.3 插件 pageinspect 的参数配置 无需配置任何参数。 64.4 插件 pageinspect 的使用方法 插件提供以下函数： 64.4.1 通用函数 get_raw_page(relname text, fork text, blkno int) returns bytea 492 第 64 章 PAGEINSPECT get_raw_page 读取指定关系、指定 fork 的指定块并以 bytea 二进制的形式返回页面数据。这允函数可以 获得该块在某一时刻一致的副本。fork 字符对应关系：’main’ 对应数据；’fsm’ 对应 FSM 空闲空间页面； ’vm’ 对应 VM 可见性页面；’init’ 对应初始页面。 get_raw_page(relname text, blkno int) returns bytea 用于读取数据 fork 的简化版 get_raw_page。等效于 get_raw_page(relname, ’main’, blkno)。 page_header(page bytea) returns record page_header 显示使用标准页面结构的堆表、索引页面的页头信息。传入 get_raw_page 获得的页面数据 作为参数 page。 示例 SELECT * FROM page_header(get_raw_page('bmsql_warehouse', 0)); lsn | checksum | flags | lower | upper | special | pagesize | version | prune_xid ------------+----------+-------+-------+--------+---------+----------+---------+----------0/4A2D1BB0 | 0 | 5 | 1168 | -32768 | -32768 | -32768 | 5 | 0 (1 row) 返回的列对应页头结构 PageHeaderData 中的各个成员。 checksum 存放页面的校验和，如果页面被损坏它可能是不正确的。如果当前实例没有开启页面校验和，输出的 值没有实际意义。 page_checksum(page bytea, blkno int4) returns smallint page_checksum 计算页面的校验和。传入 get_raw_page 获得的页面数据作为参数 page。 示例 SELECT page_checksum(get_raw_page('bmsql_warehouse', 0), 0); page_checksum ---------------4188 (1 row) 注意校验和的计算和块号相关，因此应该传入和获取的页面的块号（除非在做调试）。 用这个函数计算的校验和可以用来和函数 page_header 的结果中的 checksum 进行比较。如果示例开启了页面校 验和则两个值应该相等。 fsm_page_contents(page bytea) returns text fsm_page_contents 显示 FSM 页面的内容和结构，页面中二叉树结构每个节点会输出一行，只有不为 0 的节点输出。 示例 SELECT fsm_page_contents(get_raw_page('bmsql_warehouse', 'fsm', 0)); fsm_page_contents 493 第 64 章 PAGEINSPECT ------------------0: 251 + 1: 251 + 3: 251 + 7: 251 + 15: 251 + 31: 251 + 63: 251 + 127: 251 + 255: 251 + 511: 251 + 1023: 251 + 2047: 251 + 4095: 251 + 8191: 251 + 16383: 251 + fp_next_slot: 0 + (1 row) 64.4.2 堆表函数 heap_page_items(page bytea) returns setof record heap_page_items 显示一个堆表页面上所有的行指针，对于使用中的行指针，元组头部和元组原始数据也 会被显示。不管元组对于拷贝原始页面时的 MVCC 快照是否可见，它们都会被显示。 示例，二进制输出部分使用... 省略 SELECT * from heap_page_items(get_raw_page('bmsql_warehouse', 'main', 0)); lp | lp_off | lp_flags | lp_len | t_xmin | t_xmax | t_field3 | t_ctid | t_infomask2 | t_infomask | t_ hoff | t_bits | t_oid | t_data ----+--------+----------+--------+------------+--------+----------+--------+-------------+------------+-------+--------+-------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------1 | 32656 | 24 | | 1 | 107 | 19554 | 0 | 0 | (0,1) | 9 | 11010 | 126 | 1073751330 | 0 | 1 | (0,2) | 9 | 11010 | | \x01000 000... 2 | 32528 | 24 | | 1 | | \x04000 000... 494 第 64 章 PAGEINSPECT 3 | 32416 | 24 | | 1 | 111 | 19560 | 0 | 0 | (0,3) | 9 | 11010 | 112 | 1073751331 | 0 | 0 | (0,4) | 9 | 11010 | | \x02000 000... 4 | 32304 | 24 | | 1 | | \x03000 000... (4 rows) tuple_data_split(rel_oid oid, t_data bytea, t_infomask integer, t_infomask2 integer, t_bits text [, do_detoast bool]) returns bytea[] tuple_data_split 以和 backend 内部相同的方式将元组数据分解成属性。用 heap_page_items 的返回值 中的列作为参数传入。 示例 SELECT tuple_data_split('bmsql_warehouse'::regclass, t_data, t_infomask, t_infomask2, t_bits) from heap_ page_items(get_raw_page('bmsql_warehouse', 'main', 0)); tuple_data_spli t -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------{"\\x01000000","\\x130181b305b519141e","\\x0b7f82cb04","\\x15534b5446566736326c","\\ x194a68376f6a666e49386f54","\\x1f68567546686535507a6 e437a3138","\\x1f4c784951666c76686e41456c4738","\\x074b42","\\x15313438363131313131"} {"\\x04000000","\\x130181e5011e188025","\\x0b7f826307","\\x134139776952324e55","\\ x29797a394b3268737573616b396a4468686f4b58","\\x2b61555 0356e53334e75436151744370564856446b","\\x2b6e7531485439564d565a326a4c6e793341745a47","\\x074947","\\ x15303438333131313131"} {"\\x02000000","\\x1301819d0283009001","\\x0b7f824a02","\\x1146796663456c6d","\\ x21675837683771356d347569664f5134","\\x19436862434e39565 7313158","\\x29624a65364d4853617647325276645a57654331","\\x075a47","\\x15363339393131313131"} {"\\x03000000","\\x1301811e0399158c0a","\\x0b7f826304","\\x156e4c4459476e7a4c58","\\ x236670356148667537417053544764555a","\\x1b706239506 e785273657a4166","\\x23523074447376417574496d4146726779","\\x074350","\\x15303132363131313131"} (4 rows) heap_page_item_attrs(page bytea, rel_oid regclass [, do_detoast bool]) returns setof record heap_page_item_attrs 和 heap_page_items 效果相同，除了它会把元组的原始数据返回为属性数组，如 果设置了 do_detoast 为 true（默认为 false），属性会被反 TOAST。 示例 495 第 64 章 PAGEINSPECT SELECT * FROM heap_page_item_attrs(get_raw_page('bmsql_warehouse', 0), 'bmsql_warehouse'::regclass); lp | lp_off | lp_flags | lp_len | t_xmin | t_xmax | t_field3 | t_ctid | t_infomask2 | t_infomask | t_ hoff | t_bits | t_oid | t_attrs ----+--------+----------+--------+------------+--------+----------+--------+-------------+------------+-------+--------+-------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------1 | 32656 | 24 | | 1 | 107 | 19554 | 0 | 0 | (0,1) | 9 | 11010 | | {"\\x01 000000","\\x130181b305b519141e","\\x0b7f82cb04","\\x15534b5446566736326c","\\x194a68376f6a666e49386f54","\\ x1f68567546686535507a6e437a313 8","\\x1f4c784951666c76686e41456c4738","\\x074b42","\\x15313438363131313131"} 2 | 32528 | 24 | | 1 | 126 | 1073751330 | 0 | 1 | (0,2) | 9 | 11010 | | {"\\x04 000000","\\x130181e5011e188025","\\x0b7f826307","\\x134139776952324e55","\\ x29797a394b3268737573616b396a4468686f4b58","\\x2b615550356e533 34e75436151744370564856446b","\\x2b6e7531485439564d565a326a4c6e793341745a47","\\x074947","\\ x15303438333131313131"} 3 | 32416 | 24 | | 1 | 111 | 19560 | 0 | 0 | (0,3) | 9 | 11010 | | {"\\x02 000000","\\x1301819d0283009001","\\x0b7f824a02","\\x1146796663456c6d","\\x21675837683771356d347569664f5134", "\\x19436862434e395657313158" ,"\\x29624a65364d4853617647325276645a57654331","\\x075a47","\\x15363339393131313131"} 4 | 32304 | 24 | | 1 | 112 | 1073751331 | 0 | 0 | (0,4) | 9 | 11010 | | {"\\x03 000000","\\x1301811e0399158c0a","\\x0b7f826304","\\x156e4c4459476e7a4c58","\\ x236670356148667537417053544764555a","\\x1b706239506e7852736 57a4166","\\x23523074447376417574496d4146726779","\\x074350","\\x15303132363131313131"} (4 rows) 64.4.3 B 树索引函数 bt_metap(relname text) 返回 record bt_metap 返回 B 树索引 meta 页面的信息。 示例 SELECT * FROM bt_metap('bmsql_warehouse_pkey'); magic | version | root | level | fastroot | fastlevel | oldest_xact | last_cleanup_num_tuples 496 第 64 章 PAGEINSPECT --------+---------+------+-------+----------+-----------+-------------+------------------------340322 | 4 | 1 | 0 | 1 | 0 | 0 | 4 (1 row) bt_page_stats(relname text, blkno int) returns record bt_page_stats 返回指定 B 树索引指定块的页面统计信息。 示例 SELECT * FROM bt_page_stats('bmsql_warehouse_pkey', 1); blkno | type | live_items | dead_items | avg_item_size | page_size | free_size | btpo_prev | btpo_next | btpo | btpo_flags -------+------+------------+------------+---------------+-----------+-----------+-----------+-----------+-----+-----------1 | l 0 | | 4 | 0 | 16 | 32768 | 32632 | 0 | 0 | 3 (1 row) bt_page_items(relname text, blkno int) returns setof record bt_page_items 返回指定 B 树索引指定块的页面中的所有索引项。 示例 SELECT * FROM bt_page_items('bmsql_warehouse_pkey', 1); itemoffset | ctid | itemlen | nulls | vars | data ------------+-------+---------+-------+------+------------------------1 | (0,1) | 16 | f | f | 01 00 00 00 00 00 00 00 2 | (0,3) | 16 | f | f | 02 00 00 00 00 00 00 00 3 | (0,4) | 16 | f | f | 03 00 00 00 00 00 00 00 4 | (0,2) | 16 | f | f | 04 00 00 00 00 00 00 00 (4 rows) bt_page_items(page bytea) returns setof record bt_page_items 接收 get_raw_page 的输出作为参数，返回内容和上面的函数相同。 64.4.4 位图索引函数 bm_metap(relname text) bm_metap 返回指定的 bitmap 索引 meta 页面的信息。 示例 SELECT * FROM bm_metap('idx_t'); magic | version | auxrelid | auxindexrelid | lovlastblknum 497 第 64 章 PAGEINSPECT ------------+---------+----------+---------------+--------------1112101965 | 2 | 16421 | 16424 | 1 (1 rows) bm_lov_page_items(relname text, blkno int4) bm_lov_page_items 返回指定的 bitmap 索引的 lov 页保存的信息。 示例 SELECT * FROM bm_lov_page_items('idx_t',1); itemoffset | lov_head_blkno | lov_tail_blkno | last_complete_word | last_word | last_tid | last_setbit_tid | is_last_complete_word_fill | is_last_word_fill ------------+----------------+----------------+-------------------------+-------------------------+----------+-----------------+----------------------------+------------------1 | 0 | 4294967295 | 4294967295 | ff ff ff ff ff ff ff ff | 00 00 00 00 00 00 00 00 | 0 | f | f 2 | 289931392 | 2 | 289931440 | f 3 | 289931392 | 5 | 4 | 94 | c2 1c 44 2f 34 d3 62 cc | 00 00 41 f1 88 21 23 40 | | f 97 | 10 02 20 10 82 00 00 00 | 00 00 08 02 10 54 00 90 | 289931436 | f 5 | 289931392 | | f 289931439 | f 4 | 289931392 | 95 | 2c a0 83 c0 48 04 99 30 | 00 00 b6 08 46 00 4c 2f | 3 | | f 96 | 01 41 18 00 01 28 04 03 | 00 00 00 04 21 8a 90 00 | 289931427 | f | f (5 rows) bm_bitmap_page_header(relname text, blkno int4) bm_bitmap_page_header 返回指定的 bitmap 索引的位图页的统计信息。 示例 SELECT * FROM bm_bitmap_page_header('idx_t',2); num_words | next_blkno | last_tid -----------+------------+---------960 | 6 | 12582912 (1 row) bm_bitmap_page_items(relname text, blkno int4) bm_bitmap_page_items 返回指定的 bitmap 索引的位图页中保存的位图信息。 示例 SELECT * FROM bm_bitmap_page_items('idx_t',2); word_num | compressed | content_word ----------+------------+------------------------0 | f | 42 8c a0 00 2c 09 56 07 498 第 64 章 PAGEINSPECT 1 | f | a4 09 86 4e 6c 0e ae 42 2 | f | 00 88 68 68 44 10 01 08 3 | f | 00 00 00 00 26 41 48 a8 4 | t | 00 00 00 00 00 00 03 fc 5 | f | e9 10 20 0e ea 41 01 32 6 | f | a3 c1 b0 4d c4 2d 08 05 7 | f | 60 84 29 1e 0c 91 4d 10 8 | f | 00 00 00 03 62 83 21 82 9 | t | 00 00 00 00 00 00 03 fc 10 | f | c4 16 20 01 bf a9 52 12 64.5 插件 pageinspect 卸载方法 DROP EXTENSION pageinspect; 64.6 插件 pageinspect 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION pageinspect UPDATE TO '1.1'; 499 第 65 章 PASSWORDCHECK 65章 passwordcheck 第 插件 passwordcheck 简介 65.1 passwordcheck 插件主要用于管理口令复杂度。 口令的复杂度检查是由数据库安全员对口令的最小长度，所包含的数字、英文字母、特殊符号的数目进行设置 后，在数据库管理员创建和修改用户时，自动对口令进行相关方面的检查。如果口令不满足指定的条件，那么创建用 户将不成功。 KingbaseES 通过插件的方式来进行口令的复杂度管理。这种方式更为灵活，当数据库的实用场景需要进行口令 的复杂度管理时，加载插件即可。而不需要该功能时，卸载插件即可。 KingbaseES 中通过 4 个全局级参数配合插件来实现用户口令复杂度管理。 • 插件名为 passwordcheck • 插件版本 V1.0 插件 passwordcheck 加载方式 65.2 在使用 passwordcheck 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'passwordcheck' 65.3 插件 passwordcheck 的参数配置 • passwordcheck.enable 口令复杂度开关，默认为关闭状态。 500 第 65 章 PASSWORDCHECK • passwordcheck.password_length 口令的最小长度，取值范围为 [8，63]，缺省为 8。 • passwordcheck.password_condition_letter 口令至少包含几个字母，取值范围为 [2，61]，缺省为 2。 • passwordcheck.password_condition_digit 口令至少包含几个数字，取值范围为 [2，61]，缺省为 2。 • passwordcheck.password_condition_punct 口令至少包含几个特殊字符，取值范围为 [0，59]，缺省为 0。其中特殊符号为除空白符、英文字母、 单引号和数字外的所有可见字符。 65.4 插件 passwordcheck 的使用方法 加载 passwordcheck 插件后，在数据库管理员创建和修改用户时，自动对口令进行相关方面的检查。如果口令不 满足指定的条件，那么创建用户将不成功。当不需要该功能时，卸载插件即可。 示例： -- 打开口令复杂度开关 \c test system create extension passwordcheck; CREATE EXTENSION \c test sso show passwordcheck.enable; passwordcheck.enable ---------------------off (1 行记录) alter system set passwordcheck.enable=on; ALTER SYSTEM select sys_reload_conf(); sys_reload_conf ----------------t (1 行记录) show passwordcheck.enable; 501 第 65 章 PASSWORDCHECK passwordcheck.enable ---------------------on (1 行记录) -- 修改口令最小长度为 10 \c test sso SHOW passwordcheck.password_length; passwordcheck.password_length ------------------------------8 (1 row) SET passwordcheck.password_length = 10; SHOW passwordcheck.password_length; passwordcheck.password_length ------------------------------10 (1 row) \c test system CREATE USER u_pwd PASSWORD '123ab'; ERROR: password length 5 is too short, should be longer than min password length 10. CREATE USER u_pwd PASSWORD '1234567890ab'; CREATE ROLE -- 修改口令最少包含 3 个字母 \c test sso SHOW passwordcheck.password_condition_letter; passwordcheck.password_condition_letter ----------------------------------------2 (1 row) SET passwordcheck.password_condition_letter = 3; SHOW passwordcheck.password_condition_letter; passwordcheck.password_condition_letter ----------------------------------------3 (1 row) 502 第 65 章 PASSWORDCHECK \c test system ALTER USER u_pwd PASSWORD '1234567890'; ERROR: Password should contain at least 3 letter and the current number is 0 ALTER USER u_pwd PASSWORD '1234567890ab'; ERROR: Password should contain at least 3 letter and the current number is 2 ALTER USER u_pwd PASSWORD '1234567890abC'; ALTER ROLE -- 修改口令最少包含 3 个数字 \c test sso SHOW passwordcheck.password_condition_digit; passwordcheck.password_condition_digit ---------------------------------------2 (1 row) SET passwordcheck.password_condition_digit = 3; SHOW passwordcheck.password_condition_digit; passwordcheck.password_condition_digit ---------------------------------------3 (1 row) \c test system ALTER USER u_pwd PASSWORD 'abcdefghij'; ERROR: Password should contain at least 3 digit and the current number is 0 ALTER USER u_pwd PASSWORD 'abcdefghij123'; ALTER ROLE -- 修改口令最少包含 3 个特殊字符 \c test sso SHOW passwordcheck.password_condition_punct; passwordcheck.password_condition_punct ---------------------------------------0 (1 row) 503 第 65 章 PASSWORDCHECK SET passwordcheck.password_condition_punct = 2; SHOW passwordcheck.password_condition_punct; passwordcheck.password_condition_punct ---------------------------------------2 (1 row) \c test system ALTER USER u_pwd PASSWORD '1234567890abc.'; ERROR: Password should contain at least 2 punct and the current number is 1 ALTER USER u_pwd PASSWORD '1234567890abc./'; ALTER ROLE 65.5 插件 passwordcheck 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 65.6 插件 passwordcheck 升级方法 passwordcheck 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 504 第 66 章 PASSWORDHISTORY 66章 passwordhistory 第 66.1 插件 passwordhistory 简介 passwordhistory 插件主要用于管理口令历史。 口令的历史检查是由数据库管理员对初次设定的口令或更改过的口令使用天数进行设置后，在修改用户口令时， 自动对口令已使用天数进行相关方面的检查。如果口令不满足指定的条件，那么更改口令将不成功。 KingbaseES 通过插件的方式来进行口令历史管理。这种方式更为灵活，当数据库的实用场景需要进行口令历史 管理时，加载插件即可。而不需要该功能时，卸载插件即可。 KingbaseES 中通过 2 个全局级参数配合插件来实现用户口令历史管理。 • 插件名为 passwordhistory • 插件版本 V1.0 66.2 插件 passwordhistory 加载方式 在使用 passwordhistory 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'passwordhistory' 66.3 插件 passwordhistory 的参数配置 passwordhistory.enable 密码历史开关，默认为关闭状态。 passwordhistory.password_time 505 第 66 章 PASSWORDHISTORY 设定口令历史天数，缺省为 0。 示例： -- 创建插件并打开口令历史开关 create extension passwordhistory; CREATE EXTENSION show passwordhistory.enable; passwordhistory.enable -----------------------off (1 行记录) alter system set passwordhistory.enable=on; ALTER SYSTEM select sys_reload_conf(); sys_reload_conf ----------------t (1 行记录) show passwordhistory.enable; passwordhistory.enable -----------------------on (1 行记录) -- 设定口令历史天数为 2 show passwordhistory.password_time; passwordhistory.password_time ------------------------------0 (1 row) SET passwordhistory.password_time = 2; call sys_reload_conf(); sys_reload_conf ----------------t (1 row) 506 第 66 章 PASSWORDHISTORY SHOW passwordhistory.password_time; passwordhistory.password_time ------------------------------2 (1 row) create user test with password '123'; CREATE ROLE alter user test with password '123'; ERROR: The password has been used recently. 66.4 插件 passwordhistory 的使用方法 记载 passwordhistory 插件后，在修改用户口令时，程序会自动对口令已使用天数进行相关方面的检查。如果口 令不满足指定的条件，那么更改口令将不成功。 66.5 插件 passwordhistory 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 66.6 插件 passwordhistory 升级方法 passwordhistory 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 507 第 67 章 PLDBGAPI 67章 pldbgapi 第 67.1 插件 pldbgapi 简介 插件 pldbgapi 是 KingbaseES 的一个扩展插件。主要用于 PL/pgSQL 语言的存储过程/函数的代码调试。 • 插件名为 pldbgapi • 插件版本 V1.2 67.2 插件 pldbgapi 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。因此只需要在客户端工具执行 create extension 命令即可。 -- 创建插件 create extension pldbgapi; 注意: 在当前模式和 plpgsql_debug 模式下均创建了一套调试接口，因此在任意模式下调试接口可通过模式限定调 用。 67.3 插件 pldbgapi 的参数配置 pldbgapi 扩展插件无需配置任何参数。 508 第 67 章 PLDBGAPI 67.4 插件 pldbgapi 使用方法 67.4.1 pldebugger 调试流程 以下详细介绍其局部断点调试和全局断点调试流程的命令行调试流程。只是在目标后端与调试端建立连接的流程 有稍微差别，实际的调试的流程总体一致。 pldebugger 的调试操作是建立在目标后端和调试端正常通信的前提下，其详细的调试流程如下： 1. 创建监听，局部断点调试根据调试对象的 OID 去建立监听，全局断点调试则不需要带调试对象的 OID 而是创 建全局监听。 2. 创建连接，全局调试与局部调试的连接方式稍有不同，对于局部调试，首先是调用待调试的对象，让目标后端 进程以通信服务器端的身份发起连接，然后在调试端调用端口连接函数 pldbg_attah_to_port 让调试端以通 信客户端的身份与目标后端建立连接；对于全局断点调试，先设置全局断点，然后调用 pldbg_wait_for_target 函数发起连接并等待接受目标后端的连接。此时调用待调试的对象就可以与调试端建立通信连接。 3. 调试设置，可以根据需要设置和删除断点信息，包括局部断点和全局断点。 4. 执行调试操作，pldebugger 提供了三种调试执行的方式，分别为单步进入（step into）、单步跳过（step over） 以及继续执行（continue）。 5. 信息查询，在调试执行的过程中，可以查询源代码信息，查询和修改变量值，查询调用堆栈以及当前系统版本 等。 67.4.2 接口函数 pldebugger 调试工具支持对 PL/pgSQL 语言的函数或存储过程进行调试操作，包括操作断点、执行代码、调试 数据、查看调用堆栈、查看源码信息、查看版本信息等功能。并提供局部断点调试与全局断点调试两种调试模式。 调试接口函数列表如下： 表 67.4.1: 接口函数列表 接口函数 简介 plpgsql_oid_debug 函数 创建局部监听 pldbg_attach_to_port 函数 连接目标后端 pldbg_create_listener 函数 创建全局监听 pldbg_set_global_breakpoint 函数 设置全局断点 pldbg_wait_for_target 函数 等待连接 见续表 509 第 67 章 PLDBGAPI 表 67.4.1 – 续表 接口函数 简介 pldbg_set_breakpoint 函数 设置断点 pldbg_get_breakpoints 函数 查询断点 pldbg_drop_breakpoint 函数 删除断点 pldbg_wait_for_breakpoint 函数 返回建立连接时断点所在行的信息 pldbg_step_into 函数 单步进入（step into） pldbg_step_over 函数 单步跳过（step over） pldbg_continue 函数 继续执行（continue） pldbg_abort_target 函数 中止执行 pldbg_get_variables 函数 查看变量 pldbg_deposit_value 函数 修改变量 pldbg_get_stack 函数 查看堆栈信息 pldbg_select_frame 函数 追溯堆栈信息 pldbg_get_source 函数 查询源代码信息 plsql_extend_get_proc_ddl 函数 获取函数、存储过程源码 pldbg_get_proxy_info 函数 查询当前系统版本信息 67.4.2.1 plpgsql_oid_debug 函数 功能描述 在同一个 session 下负责监听该函数或存储过程，创建监听状态。该函数在建立监听的过程中会设置一个系统默 认断点，行号为‘-1’。 语法格式 FUNCTION plpgsql_oid_debug( FUNCTIONOID OID ) RETURNS INTEGER 参数说明 返回值说明 调用成功返回 0，调用失败无返回值，存在报错信息如下： 1. 当 OID 输入为 0 时报错信息：no target specified。 510 第 67 章 PLDBGAPI 2. 当 OID 无效时报错信息：cache lookup failed for FUNCTION。 3. 当不是 owner 或 superuser 时报错信息：must be owner or superuser to create a breakpoint。 67.4.2.2 pldbg_attach_to_port 函数 功能描述 此函数用于响应 PLDBGBREAK 端口号。该函数连接到监听给定端口的 Target Backend 端，从而形成 Debugger Client，启动调试过程，等待后续调试工作。一个 Debugger Client 能够响应多个不同 PLDBGBREAK 端口，即 可以支持多个并发会话。 语法格式 FUNCTION pldbg_attach_to_port(portNumber INTEGER) RETURNS INTEGER 参数说明 参数名称 描述 portNumber 调用自定义函数或存储过程时显示的进程 ID 号 返回值说明 返回标识此特定调试的会话句柄。 67.4.2.3 pldbg_create_listener 函数 功能描述 创建一个 TCP 端口，为全局断点创建一个监听器，方便后续函数连接到该目标进程。 语法格式 FUNCTION pldbg_create_listener() RETURNS INTEGER 返回值说明 调用成功返回 debug_session 号。 67.4.2.4 pldbg_set_global_breakpoint 函数 功能描述 创建一个全局断点。 语法格式 511 第 67 章 PLDBGAPI FUNCTION pldbg_set_global_breakpoint( session INT, FUNCTION OID, lineNumber INT, targetPID INT ) RETURNS boolean 参数说明 返回值说明 调用成功返回 t，调用失败会报错。 67.4.2.5 pldbg_wait_for_target 函数 功能描述 发起 socket 连接，等待目标后端进程调用自定义函数或者存储过程来连接到调试端，以触发全局断点。 语法格式 FUNCTION pldbg_wait_for_target( session INTEGER ) RETURNS INTEGER 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 调用成功返回 target backend 的 PID。 67.4.2.6 pldbg_set_breakpoint 函数 功能描述 在目标进程中设置一个“局部”断点。 此函数将 PLDBG_SET_BREAKPOINT 指令发送到 Targert Backend 端，在自定义函数或者存储过程的指定 位置设置断点，然后等待下一个可执行语句到达该目标断点。 语法格式 FUNCTION pldbg_set_breakpoint( session INTEGER, FUNCTION OID, lineNumber INTEGER ) RETURNS boolean 参数说明 返回值说明 断点设置成功返回为 t，断点设置失败返回为 f。 512 第 67 章 PLDBGAPI 67.4.2.7 pldbg_get_breakpoints 函数 功能描述 显示设置的所有断点。此函数将 PLDBG_GET_BREAKPOINTS 指令发送到 Targert Backend 端，返回查询到 的断点元组信息。如果没有断点信息，则返回为空。 语法格式 FUNCTION pldbg_get_breakpoints( session INTEGER ) RETURNS SETOF breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返回一组“breakpoint”元组信息，该元组信息包括自定义函数或者存储过程的 OID，断点设置的行号 lineNumber，Target 端的名字 targetName。 67.4.2.8 pldbg_drop_breakpoint 函数 功能描述 在目标进程中删除一个指定行号的断点。此函数将 PLDBG_CLEAR_BREAKPOINT 指令发送到 Targert Backend 端，删除指定断点信息，并返回删除成功与否的状态。 语法格式 FUNCTION pldbg_drop_breakpoint( session INTEGER, FUNCTION OID, lineNumber INTEGER ) RETURNS boolean 参数说明 返回值说明 断点删除成功返回 t，断点删除失败返回 f。 67.4.2.9 pldbg_wait_for_breakpoint 函数 功能描述 调用该函数，可以返回刚建立连接时断点所在行的信息。 语法格式 513 第 67 章 PLDBGAPI FUNCTION pldbg_wait_for_breakpoint( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为一个“breakpoint”的元组，该元组包含自定义函数或者存储过程的 OID 以及刚建立连接时停 止的行号。 67.4.2.10 pldbg_step_into 函数 功能描述 单步执行，遇到子函数或子存储过程会进入到相应的部分。此函数将 PLDBG_STEP_INTO 命令发送到 Targert Backend，等待目标后端进程执行语句后，等待下一个可执行语句到达目标。 语法格式 FUNCTION pldbg_step_into( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组（但不一定是真正的断点信息，因为单步执行有可能遇到断点，有可能 没有遇见断点）。该元组包含自定义函数或者存储过程的 OID 以及目标当前停止的行号，以及自定义函数或者存储 过程名。 67.4.2.11 pldbg_step_over 函数 功能描述 单步执行，遇见子函数或子存储过程会跳过内部执行过程。此函数将 PLDBG_STEP_OVER 命令发送到 Targert Backend，待目标后端进程执行语句后，等待下一个可执行语句到达目标，并将执行后需要返回的结果返回。 语法格式 514 第 67 章 PLDBGAPI FUNCTION pldbg_step_over( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组（但不一定是真正的断点信息，因为单步执行有可能遇到断点，有可能 没有遇见断点）。该元组包含自定义函数或者存储过程的 OID 以及目标当前停止的行号，以及自定义函数或者存储 过程名。 67.4.2.12 pldbg_continue 函数 功能描述 从当前位置继续执行，直到遇见下一个断点，如果没有断点，将直接执行到自定义函数或存储过程的最后。此 函数将“PLDBG_CONTINUE”指令发送到 Targert Backend 端，目标后端进程执行，然后等待目标到达下一个断 点，并返回相应的结果信息。 语法格式 FUNCTION pldbg_continue( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组，该元组包含自定义函数或者存储过程的 OID 以及目标当前停止的行 号，以及自定义函数或者存储过程名。 67.4.2.13 pldbg_abort_target 函数 功能描述 终止当前的执行。此函数将 PLDBG_ABORT 命令发送到 Targert Backend，然后终止当前的执行，并返回终止 成功与否的状态。 语法格式 515 第 67 章 PLDBGAPI FUNCTION pldbg_abort_target( session INTEGER ) RETURNS SETOF boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 终止成功返回 t。 67.4.2.14 pldbg_get_variables 函数 功能描述 获取一个变量或者参数的信息列表。此函数将 PLDBG_GET_VARIABLES 指令发送到 Targert Backend 端， 服务器查询到所有变量的信息后返回变量或参数的信息列表。 语法格式 FUNCTION pldbg_get_variables( session INTEGER ) RETURNS SETOF var 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返回一个 var 元 组 集 合， 包 含 信 息：VarName；Class；lineNumber；Unique；isConst；notNull； dataTypeOID；value(rest of string)。其中每个变量的含义如下： 1. varName: 变量或参数的名称； 2. Class：变量或参数的类别。如果自定义函数或存储过程有输入参数时，该参数类型将标记为“A”，语句块里 的参数将标记为“L”； 3. lineNumber：声明变量或参数的行号； 4. Unique：标记该名称在自定义函数或者存储过程范围内是否唯一，如果名称不是唯一，调试器客户端将使用行 号来区分同名的变量或参数； 5. isConst：标记变量或参数是否为常量； 6. notNull：标记变量或参数是否不为空； 516 第 67 章 PLDBGAPI 7. dataTypeOID：该变量 sys_type 中对应的 OID； 8. value(rest of string)：变量的值。 67.4.2.15 pldbg_deposit_value 函数 功能描述 在调试过程中，将一个新值赋给指定的变量。此函数将 PLDBG_DEPOSIT 指令发送到 Targert Backend 端，服 务器查询该变量然后修改变量的值，最后将修改成功与否的状态返回。 语法格式 FUNCTION pldbg_deposit_value( session INTEGER, varName TEXT, lineNumber INTEGER, value TEXT ) RETURNS boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 varName 变量名 lineNumber 变量定义的行号 value 变量新值 返回值说明 新值设置成功返回 t，新值设置失败返回 f。 67.4.2.16 pldbg_get_stack 函数 功能描述 从 Targert Backend 端获取调用堆栈信息。此函数将 PLDBG_GET_STACK 指令发送到 Targert Backend 端， 返回相应调用堆栈信息。 语法格式 FUNCTION pldbg_get_stack( session INTEGER ) RETURNS SETOF frame 参数说明 517 第 67 章 PLDBGAPI 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返 回 一 组 堆 栈 框 架 信 息 元 组， 包 含：CallCount；targetName；funcOID；lineNumber；arguments(rest of string)。 1. CallCount: 堆栈深度。 2. targetName: 调用函数或存储过程的名称。 3. funcOID: 自定义函数或者存储过程 OID。 4. lineNumber: 当前停留的行号。 5. arguments(rest of string): 参数的信息。 67.4.2.17 pldbg_select_frame 函数 功能描述 将调试器焦点（当前在堆栈中的执行位置）更改为指定的帧。此函数将 PLDBG_SELECT_FRAME 命令发送 到 Targert Backend，然后循环查询指定的帧，如果传入的帧不存在，将返回当前帧的信息，如果传入的帧信息存 在，将返回相应的查询信息。 语法格式 FUNCTION pldbg_select_frame( session INTEGER, frame INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 frame 指定帧 返回值说明 此函数返回类型为“breakpoint”的元组，其中包含自定义函数或者存储过程 OID，以及当前目标在选定帧中停 止的行号。 67.4.2.18 pldbg_get_source 函数 功能描述 518 第 67 章 PLDBGAPI 从 Target Backend 获取自定义函数或存储过程正在执行的源代码。此函数将包含 PLDBG_GET_SOURCE， FUNCTIONOID 的字符串发送到 Targert Backend，查询源代码信息并返回。 语法格式 FUNCTION pldbg_get_source( session INTEGER, func OID ) RETURNS TEXT 参数说明 参数名称 描述 session 标识特定调试的会话句柄 func 自定义函数或存储过程的 OID 返回值说明 返回给定函数或存储过程的源代码信息。 67.4.2.19 plsql_extend_get_proc_ddl 函数 功能描述 用以支撑 pldebugger 获取函数、存储过程源码。 语法格式 FUNCTION plpgsql_debug.plsql_extend_get_proc_ddl(func OID) returns text 参数说明 参数名称 描述 func 函数、存储过程的 oid。 返回值说明 函数、存储过程的源码。 参数异常 参数名称 用例 结果 func NULL 返回 NULL 0 报错 invalid object oid 不存在的 oid 报错 cache lookup failed for function 519 第 67 章 PLDBGAPI 67.4.2.20 pldbg_get_proxy_info 函数 功能描述 获取服务器版本，Proxy Backend API 版本等信息。 语法格式 FUNCTION pldbg_get_proxy_info() RETURNS proxyInfo 返回值说明 返回服务器和代理 API 的版本信息。 67.4.2.21 局部断点调试示例 创建调试环境和用例： --创建 pldebugger 环境 create extension pldbgapi; --创建用来调试的存储过程 CREATE OR REPLACE PROCEDURE public.pro1() language 'plpgsql' AS $$ BEGIN raise notice '123'; raise notice 'success'; END; $$; CREATE OR REPLACE PROCEDURE public.pro4() LANGUAGE 'plpgsql' AS $$ declare i int := 2; begin i = 3; raise notice 'i= %',i; i = 4; raise notice 'i= %',i; raise notice '0:ready.....'; begin raise notice '1:ready.....'; call pro1(); begin 520 第 67 章 PLDBGAPI raise notice 'success'; end; end; end; $$; --查询出需要调试的存储过程的 oid select oid from sys_proc where proname = 'pro4'; oid ------16918 (1 row) application client： --应用端开启局部监听 select plpgsql_oid_debug(16918); plsql_oid_debug ------------------0 (1 row) --开始调试存储过程 pro4 call pro4(); NOTICE: PLDBGBREAK:3 --该进程控制器转交给另一进程，直至调试结束，3 为连接的端口号 debugger client： --调试端连接 select pldbg_attach_to_port(3); pldbg_attach_to_port ---------------------1 (1 row) --查看源码 select pldbg_get_source(1,16918); pldbg_get_source -------------------------------------+ declare i int := 2; begin + + + i = 3; + raise notice 'i= %',i; + 521 第 67 章 PLDBGAPI i = 4; + raise notice 'i= %',i; + raise notice '0:ready.....'; + begin + raise notice '1:ready.....';+ call pro1(); + begin + raise notice 'success'; + end; end; + + end (1 row) --设置断点 select pldbg_set_breakpoint(1,16918,7); pldbg_set_breakpoint ---------------------------t (1 row) select pldbg_set_breakpoint(1,16918,12); pldbg_set_breakpoint ---------------------t (1 row) select pldbg_set_breakpoint(1,16918,15); pldbg_set_breakpoint ---------------------t (1 row) --获取当前设置的断点信息 select pldbg_get_breakpoints(1); pldbg_get_breakpoints ----------------------(16918,-1,"") (16918,12,"") (16918,15,"") (16918,7,"") (4 rows) --单步执行，遇到子程序进入 select pldbg_step_into(1); pldbg_step_into 522 第 67 章 PLDBGAPI ----------------------(16918,7,"pro4()") (1 row) select pldbg_step_into(1); pldbg_step_into ----------------------(16918,8,"pro4()") (1 row) select pldbg_step_into(1); pldbg_step_into ----------------------(16918,9,"pro4()") (1 row) --单步执行，遇到子程序跳过 select pldbg_step_over(1); pldbg_step_over ----------------------(16918,10,"pro4()") (1 row) --继续执行程序，直到断点处或者程序结束 select pldbg_continue(1); pldbg_continue ---------------------(16918,13,"pro4()") (1 row) --当 application client 执行完毕后，debug client 进程会挂起，直到 application client 再次执行测试函数或存储过 程 select pldbg_continue(1); application client： --应用端存储过程执行完成 call pro4(); NOTICE: PLDBGBREAK:3 NOTICE: i= 3 NOTICE: i= 4 NOTICE: 0:ready..... NOTICE: 1:ready..... NOTICE: 123 NOTICE: success 523 第 67 章 PLDBGAPI NOTICE: success CALL --再次调起 call pro4(); debugger client： --调试端进入调试状态，调用 pldbg_abort_target，终止调试 select pldbg_abort_target(1); pldbg_abort_target -------------------t (1 row) application client： —当 debug client 调用 select pldbg_abort_target(1) 后，执行被终止 call pro4(); ERROR: canceling statement due to user request CONTEXT: PL/pgSQL FUNCTION pro4() line 5 at assignment 67.4.2.22 全局断点调试示例 debugger client： --调试端创建全局监听 select pldbg_create_listener(); pldbg_create_listener ----------------------1 (1 row) --设置全局断点，未指定行号默认为-1，即 BEGIN 块的第一行 select pldbg_set_global_breakpoint(1,16918,null,null); pldbg_set_global_breakpoint ----------------------------t (1 row) --等待测试函数被调用，无测试函数调用该进程会挂起 select pldbg_wait_for_target(1); application client： 524 第 67 章 PLDBGAPI --应用端执行测试函数 call pro4(); debugger client： --测试函数调用后，返回测试函数 session 的进程号，开始调试 select pldbg_wait_for_target(1); pldbg_wait_for_target ----------------------------235966 (1 row) --设置局部断点 select pldbg_set_breakpoint(1,16918,5); pldbg_set_breakpoint ---------------------t (1 row) --设置全局断点 select pldbg_set_global_breakpoint(1,16918,12,null); pldbg_set_global_breakpoint ----------------------------t (1 row) --获取变量信息 select pldbg_get_variables(1); pldbg_get_variables --------------------------(i,L,3,t,f,f,23,2) (1 row) --单步进入 select pldbg_step_into(1); pldbg_step_into ----------------------(16918,7,"pro4()") (1 row) select pldbg_step_into(1); pldbg_step_into ----------------------(16918,8,"pro4()") 525 第 67 章 PLDBGAPI (1 row) --获取修改后的变量信息 select pldbg_get_variables(1); pldbg_get_variables --------------------(i,L,3,t,f,f,23,3) (1 row) --继续执行到断点处 select pldbg_continue(1); pldbg_continue --------------------(16918,13,"pro4()") (1 row) --单步进入子程序 pro1 select pldbg_step_into(1); pldbg_step_into -------------------(16917,4,"pro1()") (1 row) --获取堆栈信息 select pldbg_get_stack(1); pldbg_get_stack -------------------------(0,"pro1()",16917,3,"") (1,"pro4()",16918,12,"") (2 rows) --追溯堆栈信息 select pldbg_select_frame(1,1); pldbg_select_frame --------------------(16918,13,"pro4()") (1 row) --继续执行到程序结束后挂起，等待下一次程序调用 select pldbg_continue(1); pldbg_continue --------------------(16918,15,"pro4()") 526 第 67 章 PLDBGAPI (1 row) select pldbg_continue(1); application client： --应用端程序执行完成 call pro4(); NOTICE: i= 3 NOTICE: i= 4 NOTICE: 0:ready NOTICE: 1:ready NOTICE: 123 NOTICE: success NOTICE: success CALL 67.4.2.23 修改调试时数据及删除断点调试示例 创建测试环境和用例： --创建 pldebugger 环境 create extension pldbgapi; --创建用来调试的存储过程 create or replace procedure pro5(i int) LANGUAGE 'plpgsql' as $$ declare j int; begin raise notice 'i = %',i; j = i; raise notice 'j = %',j; j = 1; raise notice 'j = %',j; i = 2; raise notice 'i = %',i; end; $$; --查询出需要调试的存储过程的 oid select oid from sys_proc where proname = 'pro5'; oid 527 第 67 章 PLDBGAPI ------16919 (1 row) debugger client： --创建全局监听 select pldbg_create_listener(); pldbg_create_listener ----------------------1 (1 row) --设置全局断点 select pldbg_set_global_breakpoint(1,16919,null,null); pldbg_set_global_breakpoint ----------------------------t (1 row) --等待测试存储过程调用 select pldbg_wait_for_target(1); application client： call pro5(3); debugger client： --子程序已调用，开始调试 select pldbg_wait_for_target(1); pldbg_wait_for_target ----------------------------313888 (1 row) --返回建立连接时断点所在行的信息 (全局断点行号为 null，默认当前在 BEGIN 块的第一行) select pldbg_wait_for_breakpoint(1); pldbg_wait_for_breakpoint --------------------------(16919,6,"pro5(integer)") (1 row) --单步执行 select pldbg_step_into(1); pldbg_step_into 528 第 67 章 PLDBGAPI --------------------------(16919,7,"pro5(integer)") (1 row) --获取存储过程源码 select pldbg_get_source(1,16919); pldbg_get_source ----------------------------+ declare j int; begin + + + raise notice 'i = %',i;+ j = i; + raise notice 'j = %',j;+ j = 1; + raise notice 'j = %',j;+ i = 2; + raise notice 'i = %',i;+ end; (1 row) --查看变量的值 select pldbg_get_variables(1); pldbg_get_variables ----------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,NULL) (2 rows) --修改变量 j 的值 select pldbg_deposit_value(1, 'j', 3, '10'); pldbg_deposit_value --------------------f (1 row) --再次查看变量 j 的值，已被改变 select pldbg_get_variables(1); pldbg_get_variables --------------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,10) (2 rows) 529 第 67 章 PLDBGAPI --单步执行，变量 j 在程序中被赋值 select pldbg_step_into(1); pldbg_step_into --------------------------(16919,8,"pro5(integer)") (1 row) --查看变量 j 的值，已改变 select pldbg_get_variables(1); pldbg_get_variables --------------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,3) (2 rows) --设置局部断点 select pldbg_set_breakpoint(1,16919,5); pldbg_set_breakpoint ---------------------t (1 row) select pldbg_set_breakpoint(1,16919,7); pldbg_set_breakpoint ---------------------t (1 row) select pldbg_set_breakpoint(1,16919,9); pldbg_set_breakpoint ---------------------t (1 row) --查看断点信息 select pldbg_get_breakpoints(1); pldbg_get_breakpoints ----------------------(16919,-1,"") (16919,7,"") (16919,9,"") (16919,-1,"") (16919,5,"") (5 rows) 530 第 67 章 PLDBGAPI --删除断点 select pldbg_drop_breakpoint(1,16919,5); pldbg_drop_breakpoint ----------------------t (1 row) select pldbg_drop_breakpoint(1,16919,9); pldbg_drop_breakpoint ----------------------t (1 row) --查看断点信息 select pldbg_get_breakpoints(1); pldbg_get_breakpoints ----------------------------(16919,-1,"") (16919,7,"") (16919,-1,"") (3 rows) --设置全局断点 select pldbg_set_global_breakpoint(1,16919,11,null); pldbg_set_global_breakpoint ----------------------------t (1 row) --查看断点信息 select pldbg_get_breakpoints(1); pldbg_get_breakpoints ----------------------------(16919,11,"") (16919,-1,"") (16919,7,"") (16919,-1,"") (4 rows) --设置断点行号为 0 时无效 select pldbg_drop_breakpoint(1,16919,0); pldbg_drop_breakpoint ----------------------f (1 row) 531 第 67 章 PLDBGAPI --设置断点行号为 NULL 时无效 select pldbg_drop_breakpoint(1,16919,NULL); pldbg_drop_breakpoint ----------------------(1 row) --查看断点信息，0 和 NULL 断点都未设置成功 select pldbg_get_breakpoints(1); pldbg_get_breakpoints ----------------------(16919,11,"") (16919,-1,"") (16919,7,"") (16919,-1,"") (4 rows) --查看版本信息 select * from pldbg_get_proxy_info(); serverversionstr | serverversionnum | proxyapiver | serverprocessid ---------------------------------------------------------------------------------------------------------+-----------------+-------------+----------------PostgreSQL 12.1 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-36), 64-bit | 120001 | 3 | 311197 (1 row) 67.5 插件 pldbgapi 卸载方法 卸载 pldbgapi 插件接口，只需要执行以下命令： -- 删除插件 drop extension pldbgapi; 67.6 插件 pldbgapi 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.1 升级到 1.2： 532 第 67 章 PLDBGAPI ALTER EXTENSION pldbgapi UPDATE TO '1.2'; 533 第 68 章 PLSQL_PLDBGAPI 68章 plsql_pldbgapi 第 68.1 插件 plsql_pldbgapi 简介 插件 plsql_pldbgapi 是 KingbaseES 的一个扩展插件。主要用于 PL/SQL 语言的存储过程、函数、包、触发器 函数、匿名块、object type 方法的代码调试。 • 插件名为 plsql_pldbgapi • 插件版本 V1.2 68.2 插件 plsql_pldbgapi 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。因此只需要在客户端工具执行 create extension 命令即可。 -- 创建插件 create extension plsql_pldbgapi; 注意: 在当前模式和 plsql_debug 模式下均创建了一套调试接口，因此在任意模式下调试接口可通过模式限定调用。 68.3 插件 plsql_pldbgapi 的参数配置 plsql_pldbgapi 扩展插件无需配置任何参数。 534 第 68 章 PLSQL_PLDBGAPI 插件 plsql_pldbgapi 使用方法 68.4 68.4.1 plsql_debugger 调试流程 以下详细介绍其局部断点调试和全局断点调试流程的命令行调试流程。只是在目标后端与调试端建立连接的流程 有稍微差别，实际的调试的流程总体一致。 plsql_debugger 的调试操作是建立在目标后端和调试端正常通信的前提下，其详细的调试流程如下： 1. 创建监听，局部断点调试根据调试对象的 OID 去建立监听，全局断点调试则不需要带调试对象的 OID 而是创 建全局监听。 2. 创建连接，全局调试与局部调试的连接方式稍有不同，对于局部调试，首先是调用待调试的对象，让目标 后端进程以通信服务器端的身份发起连接，然后在调试端调用端口连接函数 plsql_pldbg_attah_to_port 让 调 试 端 以 通 信 客 户 端 的 身 份 与 目 标 后 端 建 立 连 接； 对 于 全 局 断 点 调 试， 先 设 置 全 局 断 点， 然 后 调 用 plsql_pldbg_wait_for_target 函数发起连接并等待接受目标后端的连接。此时调用待调试的对象就可以与 调试端建立通信连接。 3. 调试设置，可以根据需要设置和删除断点信息，包括局部断点和全局断点。 4. 执行调试操作，plsql_debugger 提供了三种调试执行的方式，分别为单步进入（step into）、单步跳过（step over）以及继续执行（continue）。 5. 信息查询，在调试执行的过程中，可以查询源代码信息，查询和修改变量值，查询调用堆栈以及当前系统版本 等。 68.4.2 接口函数 plsql_debugger 调试工具支持对 PL/SQL 语言的存储过程、函数、包、触发器函数、匿名块、object type 方法 进行代码调试操作，包括操作断点、执行代码、调试数据、查看调用堆栈、查看源码信息、查看版本信息等功能。并 提供局部断点调试与全局断点调试两种调试模式。 调试接口函数列表如下： 表 68.4.1: 接口函数列表 接口函数 简介 plsql_oid_debug 函数 创建局部监听 plsql_oid_debug_number 函数 对指定行设置断点 plsql_pldbg_attach_to_port 函数 连接目标后端 plsql_pldbg_create_listener 函数 创建全局监听 见续表 535 第 68 章 PLSQL_PLDBGAPI 表 68.4.1 – 续表 接口函数 简介 plsql_pldbg_set_global_breakpoint 函数 设置全局断点 plsql_pldbg_wait_for_target 函数 等待连接 plsql_pldbg_set_breakpoint 函数 设置断点 plsql_pldbg_get_breakpoints 函数 查询断点 plsql_pldbg_drop_breakpoint 函数 删除断点 plsql_pldbg_wait_for_breakpoint 函数 返回建立连接时断点所在行的信息 plsql_pldbg_step_into 函数 单步进入（step into） plsql_pldbg_step_over 函数 单步跳过（step over） plsql_pldbg_continue 函数 继续执行（continue） plsql_pldbg_step_out 函数 单步跳出（step out） plsql_pldbg_step_end 函数 步至方法结束 plsql_pldbg_run_to_next_exception 函数 进入下一个异常 plsql_pldbg_run_to_cursor_line 函数 运行至光标处 plsql_pldbg_alter_breakpoint_hit_number 函数 修改断点击中次数 plsql_pldbg_alter_breakpoint_msg 函数 修改断点的描述信息 plsql_pldbg_alter_breakpoint_status 函数 修改指定断点的状态 plsql_pldbg_alter_all_breakpoint_status 函数 修改全部断点的状态 plsql_pldbg_set_breakpoint_src 函数 插入或更新源断点的状态和信息 plsql_pldbg_get_breakpoints_src 函数 获取当前会话的本地源断点信息 plsql_pldbg_set_exception_breakpoint_src 函数 插入或更新异常断点的状态和信息 plsql_pldbg_get_exception_breakpoints_src 函数 获取所有异常断点的状态和信息 plsql_pldbg_drop_exception_breakpoint 函数 删除异常断点 plsql_pldbg_drop_all_breakpoint 函数 删除所有本地源断点和所有异常断点 plsql_pldbg_abort_target 函数 中止执行 见续表 536 第 68 章 PLSQL_PLDBGAPI 表 68.4.1 – 续表 接口函数 简介 plsql_pldbg_get_variables 函数 查看变量 plsql_pldbg_deposit_value 函数 修改变量 plsql_pldbg_get_stack 函数 查看堆栈信息 plsql_pldbg_select_frame 函数 追溯堆栈信息 plsql_pldbg_get_source 函数 查询源代码信息 plsql_extend_get_proc_ddl 函数 获取函数、存储过程源码 plsql_pldbg_get_proxy_info 函数 查询当前系统版本信息 plsql_pldbg_set_connection_timeout 函数 目标会话等待连接的超时设置 plsql_pldbg_set_operation_timeout 函数 目标会话等待调试会话操作命令的超时设置 68.4.2.1 plsql_oid_debug 函数 功能描述 在同一个 session 下负责监听该调试对象，创建监听状态。该函数在建立监听的过程中会设置一个系统默认断 点，行号为‘-1’。 语法格式 FUNCTION plsql_oid_debug( functionOID OID ) RETURNS INTEGER 参数说明 参数名称 描述 functionOID 存储过程、函数、包、触发器函数、object type 方法、匿名块的 oid，其中匿名块为 9999 返回值说明 调用成功返回 0，调用失败无返回值，存在报错信息如下： 1. 当 OID 输入为 0 时报错信息：no target specified。 2. 当 OID 无效时报错信息：cache lookup failed for function。 3. 当不是 owner 或 superuser 时报错信息：must be owner or superuser to create a breakpoint。 537 第 68 章 PLSQL_PLDBGAPI 68.4.2.2 plsql_oid_debug_number 函数 功能描述 对指定调试对象的指定行下监听断点。 语法格式 FUNCTION plsql_oid_debug_number(func OID, linenumber INTEGER default -1) RETURNS INTEGER 参数说明 参数名称 描述 func 调试对象的 OID linenumber 调试对象的指定行，默认值为-1 返回值说明 断点设置成功则返回 0；断点设置失败则会进行报错。 参数异常说明 参数名称 用例 结果 fucn 0 报错 no target specified 不存在 PLSQL 对象 OID 报错 cache lookup failed xxx 不是当前 oid 的 owner 且不是超级用户 must be owner or superuser to create a breakpoint NULL 返回 NULL NULL 返回 NULL linenumber 68.4.2.3 plsql_pldbg_attach_to_port 函数 功能描述 此函数用于响应 PLDBGBREAK 端口号。该函数连接到监听给定端口的 Target Backend 端，从而形成 Debugger Client，启动调试过程，等待后续调试工作。一个 Debugger Client 能够响应多个不同 PLDBGBREAK 端口，即 可以支持多个并发会话。 语法格式 FUNCTION plsql_pldbg_attach_to_port(portNumber INTEGER) RETURNS INTEGER 538 第 68 章 PLSQL_PLDBGAPI 参数说明 参数名称 描述 portNumber 调用调试对象显示的进程 ID 号 返回值说明 返回标识此特定调试的会话句柄。 68.4.2.4 plsql_pldbg_create_listener 函数 功能描述 创建一个 TCP 端口，为全局断点创建一个监听器，方便后续函数连接到该目标进程。 语法格式 FUNCTION plsql_pldbg_create_listener() RETURNS INTEGER 返回值说明 调用成功返回 debug_session 号。 68.4.2.5 plsql_pldbg_set_global_breakpoint 函数 功能描述 创建一个全局断点。 语法格式 FUNCTION plsql_pldbg_set_global_breakpoint( session INT, FUNCTION OID, lineNumber INT, targetPID INT ) RETURNS boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 FUNCTION 调试对象的 OID lineNumber 行号（可为 NULL） targetPID 目标端 PID（可为 NULL） 539 第 68 章 PLSQL_PLDBGAPI 返回值说明 调用成功返回 t，调用失败会报错。 68.4.2.6 plsql_pldbg_wait_for_target 函数 功能描述 发起 socket 连接，等待目标后端进程调用调试对象来连接到调试端，以触发全局断点。 语法格式 FUNCTION plsql_pldbg_wait_for_target( session INTEGER ) RETURNS INTEGER 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 调用成功返回 target backend 的 PID。 68.4.2.7 plsql_pldbg_set_breakpoint 函数 功能描述 在目标进程中设置一个“局部”断点。 此函数将 PLDBG_SET_BREAKPOINT 指令发送到 Targert Backend 端，在调试对象的指定位置设置断点， 然后等待下一个可执行语句到达该目标断点。 语法格式 FUNCTION plsql_pldbg_set_breakpoint( session INTEGER, FUNCTION OID, lineNumber INTEGER ) RETURNS boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄需要设置的断点行号 FUNCTION 调试对象的 OID lineNumber 若行号传入为 NULL，不会报错也不会设置断点 540 第 68 章 PLSQL_PLDBGAPI 返回值说明 断点设置成功返回为 t，断点设置失败返回为 f。 68.4.2.8 plsql_pldbg_get_breakpoints 函数 功能描述 显示设置的所有断点。此函数将 PLDBG_GET_BREAKPOINTS 指令发送到 Targert Backend 端，返回查询到 的断点元组信息。如果没有断点信息，则返回为空。 语法格式 FUNCTION plsql_pldbg_get_breakpoints( session INTEGER ) RETURNS SETOF breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返回一组“breakpoint”元组信息，该元组信息包括调试对象的 OID，断点设置的行号 lineNumber，Target 端 的名字 targetName。 68.4.2.9 plsql_pldbg_drop_breakpoint 函数 功能描述 在目标进程中删除一个指定行号的断点。此函数将 PLDBG_CLEAR_BREAKPOINT 指令发送到 Targert Backend 端，删除指定断点信息，并返回删除成功与否的状态。 语法格式 FUNCTION plsql_pldbg_drop_breakpoint( session INTEGER, FUNCTION OID, lineNumber INTEGER ) RETURNS boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 FUNCTION 调试对象的 OID lineNumber 所要删除断点的行号 541 第 68 章 PLSQL_PLDBGAPI 返回值说明 断点删除成功返回 t，断点删除失败返回 f。 68.4.2.10 plsql_pldbg_wait_for_breakpoint 函数 功能描述 调用该函数，可以返回刚建立连接时断点所在行的信息。 语法格式 FUNCTION plsql_pldbg_wait_for_breakpoint( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为一个“breakpoint”的元组，该元组包含调试对象的 OID 以及刚建立连接时停止的行号。 68.4.2.11 plsql_pldbg_step_into 函数 功能描述 单步执行，遇到子函数或子存储过程会进入到相应的部分。此函数将 PLDBG_STEP_INTO 命令发送到 Targert Backend，等待目标后端进程执行语句后，等待下一个可执行语句到达目标。 语法格式 FUNCTION plsql_pldbg_step_into( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组（但不一定是真正的断点信息，因为单步执行有可能遇到断点，有可能 没有遇见断点）。该元组包含调试对象的 OID 以及目标当前停止的行号，以及调试对象名。 542 第 68 章 PLSQL_PLDBGAPI 68.4.2.12 plsql_pldbg_step_over 函数 功能描述 单步执行，遇见子函数或子存储过程会跳过内部执行过程。此函数将 PLDBG_STEP_OVER 命令发送到 Targert Backend，待目标后端进程执行语句后，等待下一个可执行语句到达目标，并将执行后需要返回的结果返回。 语法格式 FUNCTION plsql_pldbg_step_over( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组（但不一定是真正的断点信息，因为单步执行有可能遇到断点，有可能 没有遇见断点）。该元组包含调试对象的 OID 以及目标当前停止的行号，以及调试对象名。 68.4.2.13 plsql_pldbg_continue 函数 功能描述 从 当 前 位 置 继 续 执 行， 直 到 遇 见 下 一 个 断 点， 如 果 没 有 断 点， 将 直 接 执 行 到 调 试 对 象 的 最 后。 此 函 数 将 “PLDBG_CONTINUE”指令发送到 Targert Backend 端，目标后端进程执行，然后等待目标到达下一个断点，并 返回相应的结果信息。 语法格式 FUNCTION plsql_pldbg_continue( session INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 此函数返回类型为“breakpoint”的元组，该元组包含调试对象的 OID 以及目标当前停止的行号，以及调试对象 名。 543 第 68 章 PLSQL_PLDBGAPI 68.4.2.14 plsql_pldbg_step_out 函数 功能描述 与断点无关；跳回上层堆栈的下一条语句。 语法格式 FUNCTION plsql_pldbg_step_out( session INTEGER ) RETURNS plsql_breakpoint 参数说明 参数名称 描述 session 会话句柄 返回值说明 返回一个 plsql_breakpoint 结构，用来表示位置信息。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 68.4.2.15 plsql_pldbg_step_end 函数 功能描述 断点优先；步至当前堆栈末尾语句。最后一条语句作用类似于 step over。 语法格式 FUNCTION plsql_pldbg_step_end( session INTEGER ) RETURNS plsql_breakpoint 参数说明 参数名称 描述 session 会话句柄 返回值说明 返回一个 plsql_breakpoint 结构，用来表示位置信息。 544 第 68 章 PLSQL_PLDBGAPI 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 68.4.2.16 plsql_pldbg_run_to_next_exception 函数 功能描述 断点优先；停在触发异常语句的地方（包括异常处理模块的语句），能够停在未生成调试信息的区域。 语法格式 FUNCTION plsql_pldbg_run_to_next_exception( session INTEGER ) RETURNS plsql_breakpoint 参数说明 参数名称 描述 session 会话句柄 返回值说明 返回一个 plsql_breakpoint 结构，用来表示位置信息。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 68.4.2.17 plsql_pldbg_run_to_cursor_line 函数 功能描述 无视断点，直接调试目标行代码。调试途中的断点，状态保持不变。必须要生成调试信息才可以进行调试。 语法格式 545 第 68 章 PLSQL_PLDBGAPI FUNCTION plsql_pldbg_run_to_cursor_line( session INTEGER, func OID, linenumber INTEGER ) RETURNS plsql_ breakpoint 参数说明 参数名称 描述 session 会话句柄 func 调试对象的 OID linenumber 调试对象的指定行 返回值说明 返回一个 plsql_breakpoint 结构，用来表示位置信息。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle NULL 返回 NULL 嵌套函数 OID 报错 Debugging nested functions requires the use of the outer oid NULL 返回 NULL func linenumber 68.4.2.18 plsql_pldbg_alter_breakpoint_hit_number 函数 功能描述 修改断点击中次数，当断点击中的总次数与设定断点次数相同则进行中断。击中断点后，后期则每次击中断点会 进行中断。 语法格式 FUNCTION plsql_pldbg_alter_breakpoint_hit_number( session INTEGER, func OID, linenumber INTEGER, hitnumber INTEGER) RETURNS boolean 参数说明 546 第 68 章 PLSQL_PLDBGAPI 参数名称 描述 session 会话句柄 func 调试对象的 OID linenumber 调试对象的指定行 hitnumber 设置的断点击中次数，小于 1 则设置为 1 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle func NULL 返回 NULL linenumber NULL 返回 NULL hitnumber <1 hitnumber 设置为 1 使用说明 1. 未找到断点信息返回 false。 2. 无论执行什么操作，只要该行上有断点就需要计入内部执行次数。 3. 再次调用 PLSQL 时，当前断点内部击中次数会重新计数。 4. 更新断点击中次数后，则会更新断点内部击中次数。 5. 该方式也被称为断点传送计数。 68.4.2.19 plsql_pldbg_alter_breakpoint_msg 函数 功能描述 修改断点的描述信息。 语法格式 FUNCTION plsql_pldbg_alter_breakpoint_msg( session INTEGER, func OID, linenumber INTEGER, breakpointdesc text) RETURNS boolean 547 第 68 章 PLSQL_PLDBGAPI 参数说明 参数名称 描述 session 会话句柄 func 调试对象的 OID linenumber 调试对象的指定行 breakpointdesc 断点的描述信息，可设置为 NULL 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle func NULL 返回 NULL linenumber NULL 返回 NULL 68.4.2.20 plsql_pldbg_alter_breakpoint_status 函数 功能描述 修改指定断点的状态。 语法格式 FUNCTION plsql_pldbg_alter_breakpoint_status( session INTEGER, func OID, linenumber INTEGER, breakpointstatus boolean) RETURNS boolean 参数说明 548 第 68 章 PLSQL_PLDBGAPI 参数名称 描述 session 会话句柄 func 调试对象的 OID linenumber 调试对象的指定行 breakpointstatus 断点状态 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle func NULL 返回 NULL linenumber NULL 返回 NULL breakpointstatus NULL 返回 NULL 使用说明 断点状态分为启用与禁用，当断点状态为禁用时，则断点击中后不会进行中断。若指定断点不存在则返回 false。 68.4.2.21 plsql_pldbg_alter_all_breakpoint_status 函数 功能描述 修改全部断点的状态。 语法格式 FUNCTION plsql_pldbg_alter_all_breakpoint_status( session INTEGER, breakpointstatus boolean) RETURNS boolean 参数说明 549 第 68 章 PLSQL_PLDBGAPI 参数名称 描述 session 会话句柄 breakpointstatus 设置全部断点的状态 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle NULL 返回 NULL breakpointstatus 68.4.2.22 plsql_pldbg_set_breakpoint_src 函数 功能描述 插入或更新源断点的状态、击中次数、描述信息、条件信息。 语法格式 FUNCTION plsql_pldbg_set_breakpoint_src(session INTEGER, func OID, linenumber INTEGER, breakpointstatus boolean, hitnumber INTEGER, breakpointdesc text, breakpointcond text default NULL) returns boolean 参数说明 参数名称 描述 session 会话句柄 func 对象的 OID linenumber 行号 breakpointstatus 断点状态 hitnumber 断点击中次数 breakpointdesc 断点描述信息 breakpointcond 断点条件，默认值为 NULL 550 第 68 章 PLSQL_PLDBGAPI 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle NULL 返回 NULL 嵌套函数 OID 报错 Debugging nested functions requires the use of the outer oid linenumber NULL 返回 NULL breakpointstatus NULL 返回 NULL hitnumber NULL 返回 NULL <1 hitnumber 设置为 1 NULL 将断点描述信息设置为空串 func breakpointdesc 使用说明 不支持条件断点，因此 breakpointcond 不生效。更新源断点后，内部当前击中次数会进行重置。 68.4.2.23 plsql_pldbg_get_breakpoints_src 函数 功能描述 获取当前会话的本地源断点信息。 语法格式 FUNCTION plsql_pldbg_get_breakpoints_src(in session INTEGER, out func OID, out linenumber INTEGER, out breakpointstatus boolean, out hitnumber INTEGER, out breakpointdesc text, out breakpointcond text) returns setof record AS '$libdir/plsql_plugin_debugger' LANGUAGE C STRICT 参数说明 551 第 68 章 PLSQL_PLDBGAPI 参数名称 描述 session 会话句柄 func 对象的 OID linenumber 行号 breakpointstatus 断点状态 hitnumber 断点击中次数 breakpointdesc 断点描述信息 breakpointcond 断点条件 返回值说明 返回一个多行多列的断点信息数据。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 68.4.2.24 plsql_pldbg_set_exception_breakpoint_src 函数 功能描述 插入或更新异常断点的状态、击中次数、描述信息、条件信息。 语法格式 FUNCTION plsql_pldbg_set_exception_breakpoint_src(session INTEGER, exceptionsqlcode INTEGER, linenumber INTEGER, breakpointstatus boolean, hitnumber INTEGER, breakpointdesc text, breakpointcond text default NULL) returns boolean 参数说明 552 第 68 章 PLSQL_PLDBGAPI 参数名称 描述 session 会话句柄 exceptionsqlcode 异常的 sqlcode，当为 0 时可以匹配所有异常 linenumber 行号，必须填写-1 breakpointstatus 异常断点状态 hitnumber 异常断点击中次数 breakpointdesc 异常断点描述信息 breakpointcond 异常断点条件，默认值为 NULL 返回值说明 设置成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle exceptionsqlcode NULL 返回 NULL linenumber NULL 返回 NULL 不等于-1 报错 The line number of an exception breakpoint can only be -1. breakpointstatus NULL 返回 NULL hitnumber NULL 返回 NULL <1 hitnumber 设置为 1 NULL 将断点描述信息设置为空串 breakpointdesc 使用说明 1. 不支持条件断点，因此 breakpointcond 不生效。 2. 通过“select * from SYS_GET_PREDEFINED_EXCEPTION_DETAIL()”查询异常 sqlcode。 3. 当 exceptionsqlcode 为 0 时，能够匹配所有的异常。 4. plsql_pldbg_alter_all_breakpoint_status、plsql_pldbg_drop_all_breakpoint 会影响异常断点。 553 第 68 章 PLSQL_PLDBGAPI 5. 异常断点更新后，内部击中次数会进行重置。 6. 再次执行 PLSQL 时会重新计数断点击中次数。 68.4.2.25 plsql_pldbg_get_exception_breakpoints_src 函数 功能描述 获取所有异常断点的状态、击中次数、描述信息、条件信息。 语法格式 FUNCTION plsql_pldbg_get_exception_breakpoints_src(in session INTEGER, out exceptionsqlcode INTEGER, out linenumber INTEGER, out breakpointstatus boolean, out hitnumber INTEGER, out breakpointdesc text, out breakpointcond text) returns setof record 参数说明 参数名称 描述 session 会话句柄 exceptionsqlcode 异常的 sqlcode linenumber 行号 breakpointstatus 异常断点状态 hitnumber 异常断点击中次数 breakpointdesc 异常断点描述信息 breakpointcond 异常断点条件 返回值说明 返回一个多行多列的断点信息数据。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 使用说明 不支持条件断点，因此 breakpointcond 不生效。 554 第 68 章 PLSQL_PLDBGAPI 68.4.2.26 plsql_pldbg_drop_exception_breakpoint 函数 功能描述 删除异常断点。 语法格式 FUNCTION plsql_pldbg_drop_exception_breakpoint( session INTEGER, exceptionsqlcode INTEGER, linenumber INTEGER ) RETURNS boolean 参数说明 参数名称 描述 session 会话句柄 exceptionsqlcode 异常的 sqlcode linenumber 异常断点的行号必须为 返回值说明 删除成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle NULL 返回 NULL 不等于-1 报错 The line number of an exception breakpoint can only be -1 NULL 返回 NULL exceptionsqlcode linenumber 使用说明 不支持条件断点，因此 breakpointcond 不生效。 68.4.2.27 plsql_pldbg_drop_all_breakpoint 函数 功能描述 删除所有本地源断点和所有异常断点。 555 第 68 章 PLSQL_PLDBGAPI 语法格式 FUNCTION plsql_pldbg_drop_all_breakpoint(session INTEGER) RETURNS boolean 参数说明 参数名称 描述 session 会话句柄 返回值说明 删除成功返回 true，否则返回 false。 参数异常说明 参数名称 用例 结果 session NULL 返回 NULL 会话句柄无效 报错 invalid session handle 使用说明 不支持条件断点，因此 breakpointcond 不生效。 68.4.2.28 plsql_pldbg_abort_target 函数 功能描述 终止当前的执行。此函数将 PLDBG_ABORT 命令发送到 Targert Backend，然后终止当前的执行，并返回终止 成功与否的状态。 语法格式 FUNCTION plsql_pldbg_abort_target( session INTEGER ) RETURNS SETOF boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 终止成功返回 t。 556 第 68 章 PLSQL_PLDBGAPI 68.4.2.29 plsql_pldbg_get_variables 函数 功能描述 获取一个变量或者参数的信息列表。此函数将 PLDBG_GET_VARIABLES 指令发送到 Targert Backend 端， 服务器查询到所有变量的信息后返回变量或参数的信息列表。 语法格式 FUNCTION plsql_pldbg_get_variables( session INTEGER ) RETURNS SETOF var 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返回一个 var 元 组 集 合， 包 含 信 息：VarName；Class；lineNumber；Unique；isConst；notNull； dataTypeOID；value(rest of string)。其中每个变量的含义如下： 1. varName: 变量或参数的名称； 2. Class：变量或参数的类别。如果调试对象有输入参数时，该参数类型将标记为“A”，语句块里的参数将标记 为“L”； 3. lineNumber：声明变量或参数的行号； 4. Unique：标记该名称在调试对象范围内是否唯一，如果名称不是唯一，调试器客户端将使用行号来区分同名的 变量或参数； 5. isConst：标记变量或参数是否为常量； 6. notNull：标记变量或参数是否不为空； 7. dataTypeOID：该变量 sys_type 中对应的 OID； 8. value(rest of string)：变量的值。 68.4.2.30 plsql_pldbg_deposit_value 函数 功能描述 在调试过程中，将一个新值赋给指定的变量。此函数将 PLDBG_DEPOSIT 指令发送到 Targert Backend 端，服 务器查询该变量然后修改变量的值，最后将修改成功与否的状态返回。 语法格式 557 第 68 章 PLSQL_PLDBGAPI FUNCTION plsql_pldbg_deposit_value( session INTEGER, varName TEXT, lineNumber INTEGER, value TEXT ) RETURNS boolean 参数说明 参数名称 描述 session 标识特定调试的会话句柄 varName 变量名 lineNumber 变量定义的行号 value 变量新值 返回值说明 新值设置成功返回 t，新值设置失败返回 f。 68.4.2.31 plsql_pldbg_get_stack 函数 功能描述 从 Targert Backend 端获取调用堆栈信息。此函数将 PLDBG_GET_STACK 指令发送到 Targert Backend 端， 返回相应调用堆栈信息。 语法格式 FUNCTION plsql_pldbg_get_stack( session INTEGER ) RETURNS SETOF frame 参数说明 参数名称 描述 session 标识特定调试的会话句柄 返回值说明 返 回 一 组 堆 栈 框 架 信 息 元 组， 包 含：CallCount；targetName；funcOID；lineNumber；arguments(rest of string)。 1. CallCount: 堆栈深度。 2. targetName: 调用调试对象的名称。 3. funcOID: 调试对象 OID。 4. lineNumber: 当前停留的行号。 558 第 68 章 PLSQL_PLDBGAPI 5. arguments(rest of string): 参数的信息。 68.4.2.32 plsql_pldbg_select_frame 函数 功能描述 将调试器焦点（当前在堆栈中的执行位置）更改为指定的帧。此函数将 PLDBG_SELECT_FRAME 命令发送 到 Targert Backend，然后循环查询指定的帧，如果传入的帧不存在，将返回当前帧的信息，如果传入的帧信息存 在，将返回相应的查询信息。 语法格式 FUNCTION plsql_pldbg_select_frame( session INTEGER, frame INTEGER ) RETURNS breakpoint 参数说明 参数名称 描述 session 标识特定调试的会话句柄 frame 指定帧 返回值说明 此函数返回类型为“breakpoint”的元组，其中包含调试对象 OID，以及当前目标在选定帧中停止的行号。 68.4.2.33 plsql_pldbg_get_source 函数 功能描述 从 Target Backend 获取存储过程、函数、包、触发器函数、object type 方法、匿名块正在执行的源代码。此函 数将包含 PLDBG_GET_SOURCE，functionOID 的字符串发送到 Targert Backend，查询源代码信息并返回。 语法格式 FUNCTION plsql_pldbg_get_source( session INTEGER, func OID ) RETURNS TEXT 参数说明 参数名称 描述 session 标识特定调试的会话句柄 func 调试对象的 OID 返回值说明 559 第 68 章 PLSQL_PLDBGAPI 返回给定调试对象的源代码信息。 68.4.2.34 plsql_extend_get_proc_ddl 函数 功能描述 用以支撑 plsql_pldebugger 获取函数、存储过程源码。 语法格式 FUNCTION plsql_debug.plsql_extend_get_proc_ddl(func OID) returns text 参数说明 参数名称 描述 func 函数、存储过程的 oid。 返回值说明 函数、存储过程的源码。 参数异常说明 参数名称 用例 结果 func NULL 返回 NULL 0 报错 invalid object oid 不存在的 oid 报错 cache lookup failed for function 68.4.2.35 plsql_pldbg_get_proxy_info 函数 功能描述 获取服务器版本，Proxy Backend API 版本等信息。 语法格式 FUNCTION plsql_pldbg_get_proxy_info() RETURNS proxyInfo 返回值说明 返回服务器和代理 PAI 的版本信息。 560 第 68 章 PLSQL_PLDBGAPI 68.4.2.36 plsql_pldbg_set_connection_timeout 函数 功能描述 目标会话等待连接的超时设置。若目标会话等待超时，则进行报错处理。仅在目标端执行。 语法格式 FUNCTION plsql_pldbg_set_connection_timeout( timeout INTEGER ) RETURNS int 参数说明 参数名称 描述 timeout 目标会话等待连接的超时设置。单位为秒。 返回值说明 返回设置的时间。 参数异常说明 参数名称 用例 结果 timetout <0 返回 NULL NULL 返回 NULL 使用说明 内部默认连接超时为 1 小时。timeout 设置为 0 为不限制时间。超时报错 select() timeout in plsql_pldbgapi。 68.4.2.37 plsql_pldbg_set_operation_timeout 函数 功能描述 调试连接后，目标会话等待调试会话的操作超时设置。仅在目标端执行。 语法格式 FUNCTION plsql_pldbg_set_operation_timeout( timeout INTEGER ) RETURNS int 参数说明 参数名称 描述 timeout 目标会话等待调试会话操作命令的超时设置。单位为秒。 561 第 68 章 PLSQL_PLDBGAPI 返回值说明 返回设置的时间。 参数异常说明 参数名称 用例 结果 timeout <0 返回 NULL NULL 返回 NULL 使用说明 内部默认不限制时间。timeout 设置为 0 为不限制时间。超时报错 errors communicating with the proxy。 68.4.2.38 局部断点调试示例 创建调试环境和用例： --创建 plsql_debugger 环境 create extension plsql_pldbgapi; --创建用来调试的存储过程 \set SQLTERM / CREATE OR REPLACE PROCEDURE public.pro1() AS BEGIN raise notice '123'; raise notice 'success'; END; / CREATE OR REPLACE PROCEDURE public.pro4() AS declare i int := 2; begin i = 3; raise notice 'i= %',i; i = 4; raise notice 'i= %',i; raise notice '0:ready.....'; begin raise notice '1:ready.....'; call pro1(); begin raise notice 'success'; 562 第 68 章 PLSQL_PLDBGAPI end; end; end; / \set SQLTERM ; --查询出需要调试的存储过程的 oid select oid from sys_proc where proname = 'pro4'; oid ------16918 (1 row) application client： --应用端开启局部监听 select plsql_oid_debug(16918); plsql_oid_debug ------------------0 (1 row) --开始调试存储过程 pro4 call pro4(); NOTICE: PLDBGBREAK:3 --该进程控制器转交给另一进程，直至调试结束，3 为连接的端口号 debugger client： .. code:: --调试端连接 select plsql_pldbg_attach_to_port(3); plsql_pldbg_attach_to_port ---------------------1 (1 row) --查看源码 select plsql_pldbg_get_source(1,16918); plsql_pldbg_get_source -------------------------------------+ declare i int := 2; begin + + + 563 第 68 章 PLSQL_PLDBGAPI i = 3; + raise notice 'i= %',i; + i = 4; + raise notice 'i= %',i; + raise notice '0:ready.....'; + begin + raise notice '1:ready.....';+ call pro1(); + begin + raise notice 'success'; + end; end; + + end (1 row) --设置断点 select plsql_pldbg_set_breakpoint(1,16918,7); plsql_pldbg_set_breakpoint ---------------------------t (1 row) select plsql_pldbg_set_breakpoint(1,16918,12); plsql_pldbg_set_breakpoint ---------------------t (1 row) select plsql_pldbg_set_breakpoint(1,16918,15); plsql_pldbg_set_breakpoint ---------------------t (1 row) --获取当前设置的断点信息 select plsql_pldbg_get_breakpoints(1); plsql_pldbg_get_breakpoints ----------------------------(16918,15,"") (16918,7,"") (16918,12,"") (16918,-1,"") (4 rows) --单步执行，遇到子程序进入 564 第 68 章 PLSQL_PLDBGAPI select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16918,6,"pro4()") (1 row) select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16918,7,"pro4()") (1 row) select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16918,8,"pro4()") (1 row) --单步执行，遇到子程序跳过 select plsql_pldbg_step_over(1); plsql_pldbg_step_over ----------------------(16918,9,"pro4()") (1 row) --继续执行程序，直到断点处或者程序结束 select plsql_pldbg_continue(1); plsql_pldbg_continue ---------------------(16918,12,"pro4()") (1 row) --当 application client 执行完毕后，debug client 进程会挂起，直到 application client 再次执行测试调试对象 select plsql_pldbg_continue(1); application client： --应用端存储过程执行完成 call pro4(); NOTICE: PLDBGBREAK:3 NOTICE: i= 3 NOTICE: i= 4 NOTICE: 0:ready..... NOTICE: 1:ready..... NOTICE: 123 565 第 68 章 PLSQL_PLDBGAPI NOTICE: success NOTICE: success CALL --再次调起 call pro4(); debugger client： --调试端进入调试状态，调用 plsql_pldbg_abort_target，终止调试 select plsql_pldbg_abort_target(1); plsql_pldbg_abort_target -------------------t (1 row) application client： --当 debug client 调用 select plsql_pldbg_abort_target(1) 后，执行被终止 call pro4(); ERROR: canceling statement due to user request CONTEXT: PL/SQL 68.4.2.39 FUNCTION pro4() line 5 at assignment 全局断点调试示例 debugger client： --调试端创建全局监听 select plsql_pldbg_create_listener(); plsql_pldbg_create_listener ----------------------1 (1 row) --设置全局断点，未指定行号默认为-1，即 BEGIN 块的第一行 select plsql_pldbg_set_global_breakpoint(1,16918,null,null); plsql_pldbg_set_global_breakpoint ----------------------------t (1 row) --等待测试函数被调用，无测试函数调用该进程会挂起 select plsql_pldbg_wait_for_target(1); application client： 566 第 68 章 PLSQL_PLDBGAPI --应用端执行测试函数 call pro4(); debugger client： --测试函数调用后，返回测试函数 session 的进程号，开始调试 select plsql_pldbg_wait_for_target(1); plsql_pldbg_wait_for_target ----------------------------427689 (1 row) --设置局部断点 select plsql_pldbg_set_breakpoint(1,16918,5); plsql_pldbg_set_breakpoint ---------------------t (1 row) --设置全局断点 select plsql_pldbg_set_global_breakpoint(1,16918,12,null); plsql_pldbg_set_global_breakpoint ----------------------------t (1 row) --获取变量信息 select plsql_pldbg_get_variables(1); plsql_pldbg_get_variables --------------------------(i,L,3,t,f,f,23,2) (1 row) --单步进入 select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16918,6,"pro4()") (1 row) select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16918,7,"pro4()") 567 第 68 章 PLSQL_PLDBGAPI (1 row) --获取修改后的变量信息 select plsql_pldbg_get_variables(1); plsql_pldbg_get_variables --------------------(i,L,3,t,f,f,23,3) (1 row) --继续执行到断点处 select plsql_pldbg_continue(1); plsql_pldbg_continue ---------------------(16918,12,"pro4()") (1 row) --单步进入子程序 pro1 select plsql_pldbg_step_into(1); plsql_pldbg_step_into ----------------------(16917,3,"pro1()") (1 row) --获取堆栈信息 select plsql_pldbg_get_stack(1); plsql_pldbg_get_stack -------------------------(0,"pro1()",16917,3,"") (1,"pro4()",16918,12,"") (2 rows) --追溯堆栈信息 select plsql_pldbg_select_frame(1,1); plsql_pldbg_select_frame -------------------------(16918,12,"pro4()") (1 row) --继续执行到程序结束后挂起，等待下一次程序调用 select plsql_pldbg_continue(1); application client： --应用端程序执行完成 call pro4(); 568 第 68 章 PLSQL_PLDBGAPI NOTICE: i= 3 NOTICE: i= 4 NOTICE: 0:ready NOTICE: 1:ready NOTICE: 123 NOTICE: success NOTICE: success CALL 68.4.2.40 修改调试时数据及删除断点调试示例 创建测试环境和用例： --创建 plsql_debugger 环境 create extension plsql_pldbgapi; --创建用来调试的存储过程 \set SQLTERM / create or replace procedure pro5(i int) as declare j int; begin raise notice 'i = %',i; j = i; raise notice 'j = %',j; j = 1; raise notice 'j = %',j; i = 2; raise notice 'i = %',i; end; / \set SQLTERM ; --查询出需要调试的存储过程的 oid select oid from sys_proc where proname = 'pro5'; oid ------16919 (1 row) debugger client： --创建全局监听 select plsql_pldbg_create_listener(); 569 第 68 章 PLSQL_PLDBGAPI plsql_pldbg_create_listener ----------------------1 (1 row) --设置全局断点 select plsql_pldbg_set_global_breakpoint(1,16919,null,null); plsql_pldbg_set_global_breakpoint ----------------------------t (1 row) --等待测试存储过程调用 select plsql_pldbg_wait_for_target(1); application client： call pro5(3); debugger client： --子程序已调用，开始调试 select plsql_pldbg_wait_for_target(1); plsql_pldbg_wait_for_target ----------------------------120947 (1 row) --返回建立连接时断点所在行的信息 (全局断点行号为 null，默认当前在 BEGIN 块的第一行) select plsql_pldbg_wait_for_breakpoint(1); plsql_pldbg_wait_for_breakpoint --------------------------------(16919,5,"pro5(integer)") (1 row) --单步执行 select plsql_pldbg_step_into(1); plsql_pldbg_step_into --------------------------(16919,6,"pro5(integer)") (1 row) --获取存储过程源码 select plsql_pldbg_get_source(1,16919); plsql_pldbg_get_source 570 第 68 章 PLSQL_PLDBGAPI ----------------------------+ declare j int; begin + + + raise notice 'i = %',i;+ j = i; + raise notice 'j = %',j;+ j = 1; + raise notice 'j = %',j;+ i = 2; + raise notice 'i = %',i;+ end (1 row) --查看变量的值 select plsql_pldbg_get_variables(1); plsql_pldbg_get_variables --------------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,NULL) (2 rows) --修改变量 j 的值 select plsql_pldbg_deposit_value(1, 'j', 3, '10'); plsql_pldbg_deposit_value --------------------t (1 row) --再次查看变量 j 的值，已被改变 select plsql_pldbg_get_variables(1); plsql_pldbg_get_variables --------------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,10) (2 rows) --单步执行，变量 j 在程序中被赋值 select plsql_pldbg_step_into(1); plsql_pldbg_step_into --------------------------(16919,7,"pro5(integer)") (1 row) 571 第 68 章 PLSQL_PLDBGAPI --查看变量 j 的值，已改变 select plsql_pldbg_get_variables(1); plsql_pldbg_get_variables --------------------------(i,A,0,t,f,f,23,3) (j,L,3,t,f,f,23,3) (2 rows) --设置局部断点 select plsql_pldbg_set_breakpoint(1,16919,5); plsql_pldbg_set_breakpoint ---------------------t (1 row) select plsql_pldbg_set_breakpoint(1,16919,7); plsql_pldbg_set_breakpoint ---------------------t (1 row) select plsql_pldbg_set_breakpoint(1,16919,9); plsql_pldbg_set_breakpoint ---------------------t (1 row) --查看断点信息 select plsql_pldbg_get_breakpoints(1); plsql_pldbg_get_breakpoints ----------------------------(16919,-1,"") (16919,5,"") (16919,9,"") (16919,7,"") (16919,-1,"") (5 rows) --删除断点 select plsql_pldbg_drop_breakpoint(1,16919,5); plsql_pldbg_drop_breakpoint ----------------------t (1 row) 572 第 68 章 PLSQL_PLDBGAPI select plsql_pldbg_drop_breakpoint(1,16919,9); plsql_pldbg_drop_breakpoint ----------------------t (1 row) --查看断点信息 select plsql_pldbg_get_breakpoints(1); plsql_pldbg_get_breakpoints ----------------------------(16919,-1,"") (16919,7,"") (16919,-1,"") (3 rows) --设置全局断点 select plsql_pldbg_set_global_breakpoint(1,16919,11,null); plsql_pldbg_set_global_breakpoint ----------------------------t (1 row) --查看断点信息 select plsql_pldbg_get_breakpoints(1); plsql_pldbg_get_breakpoints ----------------------------(16919,11,"") (16919,-1,"") (16919,7,"") (16919,-1,"") (4 rows) --设置断点行号为 0 时无效 select plsql_pldbg_drop_breakpoint(1,16919,0); plsql_pldbg_drop_breakpoint ----------------------f (1 row) --设置断点行号为 NULL 时无效 select plsql_pldbg_drop_breakpoint(1,16919,NULL); plsql_pldbg_drop_breakpoint ----------------------(1 row) 573 第 68 章 PLSQL_PLDBGAPI --查看断点信息，0 和 NULL 断点都未设置成功 select plsql_pldbg_get_breakpoints(1); plsql_pldbg_get_breakpoints ----------------------------(16919,11,"") (16919,-1,"") (16919,7,"") (16919,-1,"") (4 rows) --查看版本信息 select * from plsql_pldbg_get_proxy_info(); serverversionstr | serverversionnum | proxyapiver | serverprocessid ------------------------------------------------------------------------------------------------------------+------------------+-------------+----------------KingbaseES V008R006 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 4.8.5 20150623 (Red Hat 4.8.5-36), 64-bit | 8 | 3 | 437829 (1 row) 68.5 插件 plsql_pldbgapi 卸载方法 卸载 plsql_pldbgapi 插件接口，只需要执行以下命令： -- 删除插件 drop extension plsql_pldbgapi; 68.6 插件 plsql_pldbgapi 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 1.1 升级到 1.2： ALTER EXTENSION plsql_pldbgapi UPDATE TO '1.2'; 574 第 69 章 PLSQL_PLPROFILER 69章 plsql_plprofiler 第 插件 plsql_plprofiler 简介 69.1 插件 plsql_plprofiler 是 KingbaseES 的一个扩展插件。plsql_plprofiler 插件支持收集分析器（性能）数据以提高 性能或确定 PL/SQL 应用程序的代码覆盖率。应用程序可以使用代码覆盖率数据来集中他们的增量测试工作。 此插件可以为所有 PL/SQL 单元生成分析信息，此信息包括每行的执行次数、执行该行所花费的总时间以及该 行在多次执行中消耗的最长时间。 plsql_plprofiler 中的监听方式分为本地监控、全局监控、以及指定会话监控三种。其中，本地监控模式是指只对 当前 session 运行的对象进行监控；全局监控模式是指对所有 session 运行的对象进行监控；指定会话模式是指对某个 指定 session 上运行的对象进行监控。 三种模式同时启动的情况下优先级是全局监控模式 > 指定会话监听模式 > 本地监听模式。 plsql_plprofiler 中的数据共享方式分为 local 和 global 两种。其中，local 模式数据不共享，仅当前 session 可 见；global 模式数据共享，所有 session 可见。 • 插件名为 plsql_plprofiler • 插件版本 V4.2 插件 plsql_plprofiler 加载方式 69.2 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。因此只需要在客户端工具执行 create extension 命令即可。 -- 创建插件 create extension plsql_plprofiler; 注意: 在当前模式和 plsql_profiler 模式下均创建了一套分析接口，因此在任意模式下分析接口可通过模式限定调 用。 575 第 69 章 PLSQL_PLPROFILER 69.3 插件 plsql_plprofiler 的参数配置 plsql_plprofiler 定义了三个系统参数： • plsql_plprofiler.max_callgraphs 设置内存中存储堆栈关系的行数，默认值为 20000。 • plsql_plprofiler.max_functions 设置内存中可存储的对象个数，默认值为 2000。 • plsql_plprofiler.max_lines 设置内存中分析数据记录行数，默认值为 200000。 69.4 插件 plsql_plprofiler 使用方法 69.4.1 plsql_plprofiler 使用说明 支持 profiler 的对象： • 支持函数分析 • 支持存储过程分析 • 支持包分析 包中支持分析的对象：包中初始化块、包中函数、包中存储过程。包中对象的分析数据记录到包对应的 oid。 • 支持触发器分析 • 支持嵌套函数分析 • 支持匿名块分析 匿名块的分析数据记录到 oid 为 9999 的行。 • 支持 object type 分析 object type 中支持分析的对象：member 方法、construct 方法、static 方法。object type 中分析数据记录到各 个方法对应的 oid。 注意: 如果是重复执行同一个对象（以 oid 为标识），需要清理之前记录的数据。 **支持 profiler 的是数据信息分为三类：**PLSQL 对象执行信息、PLSQL 对象堆栈信息和 PLSQL 对象源码信 息。 plsql_plprofiler 获取到的执行信息如下： 576 第 69 章 PLSQL_PLPROFILER • 对象 oid plsql_plprofiler 对象的 oid，包中的所有对象共用包的 oid、匿名块的 oid 为 9999、object type 中的对象使用方 法本身的 oid。嵌套函数的 oid 使用祖先函数的 oid。 • 语句所在行 0 行表示该对象的整体数据。 如果 PL/SQL 源码在一行上，则该语句的任何执行相关数据都属于该行。 如果 PL/SQL 源码在多行上，则该语句的任何执行相关数据都属于该语句的第一行。 如果 PL/SQL 源码的一行出现多个语句时，则多条语句的任何执行相关数据都属于该行。 • 执行次数 记录某一行代码的执行次数。一行代码不一定是一条语句。 • 总共耗时 记录某一行代码的总耗时。如果是控制语句则会包括整个控制语句中包含的语句的时间。时间单位 us。 • 最长耗时 记录某一行代码耗时最长的时间。时间单位 us。 注意: 1. 当执行对象抛出异常未被捕获时，只会记录整个对象的执行时间，其他数据均为 0；当执行对象抛出异常被捕 获时，异常语句的数据为 0，其他语句数据正常记录。 2. 如果执行对象中有事务操作（commit/rollback），该对象记录的总耗时是事务操作前的总时间。 3. 当开启 set serverout on 时，每条 SQL 语句都会执行 dbms_output 包中函数。因此执行语句时， plsql_plprofiler 会记录调用 dbms_output 包的数据，如：调用数据 clean 函数后，首先清除执行数据，然后 会调用 dbms_ouput 包中函数。 plsql_plprofiler 获取到的堆栈信息如下： • 堆栈 plsql_plprofiler 对象的堆栈 • 调用次数 该对象被调用的总次数。 • 总耗时 该对象总花费时间。 • 调用对象耗时 该对象调用对象的耗时。 577 第 69 章 PLSQL_PLPROFILER • 自身耗时 该对象除去调用其他对象的耗时。 plsql_plprofiler 获取到的源码信息如下： • oid • 行号 • 源码 由于匿名块在数据库中没有做存储，所以无法获取匿名块的源码信息。 578 第 69 章 PLSQL_PLPROFILER 69.4.2 接口函数 接口函数 简介 pl_profiler_set_enabled_local 函数 启停当前 session 分析器 pl_profiler_set_enabled_pid 函数 启停指定 session 分析器 pl_profiler_get_enabled_local 函数 查看当前 session 分析器状态 pl_profiler_get_enabled_pid 函数 查看指定 session 分析器状态 pl_profiler_set_enabled_global 函数 启停数据库级分析器 pl_profiler_get_enabled_global 函数 查看全局监控是否启用的状态 pl_profiler_collect_data 函数 单次数据 flush pl_profiler_set_collect_interval 函数 指定时间间隔数据 flush pl_profiler_get_collect_interval 函数 查看定时迁移的状态 pl_profiler_reset_local 函数 本地数据 clean pl_profiler_reset_shared 函数 全局数据 clean pl_profiler_linestats_local 函数 查看本地的对象的执行信息 pl_profiler_linestats_shared 函数 查看全局的对象的执行信息 pl_profiler_func_oids_local 函数 查看本地已执行 plsql 对象 pl_profiler_func_oids_shared 函数 查看全局已执行 plsql 对象 pl_profiler_callgraph_local 函数 查看本地的堆栈关系 pl_profiler_callgraph_shared 函数 查看全局的堆栈关系 pl_profiler_get_stack 函数 OID 转对象名 pl_profiler_funcs_source 函数 查看指定对象源码信息 pl_profiler_version 函数 查看整型版本信息 pl_profiler_versionstr 函数 查看字符串版本信息 pl_profiler_lines_overflow 函数 查看行数是否过界 69.4.2.1 pl_profiler_set_enabled_local 函数 功能描述 579 第 69 章 PLSQL_PLPROFILER 开启或关闭当前会话分析器。开启分析器则会对 session 中执行的所有 plsql 对象进行分析，并将信息进行暂存。 语法格式 FUNCTION pl_profiler_set_enabled_local(enabled bool) RETURNS bool 参数说明： 输入为 true 则为启用分析器，输入为 false 则为关闭分析器。 输出说明 返回值有三种：true、false、null（空），如果输入和输出一致，表示程序执行成功；反之，程序执行失败。 69.4.2.2 pl_profiler_set_enabled_pid 函数 功能描述 开启或关闭指定会话分析器。开启分析器则会对 session 中执行的所有 plsql 对象进行分析，并将信息进行暂存。 语法格式 FUNCTION pl_profiler_set_enabled_pid(pid int4) RETURNS bool 参数说明： 需要监控进程的 PID，每次只有一个 session 可以通过本方式启停分析器。输入 PID 为有效 seesion 时，启动分 析器。PID 为无效 session 时，则关闭已启动的监听器。 输出说明 输入进程号非 0 则返回 true，输入进程号为 0 则返回为 false。 69.4.2.3 pl_profiler_get_enabled_local 函数 功能描述 查看当前会话分析器状态。 语法格式 FUNCTION pl_profiler_get_enabled_local() RETURNS bool 输出说明 返回值为 true 则监控状态为启用，返回值为 false 则监控为未启用。 580 第 69 章 PLSQL_PLPROFILER 69.4.2.4 pl_profiler_get_enabled_pid 函数 功能描述 查看指定会话级分析器状态。 语法格式 FUNCTION pl_profiler_get_enabled_pid() RETURNS bool 输出说明 返回值为 true 则监控状态为启用，返回值为 false 则监控为未启用。 69.4.2.5 pl_profiler_set_enabled_global 函数 功能描述 开启或关闭数据库级分析器。开启全局监控则会对所有会话执行的所有 plsql 对象进行分析，并将信息进行暂 存。 语法格式 FUNCTION pl_profiler_set_enabled_global(enabled bool) RETURNS bool 参数说明： 输入为 true 则为启用全局监控，输入为 false 则为关闭全局监控。 输出说明 返回值有三种：true、false、null（空）。如果输入和输出一致，表示程序执行成功；反之，程序执行失败。 69.4.2.6 pl_profiler_get_enabled_global 函数 功能描述 查看全局监控是否启用的状态。 语法格式 FUNCTION pl_profiler_get_enabled_global() RETURNS bool 输出说明 返回值为 true 则监控状态为启用，返回值为 false 则监控状态为未启用。 581 第 69 章 PLSQL_PLPROFILER 69.4.2.7 pl_profiler_collect_data 函数 功能描述 将本地数据迁移到全局数据中。数据迁移后，本地的分析数据会被清除（执行次数，最长时间，总共花费时 间）。 语法格式 FUNCTION pl_profiler_collect_data() RETURNS int4 输出说明 返回值：返回为-1 则表示没有将 plprofiler 插件加载到 shared_preload_libraries 中，返回为 0 则表示迁移成功 或没有数据需要迁移。 注意: 如果全局数据区内容已满，此时本地数据不会完全迁移到全局数据区中，同时系统报错内存已超出。 69.4.2.8 pl_profiler_set_collect_interval 函数 功能描述 设置时间（秒级单位）自动将本地数据迁移到全局数据中。数据迁移后，本地的分析数据会被清除（执行次数， 最长时间，总共花费时间）。 语法格式 FUNCTION pl_profiler_set_collect_interval(seconds int4) RETURNS bool 输入说明： 输入为秒级单位。 输出说明 当输入 seconds 为负数，返回值为 t, 无实际意义； 当输入 seconds 为 0 时，返回值为 f, 无实际意义； 当输入 seconds 为大于 0 时，返回值为 t，设置迁移时间有效。 注 意: 如 果 当 前 事 务 是：XACT_EVENT_COMMIT,、XACT_EVENT_PARALLEL_COMMIT、 XACT_EVENT_ABORT、XACT_EVENT_PARALLEL_ABORT 且 已 设 置 有 效 的 迁 移 时 间， 则 立 即 将 本 地 数据迁移到全局数据中。 582 第 69 章 PLSQL_PLPROFILER 69.4.2.9 pl_profiler_get_collect_interval 函数 功能描述 查看是否定时迁移的状态。 语法格式 FUNCTION pl_profiler_get_collect_interval() RETURNS bool 输出说明 返回值：根据是否定时的设置返回对应状态。如果之前用户设置的定时时间非 0 则该函数返回 t，如果之前设置 定时时间为 0 则返回 f。 69.4.2.10 pl_profiler_reset_local 函数 功能描述 清除本地存储的所有数据信息。 语法格式 FUNCTION pl_profiler_reset_local() RETURNS void 69.4.2.11 pl_profiler_reset_shared 函数 功能描述 清除全局存储的所有数据信息。 语法格式 FUNCTION pl_profiler_reset_shared() RETURNS void 69.4.2.12 pl_profiler_linestats_local 函数 功能描述 查看本地的对象的执行信息 语法格式 FUNCTION pl_profiler_linestats_local( OUT func_oid oid, OUT line_number int8, OUT exec_count int8, 583 第 69 章 PLSQL_PLPROFILER OUT total_time int8, OUT longest_time int8 ) RETURNS SETOF record AS 'MODULE_PATHNAME' LANGUAGE C ROWS 1000000; 输出说明 返回一个具有以下结构的数据集合： func_oid：类型为 oid，表示已经监控的对象 oid； line_number：类型为 int8，表示当前语句行号； exec_count：类型为 int8，表示执行次数； total_time：类型为 int8，表示当前语句执行总时长； longest_time：类型为 int8，表示当前语句执行的最长一次时长。 注意: line_number 会根据源码（系统表中存储源码）进行计算，line_number 为 0 的行表示了当前对象的执行次 数，总共执行时长，最长一次执行时间。 69.4.2.13 pl_profiler_linestats_shared 函数 功能描述 查看全局的对象的执行信息 语法格式 FUNCTION pl_profiler_linestats_shared( OUT func_oid oid, OUT line_number int8, OUT exec_count int8, OUT total_time int8, OUT longest_time int8 ) RETURNS SETOF record AS 'MODULE_PATHNAME' LANGUAGE C ROWS 1000000; 输出说明 返回一个具有以下结构的多行： 584 第 69 章 PLSQL_PLPROFILER func_oid：类型为 oid，表示已经监控的对象 oid； line_number：类型为 int8，表示当前语句行号； exec_count：类型为 int8，表示执行次数； total_time：类型为 int8，表示当前语句执行总时长； longest_time：类型为 int8，表示当前语句执行的最长一次时长。 注意: line_number 会根据源码（系统表中存储源码）进行计算，line_number 为 0 的行表示了当前对象的执行次 数，总共执行时长，最长一次执行时间。 69.4.2.14 pl_profiler_func_oids_local 函数 功能描述 查看本地已执行 plsql 对象。 语法格式 FUNCTION pl_profiler_func_oids_local() RETURNS oid[] 输出说明 返回值：返回 plsql 对象的 oid 数组。 69.4.2.15 pl_profiler_func_oids_shared 函数 功能描述 查看全局已执行 plsql 对象 语法格式 FUNCTION pl_profiler_func_oids_shared() RETURNS oid[] 输出说明 返回值：返回 plsql 对象的 oid 数组。 69.4.2.16 pl_profiler_callgraph_local 函数 功能描述 查看本地已监控的 plsql 对象及子程序调用信息。 语法格式 585 第 69 章 PLSQL_PLPROFILER FUNCTION pl_profiler_callgraph_local( OUT stack oid[], OUT call_count int8, OUT us_total int8, OUT us_children int8, OUT us_self int8 ) RETURNS SETOF record AS 'MODULE_PATHNAME' LANGUAGE C ROWS 1000000; 输出说明 返回一个具有以下结构的多行： stack：类型为 oid[]，表示已经监控的对象 oid 数组，能够表明监控对象的堆栈关系； call_count：类型为 int8，表示当前对象调用次数； us_total：类型为 int8，表示执行该对象总共花费时间； us_children：类型为 int8，表示执行该对象中的子程序总共花费时间； us_self：类型为 int8，表示执行该对象除子程序外，对象本身语句花费时间。 注意: 如果调用的 plsql 对象中没有调用子程序，则调用 pl_profiler_callgraph_local 函数只有一行信息；如果调用 的 plsql 对象中存在调用子程序，则调用 pl_profiler_callgraph_local 函数除了显示调用的 plsql 对象，还有显示子程 序的性能数据信息，并且子程序性能数据信息中的 stack 会显示堆栈关系，如 {16513,16515,16514}，其中 16513 为调 用的 plsql 对象，16515 为 16513 的子程序，16514 为 61515 的子程序。 69.4.2.17 pl_profiler_callgraph_shared 函数 功能描述 查看全局的 plsql 对象及子程序调用信息。 语法格式 FUNCTION pl_profiler_callgraph_shared( OUT stack oid[], OUT call_count int8, OUT us_total int8, OUT us_children int8, OUT us_self int8 ) RETURNS SETOF record 586 第 69 章 PLSQL_PLPROFILER AS 'MODULE_PATHNAME' LANGUAGE C ROWS 1000000; 输出说明 返回一个具有以下结构的多行： stack：类型为 oid[]，表示已经监控的对象 oid 数组，能够表明监控对象的堆栈关系； call_count：类型为 int8，表示当前对象调用次数； us_total：类型为 int8，表示执行该对象总共花费时间； us_children：类型为 int8，表示执行该对象中的子程序总共花费时间； us_self：类型为 int8，表示执行该对象除子程序外，对象本身语句花费时间。 注意: 如果调用的 plsql 对象中没有调用子程序，则调用 pl_profiler_callgraph_shared 函数只有一行信息；如果调 用的 plsql 对象中存在调用子程序，则调用 pl_profiler_callgraph_shared 函数除了显示调用的 plsql 对象，还有显示 子程序的性能数据信息，并且子程序性能数据信息中的 stack 会显示堆栈关系，如 {16513,16515,16514}，其中 16513 为调用的 plsql 对象，16515 为 16513 的子程序，16514 为 61515 的子程序。 69.4.2.18 pl_profiler_get_stack 函数 功能描述 将 OID 转成对象名称及当前模式名信息。 语法格式 FUNCTION pl_profiler_get_stack(stack oid[]) RETURNS text[] AS 'MODULE_PATHNAME' LANGUAGE C STRICT; 输入说明： stack 为一个 oid 的数组，通常为 pl_profiler_func_oids_shared 接口或 pl_profiler_func_oids_local 接口的返 回值。 输出说明 将传入的 oid 转化为模式 + 函数名称的 text 数组。 注意: 如果传入的 oid 对应的模式名或对象名称不存在，则 text 数组中会返回”.()” 的信 息。若传入 oid 数组存在堆栈关系，则可以转化为带有堆栈关系的 text 数组。 587 第 69 章 PLSQL_PLPROFILER 69.4.2.19 pl_profiler_funcs_source 函数 功能描述 查看指定对象源码信息。 语法格式 FUNCTION pl_profiler_funcs_source( IN func_oids oid[], OUT func_oid oid, OUT line_number int8, OUT source text ) RETURNS SETOF record AS 'MODULE_PATHNAME' LANGUAGE C ROWS 1000000 STRICT; 输入说明： func_oids：传入的一个对象 oid 数组。 输出说明 返回值：通过传入对象 oid 数组，输出以下结构的多行： func_oid：对象 oid； line_number：当前行号； source：当前行号对应源码。 注意: 系统会自动增加一行 line_number 为 0 的行，并且 suorce 为“-- Line 0”。如果不能查询到输入 oid 的源码， 则系统报错。 不能查询匿名块的源码。 69.4.2.20 pl_profiler_version 函数 功能描述 查看整型版本信息。 语法格式 FUNCTION pl_profiler_version() RETURNS integer 输出说明 588 第 69 章 PLSQL_PLPROFILER 返回值：输出当前的版本值。 69.4.2.21 pl_profiler_versionstr 函数 功能描述 查看字符串版本信息。 语法格式 FUNCTION pl_profiler_versionstr() RETURNS text 输出说明 返回值：输出当前版本的字符串信息。 69.4.2.22 pl_profiler_lines_overflow 函数 功能描述 查看存储对象具体信息结构的行数是否过界。 语法格式 FUNCTION pl_profiler_lines_overflow() RETURNS bool 输出说明 返回值：如果 profiler_linestats 结构内存过界，则返回 t, 否则返回 f。 69.4.3 典型用例 Profiler 每次运行的的过程应该包括以下步骤： 1. 启动分析器 2. 运行应用程序 3. 关闭分析器 4. 数据 flush 5. 分析数据 用户在使用 profiler 前，需要创建 profiler 扩展。 profiler 收集数据，通过调用 pl_profiler_set_enabled_local 函数来控制分析器的启动或者停止。分析器收集到 的数据存储在内存中，如果用户断开连接，分析器将不会自动存储数据，需要显示调用 pl_profiler_collect_data 函 数将数据刷到共享内存。需要注意的是，目前 profiler 数据不会落盘存储，所以一旦重启数据库，分析数据将会丢 失。 589 第 69 章 PLSQL_PLPROFILER --创建扩展 create extension plsql_plprofiler; --创建对象 create table t1(i int); \set SQLTERM / create or replace procedure p1() as begin raise notice 'this is procedure p1'; for i in 1..1000 loop insert into t1 values(99999); end loop; if 1000 < 100 then null; else null; end if; end; / create or replace procedure p2() as begin raise notice 'this is procedure p2'; p1(); end; / create or replace procedure p3() as begin raise notice 'this is procedure p3'; p2(); if 1 < 100 then raise notice '1 < 100'; end if; end; / \set SQLTERM ; --清理本地数据 select pl_profiler_reset_local(); --清理全局数据 select pl_profiler_reset_shared(); --启动分析器 select pl_profiler_set_enabled_global(true); --运行应用程序 call p3(); --关闭分析器 select pl_profiler_set_enabled_global(false); --数据 flush select pl_profiler_collect_data(); 590 第 69 章 PLSQL_PLPROFILER --分析数据 ----查看已记录的对象（可选） select * from pl_profiler_func_oids_shared(); ----oid 转对象名（可选） select * from pl_profiler_get_stack(pl_profiler_func_oids_shared()); \set SQLTERM ; --清理本地数据 select pl_profiler_reset_local(); pl_profiler_reset_local ------------------------(1 row) --清理全局数据 select pl_profiler_reset_shared(); pl_profiler_reset_shared -------------------------(1 row) --启动分析器 select pl_profiler_set_enabled_global(true); pl_profiler_set_enabled_global -------------------------------t (1 row) --运行应用程序 call p3(); NOTICE: this is procedure p3 NOTICE: this is procedure p2 NOTICE: this is procedure p1 NOTICE: 1 < 100 CALL --关闭分析器 select pl_profiler_set_enabled_global(false); pl_profiler_set_enabled_global -------------------------------f (1 row) --数据 flush select pl_profiler_collect_data(); pl_profiler_collect_data 591 第 69 章 PLSQL_PLPROFILER -------------------------0 (1 row) --分析数据 ----查看已记录的对象（可选） select * from pl_profiler_func_oids_shared(); pl_profiler_func_oids_shared -----------------------------{16793,16792,16794} (1 row) ----oid 转对象名（可选） select * from pl_profiler_get_stack(pl_profiler_func_oids_shared()); pl_profiler_get_stack --------------------------------------------------------------------------{"public.p2() oid=16793","public.p1() oid=16792","public.p3() oid=16794"} (1 row) ----查看数据（可选） select func_oid, func_oid::regproc as funcname,line_number, source from pl_profiler_funcs_source(pl_ profiler_func_oids_shared()); ----查看数据（可选） select func_oid, func_oid::regproc as funcname,line_number, source from pl_profiler_funcs_source(pl_ profiler_func_oids_shared()); func_oid | funcname | line_number | source ----------+----------+-------------+----------------------------------------------------16793 | p2 | 0 | -- Line 0 16793 | p2 | 1 | 16793 | p2 | 2 | 16793 | p2 | 3 | raise notice 'this is procedure p2'; 16793 | p2 | 4 | p1(); 16793 | p2 | 5 | 16792 | p1 | 0 | -- Line 0 16792 | p1 | 1 | 16792 | p1 | 2 | 16792 | p1 | 3 | raise notice 'this is procedure p1'; 16792 | p1 | 4 | for i in 1..1000 loop 16792 | p1 | 5 | insert 16792 | p1 | 6 | into 16792 | p1 | 7 | t1 16792 | p1 | 8 | values(99999); 16792 | p1 | 9 | begin end begin end loop; 592 第 69 章 PLSQL_PLPROFILER 16792 | p1 | 10 | if 1000 < 100 then null; else null; end if; 16792 | p1 | 11 | 16794 | p3 | 0 | -- Line 0 16794 | p3 | 1 | 16794 | p3 | 2 | 16794 | p3 | 3 | raise notice 'this is procedure p3'; end begin 16794 | p3 | 4 | p2(); 16794 | p3 | 5 | if 1 < 100 then 16794 | p3 | 6 | 16794 | p3 | 7 | 16794 | p3 | 8 | raise notice '1 < 100'; end if; end (27 rows) ----查看对象调用关系 select * from pl_profiler_callgraph_shared(); stack | call_count | us_total | us_children | us_self ---------------------+------------+----------+-------------+--------- {16794,16793} | 1 | 8175 | 7990 | 185 {16794,16793,16792} | 1 | 7990 | 0 | 7990 {16794} | 1 | 8473 | 8175 | 298 (3 rows) -----源码和分析数据对应该系 SELECT L.func_oid::regproc as funcname, L.func_oid as func_oid, L.line_number, sum(L.exec_count)::bigint AS exec_count, sum(L.total_time)::bigint AS total_time, max(L.longest_time)::bigint AS longest_time, S.source FROM pl_profiler_linestats_shared() L JOIN pl_profiler_funcs_source(pl_profiler_func_oids_shared) S ON S.func_oid = L.func_oid AND S.line_number = L.line_number GROUP BY L.func_oid, L.line_number, S.source ORDER BY L.func_oid, L.line_number; funcname | func_oid | line_number | exec_count | total_time | longest_time | source ----------+----------+-------------+------------+------------+--------------+---------------------------------------------------p1 | 16792 | 0 | 1 | 7990 | 7990 | -- Line 0 p1 | 16792 | 1 | 0 | 0 | 0 | p1 | 16792 | 2 | 1 | 7989 | 7989 | p1 | 16792 | 3 | 1 | 14 | 14 | begin raise notice 'this is procedure p1'; 593 第 69 章 PLSQL_PLPROFILER p1 | 16792 | 4 | 1 | 7830 | 7830 | for i in 1..1000 loop p1 | 16792 | 5 | 1000 | 7181 | 314 | insert p1 | 16792 | 6 | 0 | 0 | 0 | into p1 | 16792 | 7 | 0 | 0 | 0 | t1 p1 | 16792 | 8 | 0 | 0 | 0 | values(99999); p1 | 16792 | 9 | 0 | 0 | 0 | end loop; p1 | 16792 | 10 | 2 | 0 | 0 | if 1000 < 100 then 0 | null; else null; end if; p1 | 16792 | 11 | 0 | 0 | p2 | 16793 | 0 | 1 | 8175 | p2 | 16793 | 1 | 0 | 0 | 0 | p2 | 16793 | 2 | 1 | 8174 | 8174 | p2 | 16793 | 3 | 1 | 22 | 22 | end 8175 | -- Line 0 begin raise notice 'this is procedure p2'; p2 | 16793 | 4 | 1 | 8151 | 8151 | p2 | 16793 | 5 | 0 | 0 | 0 | p3 | 16794 | 0 | 1 | 8473 | p3 | 16794 | 1 | 0 | 0 | 0 | p3 | 16794 | 2 | 1 | 8471 | 8471 | p3 | 16794 | 3 | 1 | 50 | 50 | p1(); end 8473 | -- Line 0 begin raise notice 'this is procedure p3'; p3 | 16794 | 4 | 1 | 8365 | 8365 | p3 | 16794 | 5 | 1 | 52 | 52 | p3 | 16794 | 6 | 1 | 13 | 13 | p3 | 16794 | 7 | 0 | 0 | 0 | p3 | 16794 | 8 | 0 | 0 | 0 | p2(); if 1 < 100 then raise notice '1 < 100'; end if; end (27 rows) 69.5 插件 plsql_plprofiler 卸载方法 卸载 plsql_plprofiler 插件接口，只需要执行以下命令： -- 删除插件 drop extension plsql_plprofiler; 69.6 插件 plsql_plprofiler 升级方法 若该插件有升级版本则通过 alter extension 来升级插件。 示例，由 4.1 升级到 4.2： 594 第 69 章 PLSQL_PLPROFILER ALTER EXTENSION plsql_plprofiler UPDATE TO '4.2'; 595 第 70 章 RESTRICTED_DBA 70章 restricted_dba 第 70.1 插件 restricted_dba 简介 restricted_dba 是一个 KingbaseES 的扩展，可以实现对超级用户权限进行限制。 受限 DBA 是对数据库超级管理员用户权限进行限制的插件，开启此插件后，管理员的权限应当与普通用户一 致，即限制了管理员用户的操作权限，包括系统级权限级及对象级权限。 • 插件名为 restricted_dba • 插件版本 V1.0 70.2 插件 restricted_dba 加载方法 在使用 restricted_dba 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 shared_preload_libraries = 'restricted_dba， sepapower' # (change requires restart) 注意: 它依赖于《KingbaseES 数据库安全指南》分立插件 70.3 插件 restricted_dba 的参数配置 restricted_dba.restricted_enable 此参数标识是否开启受限 DBA 功能，默认是 false 即不开启受限 DBA。此参 数应由安全员开启。 596 第 70 章 RESTRICTED_DBA 70.3.1 示例 create database res_test_db; create role res_test_super with superuser createrole login; \c res_test_db res_test_super alter system set restricted_dba.restricted_enable = true; ERROR: permission denied \c res_test_db sso alter system set restricted_dba.restricted_enable = true; call sys_reload_conf(); sys_reload_conf ---------------t (1 row) \c res_test_db res_test_super show restricted_dba.restricted_enable; restricted_dba.restricted_enable ---------------------------------on (1 row) create role res_test with login; \c res_test_db res_test create table res_test_table (id int); create view res_test_view (id) as select * from res_test_table; \c res_test_db res_test_super alter role res_test; ERROR: Restricted DBA can not alter user select * from res_test_table; ERROR: permission denied for table res_test_table select * from res_test_view; ERROR: 70.4 permission denied for view res_test_view 插件 restricted_dba 使用方法 具体参考《KingbaseES 数据库安全指南》3.1.2.3 受限 DBA 章节。 70.5 插件 restricted_dba 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 597 第 70 章 RESTRICTED_DBA shared_preload_libraries = '' 70.6 插件 restricted_dba 升级方法 restricted_dba 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 598 第 71 章 ROLEDISABLE 71章 roledisable 第 71.1 插件 roledisable 简介 roledisable 是 KingbaseES 的扩展插件。主要用在管理数据库的角色是否生效。可以在不删除角色的前提下，使 本地库内使角色被禁用或者使禁用的的角色启用。 • 插件名为 roledisable • 插件版本 V1.0 71.2 插件 roledisable 加载方式 修改 kingbase.conf 文件中 shared_preload_libraries 参数，重启数据库时自动加载。 shared_preload_libraries = 'roledisable' \c - system create extension roledisable; 71.2.1 查看角色状态 SYSTEM 可以通过 roledisable.sys_role_status 视图来查看系统所有角色在当前库内的启用/禁用状态。 SELECT * FROM roledisable.sys_role_status; 71.2.2 字段说明 oid 角色在数据库内的 ID。 rolename 角色在数据库内的名称。 status 角色的状态 Enable 表示角色被启用，Disable 表示角色被禁用。 599 第 71 章 71.2.3 ROLEDISABLE 启用角色 将角色设置为启用状态。 ALTER ROLE rolename ENABLE; 执行权限: 需要以系统管理员权限执行，以非系统管理员执行时报告错误。 角色要求：被启用的角色需事先存在。 新建角色：新创建的角色默认为启用状态。 71.2.4 禁用角色 将角色设置为禁用状态。 ALTER ROLE rolename DISABLE; 执行权限: 需要以系统管理员权限执行，以非系统管理员执行时报告错误。 角色要求：被禁用的角色需事先存在。 系统内置角色；系统内置角色无法被禁用。如初始化用户、sao、sso 等无法被禁用。 71.2.5 被禁用角色的表现 • 当角色被禁用后，断开权限继承关系，不能从该角色直接和间接继承权限，间接使用被禁用角色的权限时应该 报角色被禁用或权限错误。 • 以 SET ROLE 切换到被禁用的角色时报告错误。 • 当会话使用的系统管理员角色被禁用时，因系统管理员绕过权限检查因此不会对其造成权限的影响。 • 当前会话使用的非系统管理员角色被禁用时，被禁用角色对权限继承关系产生影响因缓存机制可能不会立即生 效，当切换角色权限检查或重新登录后生效。 • 角色在使用期间被禁用时，以被禁用角色（非系统管理员）执行需检查权限的操作时，报当前角色被禁用错 误。 • 角色被禁用状态下，可以修改角色权限和角色关系。如使用 GRANT 和 REVOKE 对其操作，使用 ALTER ROLE 对其操作。 71.3 插件 roledisable 的参数配置 无需配置任何参数。 600 第 71 章 71.4 ROLEDISABLE 插件 roledisable 的使用方法 加载 roledisable 插件后，程序可以管理数据库的角色是否生效。可以在不删除角色的前提下，使本地库内使角色 被禁用或者使禁用的的角色启用。 示例： -- 创建插件 \c test system create extension roledisable; CREATE EXTENSION 71.5 插件 roledisable 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = '' 71.6 插件 roledisable 升级方法 roledisable 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 601 第 72 章 RUM 72章 rum 第 72.1 插件 rum 简介 具体参考：RUM 索引类型章节。 • 插件名为 rum • 插件版本 V1.3 72.2 插件 rum 加载方式 CREATE EXTENSION rum; 72.3 插件 rum 的参数配置 无需配置任何参数 72.4 插件 rum 的使用方法 具体参考：RUM 索引类型章节。 72.5 插件 rum 卸载方法 DROP EXTENSION rum; 602 第 72 章 RUM 72.6 插件 rum 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION rum UPDATE TO '1.1'; 603 第 73 章 SECURITY_UTILS 73章 security_utils 第 73.1 插件 security_utils 简介 security_utils 是 KingbaseES 的一个扩展插件，主要用于支持一些安全方面的功能，目前支持的功能有日志密码 脱敏，弱口令扫描。 • 插件名为 security_utils • 插件版本 V1.0 73.2 插件 security_utils 加载方式 在使用 security_utils 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'security_utils' 73.3 插件 security_utils 的参数配置 security_utils.password_masking_enable 启动日志密码脱敏功能，取值范围为 on 或者 off，缺省值为 off。 show security_utils.password_masking_enable; security_utils.password_masking_enable ---------------------------------------off (1 row) \c - system 604 第 73 章 SECURITY_UTILS alter system set security_utils.password_masking_enable = on; select sys_reload_conf(); show security_utils.password_masking_enable; security_utils.password_masking_enable ---------------------------------------on (1 row) security_utils.weak_pwd_check_enable 弱口令检查功能，取值范围为 on 或者 off，默认为关闭状态。 73.4 插件 security_utils 使用方法 73.4.1 口令脱敏 KingbaseES 加载 security_utils 插件，并修改了参数后，当开启 DDL 日志时，日志中涉及密码的 SQL 语句可 以进行脱敏处理。 示例 ---开启密码脱敏 \c - system create extension security_utils; alter system set security_utils.password_masking_enable=on; select sys_reload_conf(); ---设置日志级别 alter system set log_statement='ddl'; select sys_reload_conf(); ---执行 user 的包含密码的 ddl 语句 drop user testpwdtmu1; create user testpwdtmu1 with password '12345678ab'; alter user testpwdtmu1 with password '12345678abc'; drop user testpwdtmu1; ---查看 sys_log 下的日志文件，上述语句 password 脱敏，以 * 显示 ERROR: role "testpwdtmu1" does not exist STATEMENT: drop user testpwdtmu1; LOG: statement: create user testpwdtmu1 with password '**********'; LOG: statement: alter user testpwdtmu1 with password '***********'; LOG: statement: drop user testpwdtmu1; ---清空环境 605 第 73 章 SECURITY_UTILS alter system set security_utils.password_masking_enable=off; select sys_reload_conf(); drop extension security_utils; 73.4.2 弱口令扫描 弱口令字典配置语法 --设置弱口令字典 set weak password [if not exists] 'wpwd1'[, 'wpwd2'...]; --删除弱口令字典 remove weak password [if exists] 'wpwd1'[, 'wpwd2'...]; 说明 • 可以同时创建或删除多个弱口令，使用方法见上配置语法。 • 弱口令字符串类型为 text，不限制长度，且配置语法不限制弱口令个数。 • 当存在 if not exists 或 if exists，将忽略已存在或不存在的弱口令，避免报错，否则会报错提示。 • 不允许输入的弱口令为 null，例如 set weak password null。 • 输入的弱口令为空字符串时，例如 set weak password ”，处理方法与第三点相同。 • 弱口令扫描支持三种口令加密方式，包括 sha256、md5、sm3 。 提示: 1. 当弱口令扫描与口令复杂度功能同时开启时，且检查的口令既属于弱口令，又不符合口令复杂度要求，报错 提示的内容与两个功能的加载顺序相关，报错提示会显示写在 shared_preload_libraries 中靠前的插件的提示内容。 2. 当数据库中已创建了弱口令扫描的扩展 security_utils ，请使用数据库管理员进行备份恢复以避免报错导致备 份恢复失败。 示例 开启弱口令扫描功能： shared_preload_libraries = 'security_utils' \c - system create extension security_utils; show security_utils.weak_pwd_check_enable; security_utils.weak_pwd_check_enable -----------------------------------off 606 第 73 章 SECURITY_UTILS (1 行记录) alter system set security_utils.weak_pwd_check_enable = on; select sys_reload_conf(); sys_reload_conf ----------------t (1 行记录) show security_utils.weak_pwd_check_enable; security_utils.weak_pwd_check_enable -----------------------------------on (1 行记录) 在功能开启后，数据库管理员 system 登录数据库后，可以进行弱口令字典的配置： \c - system set weak password '123qwe';--成功 set weak password '123qwe','1234asdf';--失败，重复弱口令报错 错误: weak passwd dic "123qwe" already exists set weak password if not exists '123qwe','1234asdf';--成功，忽略已存在的弱口令 --查看弱口令配置 select * from security_utils.weak_pwd_dic; weak_passwd | created_time -------------+------------------------------123qwe | 2022-08-01 15:11:21.102412+08 1234asdf | 2022-08-01 15:12:52.640116+08 (2 rows) 创建新用户 u1，使用弱口令作为口令： \c - system create user u1 with password '123qwe';--失败，口令不符合弱口令检查 错误: password is too weak! create user u1 with password '123qwer';--成功 alter user u1 with password '123qwe'; 错误: password is too weak!--失败，口令不符合弱口令检查 数据库管理员进行弱口令扫描： \c - system --将 u1 用户的口令设置为弱口令字典 set weak password '123qwe'; 607 第 73 章 SECURITY_UTILS --进行弱口令扫描 select * from security_utils.weak_passwd_scan_result; username | weak_passwd ----------+------------u1 | 123qwer (1 row) 数据库管理员删除弱口令配置： \c - system --查看现有弱口令配置 select * from security_utils.weak_pwd_dic; weak_passwd | created_time -------------+------------------------------123qwe | 2022-08-01 15:11:21.102412+08 1234asdf | 2022-08-01 15:12:52.640116+08 123qwer | 2022-08-01 15:22:12.404342+08 (3 rows) --删除弱口令配置 remove weak password '123qwe';--成功 remove weak password '123qwe','1234asdf','123qwer';--失败，不存在的弱口令报错 错误: weak passwd dic "123qwe" does not exists remove weak password if exists '123qwe','1234asdf','123qwer';--成功，忽略不存在的弱口令 --查看弱口令字典 select * from security_utils.weak_pwd_dic; weak_passwd | created_time -------------+-------------(0 rows) 73.5 相关函数 73.5.1 check_guc_in_cluster() 功能 在集群环境中检查主备机之间安全相关 guc 参数是否相等。 返回值 返回 bool 型。 608 第 73 章 SECURITY_UTILS 返回‘t’：表示 guc 一致，或者没有备机服务器； 返回‘f’：表示主备机 guc 不一致、不是在 esrep 数据库中、不是主机服务器，或者无 repmgr.nodes 表。 73.5.2 set_guc_in_cluster() 功能 在集群环境中将主机安全相关 guc 参数，设置到各个备机服务器中。 返回值 返回 bool 型。 返回‘t’：表示 guc 设置成功； 返回‘f’：表示不是在 esrep 数据库中、不是主机服务器，或者无 repmgr.nodes 表。 注意 1）如果无法检查主备机之间的 guc 参数，则会在日志中记录 command failed:xxxx。不影响程序查看比较后面的 guc 参数。 2）建议主备机配置文件 shared_preload_libraries 相同。 73.5.2.1 定时任务 集群在部署阶段设置 sync_security_guc 参数： 如果设置为 yes，则会在部署集群的时候创建 kdb_schedule、security_utils 这两个插件，并配置相关 guc 参数。 集群环境通过 kdb_schedule 定时调用 security_utils.set_guc_in_cluster 函数，可实现集群数据库服务器自动同步主 备机安全 guc 参数。 如果设置为 no，则不执行任何操作。默认值为 no。 73.6 插件 security_utils 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 609 第 73 章 SECURITY_UTILS 73.7 插件 security_utils 升级方法 security_utils 扩展插件随着 KingbaseES 安装包一并升级。但请注意，V008R006C006B0021 版本之前的版本， 当使用 sys_upgrade 升级后无法正常使用弱口令功能时，请删除扩展并重新创建。 610 第 74 章 SEG 74章 seg 第 74.1 插件 seg 简介 seg 是 KingbaseES 的一个扩展插件，这个插件可以为程序提供 seg 数据类型的使用，是为了表示线段或者浮点 区间而实现的一种数据类型。 seg 可以表示区间端点中的不确定性，这使得它对表达实验室测量特别有用。 • 插件名为 seg • 插件版本 V1.3 74.2 插件 seg 加载方式 KingbaseES 数据库默认将它添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 shared_preload_libraries = 'seg' 74.3 插件 seg 的参数配置 无需配置任何参数 74.4 插件 seg 的使用方法 加载 seg 插件后，程序内可以使用 seg 数据类型。 示例： 611 第 74 章 SEG -- 创建插件 \c test system create extension seg; CREATE EXTENSION -- 使用示例 SELECT '1.0e+7'::seg AS seg; seg --------1.0e+07 (1 行记录) SELECT '0.000000120'::seg AS seg; seg ---------1.20e-07 (1 行记录) SELECT '0 .. 1'::seg AS seg; seg -------0 .. 1 (1 行记录) SELECT '24 .. 33.20'::seg != '24 .. 33.21'::seg AS bool; bool -----t (1 行记录) 74.5 插件 seg 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = '' 612 第 74 章 SEG 74.6 插件 seg 升级方法 seg 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 613 第 75 章 SEND_MAILS 75章 send_mails 第 75.1 插件 send_mails 简介 send_mails 是 KingbaseES 的一个扩展插件，主要用于通过 SMTP 协议，向指定收件人发送邮件，邮件内容自 定义。 • 插件名为 send_mails • 插件版本 V1.0 75.2 插件 send_mails 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例如下： shared_preload_libraries = 'send_mails' 75.3 插件 send_mails 的参数配置 send_mails.mail_server 收件人邮件服务器的 IP 地址。参数为字符串类型，默认为空，不允许配置为空。 send_mails.mail_port 收件人邮件服务器的端口号。参数为 int 类型，参数范围是 [0,65535]，默认为 0，不允许配置为 0。 send_mails.mail_login 发件人登录的邮箱地址。参数为字符串类型，默认为空，不允许配置为空。 614 第 75 章 SEND_MAILS send_mails.mail_password 发件人的邮箱密码。参数为字符串类型，默认为空，不允许配置为空。 send_mails.mail_from 发件人的邮箱。参数为字符串类型，默认为空，不允许配置为空。 send_mails.mail_to 收件人的邮箱。参数为字符串类型，默认为空，不允许配置为空。 75.4 插件 send_mails 使用方法 KingbaseES 加载 send_mails 插件，打开审计入侵检测邮件告警开关 sysaudit.ids_mail_enable，配置上述邮件 发送 send_mails 扩展的参数后，实现邮件告警功能。 75.5 插件 send_mails 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例如下： shared_preload_libraries = '' 75.6 插件 send_mails 升级方法 send_mails 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 615 第 76 章 SEPAPOWER 76章 sepapower 第 76.1 插件 sepapower 简介 sepapower 是 KingbaseES 的一个扩展插件，主要用于支持三权分立功能。三权分立插件默认加载。 具体的三权分立功能介绍，参考《KingbaseES 数据库安全指南》3.1.2.2 三权分立章节。 • 插件名为 sepapower • 插件版本 V1.0 76.2 插件 sepapower 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'sepapower' 76.3 插件 sepapower 的参数配置 sepapower.separate_power_grant 是否由 sso 用户控制使用 DCL 语句，取值范围为 true 或者 false ，缺省值为 false。 \c - system show sepapower.separate_power_grant; sepapower.separate_power_grant -------------------------------off (1 row) 616 第 76 章 SEPAPOWER alter system set sepapower.separate_power_grant = on; select sys_reload_conf(); show sepapower.separate_power_grant; sepapower.separate_power_grant -------------------------------on (1 row) sepapower.check_noprivileges_grant 是否对无授权权限操作进行报错处理，取值范围为 true 或者 false ，缺省值 为 false。 show sepapower.check_noprivileges_grant; sepapower.check_noprivileges_grant -----------------------------------off (1 row) alter system set sepapower.check_noprivileges_grant = on; select sys_reload_conf(); show sepapower.check_noprivileges_grant; sepapower.check_noprivileges_grant -----------------------------------on (1 row) 76.4 插件 sepapower 使用方法 具体参考《KingbaseES 数据库安全指南》3.1.2.2 三权分立章节。 76.5 插件 sepapower 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 617 第 76 章 76.6 SEPAPOWER 插件 sepapower 升级方法 sepapower 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 618 第 77 章 SRC_RESTRICT 77章 src_restrict 第 77.1 插件 src_restrict 简介 src_restrict 是 KingbaseES 的一个扩展插件，主要用于支持来源限制功能，该功能通过 hba 的黑白名单来实现。 插件 src_restrict 默认加载。 • 插件名为 src_restrict • 插件版本 V1.0 77.2 插件 src_restrict 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'src_restrict' 77.3 插件 src_restrict 的参数配置 src_restrict.enable 是否允许使用黑白名单功能，取值范围为 true 或者 false ，缺省值为 true。 \c - sso show src_restrict.enable; src_restrict.enable --------------------on (1 row) 619 第 77 章 SRC_RESTRICT alter system set src_restrict.enable = off; select sys_reload_conf(); show src_restrict.enable; src_restrict.enable --------------------off (1 row) 77.4 插件 src_restrict 使用方法 77.4.1 系统函数 src_restrict.add_rules src_restrict.add_rules( filter_type int, rule_user text, rule_ip text, outrule_ip text, limited_info text) 功能说明 添加来源限制的规则，可通过参数选择配置白名单或黑名单。 参数说明 filter_type 限制规则的类型，0 为白名单，1 为黑名单。 rule_user 限制的用户名，多个用户时需使用逗号分隔，null 表示限制所有用户。当用户名中存在特殊字符时，请将 该用户名使用双引号括起来，避免用户名识别失败。 用户名参数最大长度 255。 rule_ip 限制的 IP，多个 IP 之间需使用逗号分隔，null 表示限制所有 IP。 允许使用 * 号进行 IP 网段匹配，但网段后不允许出现具体 IP，例如 192.168.*.123。 outrule_ip 不受限制的 IP，与 rule_ip 相同。 不受限制仅表示该参数与 rule_ip 的类型相反，例如 filter_type 为 0，则 rule_ip 为白名单，outrule_ip 为黑名单，不影响黑白名单优先级。 620 第 77 章 SRC_RESTRICT limited_info 限制规则，内容中包含 IP 段，mac 地址，时间段，分别使用关键字 ip_range、mac、time_range 进行标 识。 关 键 字 使 用 “=” 号 连 接 具 体 的 规 则 内 容， 同 一 关 键 字 内 的 内 容， 如 果 想 输 入 多 条， 用 “/” 号 连 接， 不 同 关 键 字 之 间 用 “;” 号 连 接。 填 写 格 式 为 “ip_range=XXXXXX~XXXXXX/ XXXXXX~XXXXXX;mac=XXXXX/ XXXXX;time_range=XXXXXX~XXXXXX/ XXXXXX~XXXXXX”。其中三个字段可以选择填写，也可以置空。 返回值说明 无返回值 77.4.2 系统函数 src_restrict.remove_rules src_restrict.remove_rules( filter_type int, rule_user text, rule_ip text limited_info text) 功能说明 删除来源限制的规则。 参数说明 filter_type 规则的类型，0 为白名单，1 为黑名单。 rule_user 规则的用户名，多个用户时需使用逗号分隔，null 等于 all。当用户名中存在特殊字符时，请将该用户名 使用双引号括起来，避免用户名识别失败。 用户名参数最大长度 255。 rule_ip 规则的 IP，只允许删除一个 IP，不支持删除多个规则，null 等于 0.0.0.0/0。 允许使用 * 号进行 IP 网段匹配，但网段后不允许出现具体 IP，例如 192.168.*.123。 limited_info 限制规则，内容中包含 IP 段，mac 地址，时间段，分别使用关键字 ip_range、mac、time_range 进行标 识。 关 键 字 使 用 “=” 号 连 接 具 体 的 规 则 内 容， 同 一 关 键 字 内 的 内 容， 如 果 想 输 入 多 条， 用 “/” 号 连 接， 不 同 关 键 字 之 间 用 “;” 号 连 接。 填 写 格 式 为 “ip_range=XXXXXX~XXXXXX/ 621 第 77 章 SRC_RESTRICT XXXXXX~XXXXXX;mac=XXXXX/ XXXXX;time_range=XXXXXX~XXXXXX/ XXXXXX~XXXXXX”。其中三个字段可以选择填写，也可以置空。 返回值说明 无返回值 提示: 删除函数中，要删除的规则中类型，用户名（包括用户个数），规则 IP 都要与规则一一对应，否则将无法删 除。 77.4.3 系统视图 src_restrict.show_rules 所有用户都可以通过该视图查看当前的限制规则。 select * from src_restrict.show_rules; 参数说明 filter_type 规则的类型，allow 为白名单，reject 为黑名单。 rule_user 规则的用户名。 rule_ip 规则的 IP。 netmask 规则 IP 对应的子网掩码。 login_limited_info 登录限制信息（包括 IP 段，mac 地址，日期时间段）。 77.4.4 示例 \c - sso --添加对用 u1 户添加黑名单规则 select src_restrict.add_rules(1,'u1','10.12.1.*','','ip_range=10.12.1.10~10.12.1.29/10.12.1.30~10.12.1.40; mac=d8:bb:c1:c3:77:23/d8:bb:c1:c3:77:25;time_range=20200101-12:01:07~20210910-03:04:05/20220101-12:01:07~ 20260910-03:04:05'); 622 第 77 章 SRC_RESTRICT --查看当前黑白名单 select * from src_restrict.show_rules; --删除刚添加的规则 select src_restrict.remove_rules(1,'u1','10.12.1.*','ip_range=10.12.1.10~10.12.1.29/10.12.1.30~10.12.1.40; mac=d8:bb:c1:c3:77:23/d8:bb:c1:c3:77:25;time_range=20200101-12:01:07~20210910-03:04:05/20220101-12:01:07~ 20260910-03:04:05'); 77.5 插件 src_restrict 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 77.6 插件 src_restrict 升级方法 src_restrict 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 623 第 78 章 SSLINFO 78章 sslinfo 第 78.1 插件 sslinfo 简介 sslinfo 是 KingbaseES 的一个扩展插件，sslinfo 插件提供当前客户端提供的 SSL 证书的有关信息。如果当前连接 不使用 SSL，这个模块就没有用处（大部分函数将返回 NULL）。 本模块提供的一些信息，也可以使用内置系统视图 sys_stat_ssl 来获得。 • 插件名为 sslinfo • 插件版本 V1.2 78.2 插件 sslinfo 加载方式 KingbaseES 数据库可将它添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加载。 shared_preload_libraries = 'sslinfo' 78.3 插件 sslinfo 的参数配置 无需配置任何参数 78.4 插件 sslinfo 的使用方法 加载 sslinfo 插件后，程序可以提供当前客户端提供的 SSL 证书的有关信息。 示例： 624 第 78 章 SSLINFO -- 创建插件 \c test system create extension sslinfo; CREATE EXTENSION 78.5 插件 sslinfo 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = '' 78.6 插件 sslinfo 升级方法 sslinfo 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 625 第 79 章 SSO_UPDATE_USER 79章 sso_update_user 第 79.1 插件 sso_update_user 简介 sso_update_user 是 KingbaseES 的一个扩展插件，可以满足某些特殊场景的三权分立需求，对管理员和安全员 的权限做出进一步的划分。 • 插件名为 sso_update_user • 插件版本 V1.0 79.2 插件 sso_update_user 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例： shared_preload_libraries = 'sso_update_user' 79.3 插件 sso_update_user 的参数配置 “sso_update_user.sso_update_user_enable“默认为关闭状态。 切换用户为安全管理员 sso，打开插件开关。 show sso_update_user.sso_update_user_enable; sso_update_user.sso_update_user_enable -------------------------------------off (1 行记录) 626 第 79 章 SSO_UPDATE_USER \c - sso alter system set sso_update_user.sso_update_user_enable = true; ALTER SYSTEM select sys_reload_conf(); sys_reload_conf ----------------t (1 行记录) show sso_update_user.sso_update_user_enable; sso_update_user.sso_update_user_enable -------------------------------------on (1 行记录) 79.4 插件 sso_update_user 使用方法 具体参考《KingbaseES 数据库安全指南》3.1.2.2.5 插件增强支持章节。 79.5 插件 sso_update_user 卸载方式 修改 kingbase.conf 文件中“shared_preload_libraries“参数后重启数据库。 shared_preload_libraries = '' 79.6 插件 sso_update_user 升级方法 sso_update_user 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 627 第 80 章 SYS_ANON 80章 sys_anon 第 80.1 插件 sys_anon 简介 sys_anon 是 KingbaseES 的一个扩展插件，主要用于支持数据脱敏功能和应用级敏感数据保护。 数据脱敏，指对某些敏感信息通过脱敏规则进行数据的变形，实现敏感隐私数据的可靠保护。具体参考《KingbaseES 数据库安全指南》第 10 章数据脱敏。 • 插件名为 sys_anon • 插件版本 V1.0 80.2 插件 sys_anon 加载方式 在使用 sys_anon 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'sys_anon' 80.3 插件 sys_anon 的参数配置 anon.enable 启动数据脱敏功能的开关，取值范围为 true 或者 false ，缺省值为 false。 show anon.enable; anon.enable ------------off (1 row) 628 第 80 章 SYS_ANON alter system set anon.enable = on; select sys_reload_conf(); show anon.enable; anon.enable ------------on (1 row) 80.4 插件 sys_anon 使用方法 具体参考《KingbaseES 数据库安全指南》第 10 章数据脱敏。 80.5 插件 sys_anon 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 80.6 插件 sys_anon 升级方法 具体参考《KingbaseES 数据库安全指南》第 10 章数据脱敏。 629 第 81 章 SYS_AUDLOG 81章 sys_audlog 第 81.1 插件 sys_audlog 简介 sys_audlog 是一个 KingbaseES 的扩展，可以实现帐户异常登录锁定以及账户登录信息显示。这种方式更为灵 活，当数据库的实用场景需要进行帐户异常登录锁定以及账户登录信息显示时，加载插件即可。而不需要该功能时， 卸载插件即可。 sys_audlog 的相关参数由数据库安全员负责配置。 • 插件名为 sys_audlog • 插件版本 V1.0 81.2 插件 sys_audlog 加载方式 在使用 sys_audlog 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 shared_preload_libraries = 'sys_audlog' 81.3 插件 sys_audlog 的参数配置 • sys_audlog.error_user_connect_times 允许用户连续登录失败的最大次数，用户登录失败的次数大于超过该值，用户自动锁定，取值范围为 [0,INT_MAX]，缺省为 0。 • sys_audlog.max_error_user_connect_times 用 户 登 录 失 败 次 数 的 最 大 值 界 限，error_user_connect_times 的 最 大 取 值， 取 值 范 围 为 [0,INT_MAX]，缺省为 2147483647。 630 第 81 章 SYS_AUDLOG • sys_audlog.error_user_connect_interval 用户被锁定时间，若用户被锁定的时间超过了该参数，则该用户可自动解锁。单位是分钟，取值范围 为 [0，INT_MAX]，0 时关闭自动解锁功能，需手动解锁，缺省为 0。 81.4 插件 sys_audlog 的使用方法 具体参考《KingbaseES 安全指南》第 3.2.2.5 章节账户异常登录锁定和第 3.2.2.6 章节账户登录信息显示。 81.5 插件 sys_audlog 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = '' 81.6 插件 sys_audlog 升级方法 sys_audlog 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 631 第 82 章 SYS_BUFFERCACHE 82章 sys_buffercache 第 82.1 插件 sys_buffercache 简介 插件 sys_buffercache 是 KingbaseES 的一个扩展插件。提供了一种方法用来实时检查共享缓冲区。 • 插件名为 sys_buffercache • 插件版本 V1.3 82.2 插件 sys_buffercache 加载方式 通过 create extension 来加载插件。 示例： create extension sys_buffercache; 82.3 插件 sys_buffercache 的参数配置 无需配置任何参数。 82.4 插件 sys_buffercache 的使用方法 KingbaseES 加载 sys_buffercache 插件后，通过视图 sys_buffercache 查看。 sys_buffercache 视图字段说明： 632 第 82 章 SYS_BUFFERCACHE 名称 类型 描述 bufferid integer ID，在范围 1..shared_buffers 中 relfilenode oid 关系的文件节点编号 reltablespace oid 关系的表空间 OID reldatabase oid 关系的数据库 OID relforknumber smallint 关系内的分支编号 relblocknumber bigint 关系的页码 isdirty boolean 页面是否为脏页 usagecount smallint Clock-sweep 访问计数 pinning_backends integer 固定此缓冲区的后端数 共享缓存中的每一个缓冲区都有一行。未使用的缓冲区的行中显示为除 bufferid 之外的所有字段都为空。共享的 系统目录被显示为属于数据库零。 因为缓冲是所有数据库共享的，通常会有不属于当前数据库的关系的页面。这意味着对于一些行在 sys_class 中 可能不会有匹配的连接行，或者甚至有错误的连接。如果你试图与 sys_class 连接，将连接限制于 reldatabase 等于当 前数据库 OID 或零的行是一个好主意。 当访问 sys_buffercache 视图时，内部缓冲区管理器会被锁住足够长时间来拷贝视图将显示的所有缓冲区状态数 据。这确保了该视图会产生一个一致的结果集合，而不会不必要地长时间阻塞普通的缓冲区活动。尽管如此，如果经 常读取这个视图还是会对数据库性能产生一些影响。 82.5 插件 sys_buffercache 卸载方法 通过 drop extension 来卸载插件。 示例： drop extension sys_buffercache; 82.6 插件 sys_buffercache 升级方法 通过 alter extension 来升级插件。 示例，由 1.2 升级到 1.3： 633 第 82 章 SYS_BUFFERCACHE ALTER EXTENSION sys_buffercache UPDATE TO '1.3'; 634 第 83 章 SYS_BULKLOAD 83章 sys_bulkload 第 83.1 插件 sys_bulkload 简介 sys_bulkload 是一种用于 KingbaseES 快速加载数据的工具。 • 插件名为 sys_bulkload • 插件版本 V2.0 83.2 插件 sys_bulkload 加载方式 启动 KingbaseES 数据库后执行 SQL 命令创建插件。 示例： create extension sys_bulkload; 83.3 插件 sys_bulkload 的参数配置 无需配置任何参数。 83.4 插件 sys_bulkload 的使用方法 KingbaseES 加载 sys_bulkload 插件后，无法单独使用，需要与客户端 sys_bulkload 工具配合使用，详细使用 说明请参考客户端sys_bulkload 工具。 635 第 83 章 83.5 SYS_BULKLOAD 插件 sys_bulkload 卸载方法 在数据库中执行 SQL 命令卸载插件。 示例： drop extension sys_bulkload; 83.6 插件 sys_bulkload 升级方法 sys_bulkload 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级插件。 636 第 84 章 SYS_FREESPACEMAP 84章 sys_freespacemap 第 84.1 插件 sys_freespacemap 简介 sys_freespacemap 提供了查看 FSM 页面的方法。插件提供函数来显示 FSM 页面中记录的指定关系指定页面的 值或是指定关系全部页面的值。默认仅限超级用户、sys_stat_scan_tables 角色的成员使用。 • 插件名为 sys_freespacemap • 插件版本 V1.2 84.2 插件 sys_freespacemap 加载方式 插件为内置插件，自动加载。 84.3 插件 sys_freespacemap 的参数配置 无需配置任何参数 84.4 插件 sys_freespacemap 的使用方法 sys_freespacemap 提供以下函数： sys_freespace(rel regclass IN, blkno bigint IN) returns int2 返回指定关系指定块在 FSM 页面中记录的空闲空间值。 sys_freespace(rel regclass IN, blkno OUT bigint, avail OUT int2) 返回指定关系中每个块在 FSM 页面中记录的空闲 空间值。返回 (blkno bigint, avail int2) 类型的集合，每一行对应关系中的一个块。 FSM 页面中存储的空闲空间值并不是准确的。值会按块大小的 1/256 四舍五入，而且值在表页面被修改时不会 实时更新。对于索引来说，FSM 页面记录的是空闲页面而不是页面中的空闲空间，返回值只代表页面是否为整个空 闲。 637 第 84 章 SYS_FREESPACEMAP 84.5 插件 sys_freespacemap 卸载方法 插件为内置插件，不允许卸载。 84.6 插件 sys_freespacemap 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION sys_freespacemap UPDATE TO '1.1'; 638 第 85 章 SYS_JIEBA 第 85.1 85章 sys_jieba 插件 sys_jieba 简介 sys_jieba 是一个 KingbaseES 的扩展，主要用于全文搜索的中文分词。sys_jieba 中文分词插件支持 utf8 字符 集。 • 插件名为 sys_jieba • 插件版本 V1.0 85.2 插件 sys_jieba 加载方式 CREATE EXTENSION sys_jieba; 85.3 插件 sys_jieba 的参数配置 无需配置任何参数 85.4 插件 sys_jieba 的使用方法 CREATE EXTENSION sys_jieba; SELECT * FROM ts_parse('jieba', 'KingbaseES 中文分词插件测试'); tokid | token -------+-----------2 | KingbaseES 2 | 中文 639 第 85 章 SYS_JIEBA 2 | 分词 2 | 插件 2 | 测试 (5 rows) SELECT to_tsvector('jiebacfg','KingbaseES 中文分词插件测试'); to_tsvector ---------------------------------------------------'kingbasees':1 '中文':2 '分词':3 '插件':4 '测试':5 (1 row) SELECT to_tsquery('jiebacfg', '分词'); to_tsquery -----------'分词' (1 row) 85.5 插件 sys_jieba 的卸载方法 drop extension sys_jieba; 85.6 插件 sys_jieba 升级方法 sys_jieba 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 640 第 86 章 SYS_KWR 86章 sys_kwr 第 86.1 插件 sys_kwr 简介 插件 sys_kwr 是 KingbaseES 的一个扩展插件。主要功能是通过周期性自动记录性能统计相关的快照，分析出 KingbaseES 的操作系统运行环境、数据库时间组成、等待事件和 TOP SQL 等性能指标，为数据库性能调优提供指 导。 sys_kwr 是 Kingbase Auto Workload Repertories 的简称，可以对 KingbaseES 的负载信息自动以快照的方式进 行记录和保存，并提供负载相关的性能报告。 在 1.6 版本中合入了 KSH 功能，KSH 不在做为单独的插件使用，创建 KWR 插件后便可以使用 KSH 功能。 • 插件名为 sys_kwr • 插件版本 V1.6 86.2 插件 sys_kwr 加载方式 KingbaseES 数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加 载。 示例如下 shared_preload_libraries = 'sys_kwr' 86.3 插件 sys_kwr 的参数配置 要想使用 KWR 的全部报告功能，建议在 kingbase.conf 里添加以下 6 个参数 track_sql = on track_instance = on 641 第 86 章 SYS_KWR track_wait_timing = on track_counts = on track_io_timing = on track_functions = 'all' sys_stat_statements.track = 'top' sys_kwr.enable = on 上述参数的意义如下 track_sql: 开启统计 sql 时间，等待事件，IO ，默认为 off track_instance 开启统计实例级 IO，关键活动，锁，默认为 off track_wait_timing 开启累积式等待事件记录等待时间的功能，默认为 off track_counts 统计数据库活动，默认为 on track_io_timing 开启 IO 计时统计功能，默认为 off track_functions 开启函数统计功能，推荐用 'all'，默认为'none' sys_stat_statements.track 跟踪统计 SQL 语句的访问，推荐用 'top'，默认为'none' sys_kwr.enable 自动对收集到的数据生成快照并保存到 kwr 库里，默认为 off 其他参数一般情况下使用默认值即可 sys_kwr.topn kwr 报告显示 topn 条件记录，默认 20 条 sys_kwr.history_days kwr 快照数据保留天数，默认 8 天 sys_kwr.interval kwr 自动采集快照的间隔，默认 60 分钟 sys_kwr.language kwr 报告使用语言，默认为中文（chinese 或 chn），可选为英文 (english 或 eng) sys_stat_statements.track_parse pg_stat_statements 记录 parse 次数和时间，默认开启 sys_stat_statements.track_plan pg_stat_statements 记录 plan 次数和时间，默认开启 642 第 86 章 SYS_KWR 86.4 插件 sys_kwr 的使用方法 86.4.1 概述 sys_kwr 通过周期性自动记录性能统计相关的快照，分析出 KingbaseES 的操作系统运行环境、数据库时间组 成、等待事件和 TOP SQL 等性能指标，为数据库性能调优提供指导。 1、SQL 语句执行过程中产生的等待事件, IO 和执行时间 2、Top SQL 3、数据库对象统计信息 4、数据库实例统计信息 86.4.2 自动快照 KingbaseES 启动服务后，sys_kwr collector 后台进程后会每个小时采集一次负载信息，并保存到 kwr 库 (test)。 查询快照列表 SELECT * FROM perf.kwr_snapshots; snap_id | snap_time | sess_count --------+------------------------+-----------1 | 2021-12-07 17:51:02+08 | 1 2 | 2021-12-07 17:51:03+08 | 1 3 | 2021-12-07 17:51:04+08 | 1 (3 rows) 86.4.3 手动快照 手工快照通过 SQL 语句来执行 SELECT * FROM perf.create_snapshot(); create_snapshot ----------------5 (1 row) 86.4.4 生成 kwr 报告 有了负载信息的快照数据后，就可以调用以下 2 个函数来生成 kwr 报告 643 第 86 章 SYS_KWR SELECT * FROM perf.kwr_report(start_id integer, end_id integer, format text = 'text'); SELECT * FROM perf.kwr_report_to_file(start_id integer, end_id integer, format text, file_path text); perf.kwr_report() 生成报告并加报告内容自动保存到 KingbaseES 的 data/sys_log 目录下。 perf.kwr_report_to_file() 则生成报告并将内容保存指定的 file_path 路径下。 函数参数说明 start_id 起始快照 ID end_id 结束快照 ID format 报告的格式，只支持'text'和'html'格式，建议使用'html'格式。 file_path 在服务器上保存报告文件的全路径，必须有写文件的权限。 86.4.5 生成 html 报告 SELECT * FROM perf.kwr_report(1,2,'html'); • 查看 KWR 报告，请参考 KingbaseES 数据库性能调优指南 3.3.5 章。 86.4.6 KSH 功能 86.4.7 概述 KSH 以每秒采样的方式进行会话和数据收集，并将采集数据放入内存的 Ringbuf 队列中，采集的数据主要包 括：会话、应用、等待事件、命令类型、QueryId 等。其主要使用场景是：当前或历史某个时点，发生了什么样的异 常，系统在执行/运行什么任务。 86.5 KSH 的参数配置 KSH 功能相关的参数在 kingbase.conf 中设置： shared_preload_libraries ='sys_stat_statements, sys_kwr' track_activities = on sys_stat_statements.max = 10000 sys_stat_statements.track =all sys_kwr.collect_ksh = on # default = off 644 第 86 章 SYS_KWR sys_kwr.ringbuf_size = 200000 # default = 100000 sys_kwr.history_days = 3 # default = 8；最小 2，最大 31 sys_kwr.language = 'english' # default = ‘chinese’ 上述参数的意义如下： track_activities：跟踪活动会话的等待事件、执行 SQL、状态等，默认：on sys_stat_statements.max：设置 sys_stat_statement 跟踪的最大语句数，默认：5000 sys_stat_statements.track：跟踪统计 SQL 语句的访问，推荐用 'top'，默认为'none' sys_kwr.collect_ksh：启用或禁用 KSH 数据收集 sys_kwr.ringbuf_size：设置 ksh ringbuf 大小 sys_kwr.history_days：设置最大的 KSH 历史数据存储 sys_kwr.language：KSH 报告展示中文/英语信息 注：采集报告需要在开启：track_activities，并至少设定 sys_kwr.collect_ksh=on 的情况下才可以查看。开启 该参数会有一定的性能损耗。 86.6 KSH 功能的使用方法 86.6.1 采集数据说明 KSH 采集的数据主要包括以下信息： 645 第 86 章 SYS_KWR 字段 类型 描述 ts timestamptz 采样时间 pid int 进程 ID client_addr inet 客户端 IP 地址 app_name varchar(64) 应用名称 db_id oid 数据库 OID db_name varchar(64) 数据库名称 user_id oid 用户 OID user_name varchar(64) 用户名 phase text 执行阶段，如：PARSE, PLAN, EXECUTION, UNKNOWN event_type text 等待事件类型 event text 等待事件 query_id uint8 QueryId cmd_type text 指令类型，如 INSERT, SELECT, UPDATE, DELETE, UTILITY 等 backend_type text 后端类型，如：autovacuum, autovacuum worker 等 state text 运行状态如 running, idle 等 is_simple bool 简单查询语句标志 table_id oid IO 操作变量的表 OID func text 运行 plsql 的函数名 learder_pid int 父进程 pid(针对并行) • 保存于内存 Ringbuf 的数据可以通过视图 perf.session_history 查看： SELECT * FROM perf.session_history; • 保存于数据库的历史数据可以通过视图 perf.ksh_history 查看： SELECT * FROM perf.ksh_history; 646 第 86 章 SYS_KWR 86.6.2 生成报告 SELECT perf.ksh_report({start_ts}, {duration}, {slot_width}); SELECT * FROM perf.ksh_report_to_file({start_ts},{duration},{slot_width},{file_path},{format}); SELECT * FROM perf.ksh_report_by_snapshots({start_snapid}, {end_snapid}, {slot_width}, {format}); SELECT * FROM perf.ksh_report_to_file_by_snapshots({start_snapid}, {end_snapid}, {file_path}, {format}, {slot_width}); 上述参数说明： start_ts: 报告开始时间，默认：当前时间-15 分钟 duration: 报告时长，默认到 15 分钟，最大不超过 60 slot_width: 报告最小区间，输入 0 时系统自动计算合适的 start_snapid: 起始快照号 end_snapid: 结束快照号 file_path: 报告生成地址，示例：’/home/username/ksh_report.html’ format: 报告生成格式，可选择’html’和’text’两种格式 86.7 插件 sys_kwr 卸载方法 进入 KingbaseES 创建插件 示例 DROP EXTENSION sys_kwr; 86.8 插件 sys_kwr 升级方法 通过 alter extension 来升级插件。 示例，由 1.5 升级到 1.6 ALTER EXTENSION sys_kwr UPDATE TO '1.6'; 647 第 87 章 SYS_SQLTUNE 87章 sys_sqltune 第 87.1 插件 sys_sqltune 简介 插件 sys_sqltune 是 KingbaseES 的一个扩展插件。主要功能是通过收集统计信息对 SQL 进行语句级调优。当前 版本具备 SQL 监控功能。 SQL 监控提供有关实时 SQL 监控及数据库操作的监视信息。通过动态性能视图或者监控报告，提供实时的 SQL 语句执行过程中的状态和统计信息 • 插件名为 sys_sqltune • 插件版本 V1.0 87.2 插件 sys_sqltune 加载方式 将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加载。 示例如下 shared_preload_libraries = 'sys_sqltune' 并在数据库中创建插件 CREATE EXTENSION sys_sqltune; 87.3 插件 sys_sqltune 的参数配置 使用 SQL 监控的全部功能，建议在 kingbase.conf 里添加以下参数 648 第 87 章 SYS_SQLTUNE shared_preload_libraries = 'plsql, sys_stat_statements, sys_sqltune' sql_monitor.track = 'all' sys_stat_statements.track = 'all' enable_hint = on 上述参数的意义如下 plsql：支持 plsql，此处主要提供 PACKAGE 特性相关功能 sys_stat_statements：跟踪统计 SQL 语句插件，具体请参考 sys_stat_statements 插件，此处主要提供 query_id 数据项。 sql_monitor.track：开启对 SQL 语句和数据库操作的监控，推荐用 'all'，默认为'none' sys_stat_statements.track：跟踪统计 SQL 语句的访问，推荐用 'all'，默认为'none' enable_hint = on：开启数据库内核 hint 功能，默认为 off 全部相关参数 • sql_monitor.track SQL 语句监控层级，ENUM 类型，默认值为 none TOP：监控顶层 SQL 语句 all：监控嵌套层数小于 64 层的 SQL 语句 none：不监控 会话级参数 • sql_monitor.max 视图最大数据量，整数，默认 1000，最小 100 当系统保存的数据超出最大数量后，扔掉一些陈旧的统计结果，腾出 部分新的空间给新监控的 SQL。 系统级参数 • sql_monitor.track_options 采集统计信息控制参数，ENUM 类型，默认为’basic ’ basic：采集语句全部统计信息和执行计划节点基本统计信 息。full ：在’basic’基础上，采集执行计划节点的 buffer、wal 相关统计信息，有一定性能影响。 会话级参数 • sql_monitor.language 网页版监控报告使用语言，TEXT 类型，默认为中文（chinese 或 chn），可选为英文 (english 或 eng) chinese/ chn：网页版报告输出中文。english/eng：网页版报告输出英文。 会话级参数 649 第 87 章 SYS_SQLTUNE 87.4 插件 sys_sqltune 的使用方法 87.4.1 概述 sys_sqltune 主要功能是通过收集统计信息对 SQL 进行语句级调优。当前版本具备 SQL 监控功能。 87.4.2 SQL 监控概述 对于执行时间较长的 SQL 语句，提供 SQL 监控功能，可以监控其执行状态，以及执行过程中各计划节点的统计 数据，并提供 SQL 监控报告功能。 87.4.3 SQL 监控功能 语句符合条件开始监控后，系统自动将其数据插入共享内存中的动态视图 v$sql_monitor 和 v$sql_plan_monitor 中，间隔约 1 秒刷新一次数据。 • 自动监控 SQL 执行时间超过 5 秒的 SQL 语句被列入监控对象。 • 手动监控 SQL 可通过对语句添加 HINT 来控制语句是否会被监控，需通过 enable_hint GUC 参数开启 HINT 功能。 • 并行语句监控 当语句计划并行，组件在执行开始时将其纳入监控范围，其申请的每个并行 worker 都会在 v$sql_monitor 中插 入一条数据。 • 多层嵌套语句监控 当语句存在嵌套关系，系统会监控其最顶层的 64 层语句，将其中执行时间超过 5 秒的语句列入监控对象，存在 嵌套关系的语句包括： 1. PL/PGSQL-存在多层嵌套调用 2. 带有 SELECT 子句的 DML、DDL 语句-下层为 SELECT 语句 3. EXPLAIN ANALYZE 语句-上层为 EXPLAIN 语句无执行计划，下层为实际执行，有执行计划。 • 监控视图 组件将数据存储在动态视图 v$sql_monitor 和 v$sql_plan_monitor 中，视图最大值受 sql_monitor.max 限制。 • 监控报告 组件可生成详细监控报告和列表监控报告，包括 TEXT 和 HTML 两种类型，其中网页版报告支持中英文， TEXT 版报告仅支持英文。 650 第 87 章 SYS_SQLTUNE 87.4.4 SQL 监控函数接口 在 oracle 与 mysql 模式下，SQL 监控通过 PACKAGE DBMS_SQL_MONITOR 提供函数接口 DBMS_SQL_MONITOR 包信息参考《PLSQL 系统包和类型参考手册》中的 DBMS_SQL_MONITOR 包章 节。 在 pg 模式下，SQL 监控通过 SCHEMA perf 提供函数接口，功能、参数、返回值与 DBMS_SQL_MONITOR 相同 PERF.SQL_MONITOR_RESET()： 用于清空 v$sql_monitor 和 v$sql_plan_monitor 视图中的所有数据。 PERF.REPORT_SQL_MONITOR(): 该函数用于生成监控详细报告，可用参数指定报告类型和生成报告的数据。 PERF.REPORT_SQL_MONITOR_LIST(): 该函数用于生成监控列表报告，可用参数指定报告类型和生成报告的 数据。 PERF.REPORT_SQL_MONITOR_TO_FILE(): 函 数 用 于 生 成 监 控 详 细 报 告， 报 告 生 成 参 照 RE- PORT_SQL_MONITOR 函数，并将报告插入到磁盘指定位置。 PERF.REPORT_SQL_MONITOR_LIST_TO_FILE(): 函 数 用 于 生 成 监 控 列 表 报 告， 报 告 生 成 参 照 RE- PORT_SQL_MONITOR_LIST 函数，并将报告插入到磁盘指定位置。 87.4.5 生成监控报告 通过下面的语句产生几条被监控 SQL 语句注入数据 set sql_monitor.track = 'all'; set enable_hint = on; SELECT * FROM sys_sleep(5); CREATE TABLE smon_test(id bigint); INSERT INTO smon_test SELECT i FROM generate_series(1, 20000) i; SELECT count(*) FROM smon_test; 查看视图 SELECT * FROM V$SQL_MONITOR; SELECT * FROM V$SQL_PLAN_MONITOR; 生成 TEXT 版监控报告 SELECT DBMS_SQL_MONITOR.REPORT_SQL_MONITOR(type=>'TEXT'); 生成网页版监控报告 SELECT DBMS_SQL_MONITOR.REPORT_SQL_MONITOR(type=>'HTML'); 651 第 87 章 SYS_SQLTUNE 生成英文网页版监控报告 set sql_monitor.language = 'english'； SELECT DBMS_SQL_MONITOR.REPORT_SQL_MONITOR(type=>'HTML'); 87.4.6 SQL 监控视图 sql 监控采集的数据主要包括以下信息： 表 87.4.1: V$SQL_MONITOR 字段 类型 描述 sql_id bigint SQL ID，基于 SQL 文本的 SQL 标识 exec_id bigint 执行 ID，每次执行加一（实例级共享） session_id text 会话 ID(会话启动时间.PID) db_id oid 数据库 OID user_id oid 用户 OID query_id bigint SQL 语句 query id（来自 sys_stat_statements） start_ts timestamp 最初启动时间 last_ts timestamp 最后更新时间 px_server bigint 并行执行号，主进程为-1 px_is_cross_instance boolean 语句是否计划并行 px_servers_allocated bigint 计划最大并行数 px_servers_requested bigint 被监控并行数 duration double precision 语句总运行时间 status text 运行状态 statup_time double precision 节点实际执行总时间，单位毫秒 total_time double precision 节点实际执行活动时间，单位毫秒 query text SQL 语句原文 lock_wait_time double precision 后端重量级锁等待时间 见续表 652 第 87 章 SYS_SQLTUNE 表 87.4.1 – 续表 字段 类型 描述 lightlock_wait_time double precision 后端轻量级锁等待时间 buffer_wait_time double precision 服务器进程访问数据缓冲区时间 client_wait_time double precision 客户端等待时间 extension_wait_time double precision 扩展插件等待时间 timeout_wait_time double precision 进程间通讯等待时间 ipc_wait_time double precision 超时等待时间 user_io_wait_time double precision IO 等待时间 other_wait_time double precision 其他等待时间 tuples_num bigint 节点输出元组总数 loops_num bigint 节点调用次数 shared_blks_hit bigint 共享内存命中 shared_blks_read bigint 共享内存块读数量 shared_blks_dirtied bigint 共享磁盘块脏块数量 shared_blks_written bigint 共享磁盘块写数量 local_blks_hit bigint 本地内存命中 local_blks_read bigint 本地内存块读数量 local_blks_dirtied bigint 本地磁盘块脏块数量 local_blks_written bigint 本地磁盘块写数量 temp_blks_read bigint 临时块读 temp_blks_written bigint 临时块写 blk_read_time double precision 读花费时间，单位毫秒 blk_write_time double precision 写花费时间，单位毫秒 wal_records bigint 产生的 WAL 记录数量 wal_fpi bigint 产生的 WAL full page images 数量 见续表 653 第 87 章 SYS_SQLTUNE 表 87.4.1 – 续表 字段 类型 描述 wal_bytes bigint 产生的 WAL 记录的大小 • exec_id 加上 session_id 可以唯一的标识语句的单次执行 • 语句并行时，主进程和并行 worker 之间共用相同 exec_id、session_id，主进程 px_server 为-1，并行 worker 从 0 开始累加。 • query_id 来自sys_stat_statements 插件，可能为 0。 表 87.4.2: V$SQL_PLAN_MONITOR 字段 类型 描述 sql_id bigint SQL ID，基于 SQL 文本的 SQL 标识 exec_id bigint 执行 ID，每次执行加一（实例级共享） session_id text 会话 ID(会话启动时间.PID) db_id oid 数据库 OID user_id oid 用户 OID query_id bigint SQL 语句 query id（来自 sys_stat_statements） start_ts timestamp 最初启动时间 last_ts timestamp 最后更新时间 status text 计划节点状态 plan_index bigint 计划节点编号 plan_type text 计划节点类型 plan_depth bigint 计划节点在计划树中的深度 plan_object_name text 计划对象名 plan_object_type text 计划对象类型 plan_rows bigint 计划预计预计行数 plan_statup_cost bigint 计划预计启动成本 plan_total_cost bigint 计划预计总成本 见续表 654 第 87 章 SYS_SQLTUNE 表 87.4.2 – 续表 字段 类型 描述 statup_time double precision 节点实际执行总时间，单位毫秒 total_time double precision 节点实际执行活动时间，单位毫秒 tuples_num bigint 节点输出元组总数 loops_num bigint 节点调用次数 shared_blks_hit bigint 共享内存命中 shared_blks_read bigint 共享内存块读数量 shared_blks_dirtied bigint 共享磁盘块脏块数量 shared_blks_written bigint 共享磁盘块写数量 local_blks_hit bigint 本地内存命中 local_blks_read bigint 本地内存块读数量 local_blks_dirtied bigint 本地磁盘块脏块数量 local_blks_written bigint 本地磁盘块写数量 temp_blks_read bigint 临时块读 temp_blks_written bigint 临时块写 blk_read_time double precision 读花费时间，单位毫秒 blk_write_time double precision 写花费时间，单位毫秒 wal_records bigint 产生的 WAL 记录数量 wal_fpi bigint 产生的 WAL full page images 数量 wal_bytes bigint 产生的 WAL 记录的大小 • exec_id 、plan_index 加上 session_id 可以唯一的标识语句的单次执行中的单个执行节点。 • 语句并行时，主进程和并行 worker 之间共用相同 exec_id、session_id，主进程 px_server 为-1，并行 worker 从 0 开始累加。 • query_id 来自sys_stat_statements 插件，可能为 0。 • 执行节点的 blk、wal 相关统计数据默认不统计，可通过设置 sql_monitor.track_options 为’full’ 开启统计 655 第 87 章 SYS_SQLTUNE 87.5 插件 sys_sqltune 卸载方法 进入 KingbaseES 卸载插件 示例 DROP EXTENSION sys_sqltune; 87.6 插件 sys_sqltune 升级方法 无 656 第 88 章 SYS_PREWARM 88章 sys_prewarm 第 88.1 插件 sys_prewarm 简介 插件 sys_prewarm 是 KingbaseES 的一个扩展插件。提供了一种方便的方法把关系数据载入到操作系统缓冲区 或者 KingbaseES 缓冲区。可以使用 sys_prewarm 函数手工执行预热，或者通过对配置文件的修改实现在系统重启 时的自动预热。当在 shared_preload_libraries 中包括 sys_prewarm 时系统将自动执行预热，系统将运行一个后台工 作者 autoprewarm master，它会周期性地把共享内存中的内容记录在一个名为 autoprewarm.blocks 的文件中，并且 在重新启动后用后台工作者重新载入块。 • 插件名为 sys_prewarm • 插件版本 V1.2 88.2 插件 sys_prewarm 加载方式 通过 create extension 来加载插件。 示例： create extension sys_prewarm; 如果使用自动预热，则还需要设置在 kingbase.conf 文件中修改 shared_preload_libraries： shared_preload_libraries = 'sys_prewarm' 88.3 插件 sys_prewarm 的参数配置 手工预热无需配置任何参数。 自动预热包括 2 个参数： 657 第 88 章 SYS_PREWARM sys_prewarm.autoprewarm (boolean) 控制服务器是否应该运行 autoprewarm 工作者。默认这个参数为 on。 sys_prewarm.autoprewarm_interval (int) 这是更新 autoprewarm.blocks 的间隔。默认是 300 秒。如果被设置为 0，该文件将不会以常规的间隔方式 转储，而是只在服务器关闭时转储。 请在 kingbase.conf 文件中配置参数 88.4 插件 sys_prewarm 的使用方法 KingbaseES 加载 sys_prewarm 插件后，通过函数来对关系表进行手工预热或自动预热。 手工预热使用 sys_prewarm() 函数： sys_prewarm(regclass, mode text default 'buffer', fork text default 'main', first_block int8 default null, last_block int8 default null) RETURNS int8 该函数第一个参数是要预热的关系表。第二个参数是要使用的预热方法（prefetch、read 或者 buffer）。第三个 参数是要被预热的关系分叉，通常是 main。第四个参数是要预热的第一个块号（NULL 等同于零）。第五个参数是 要预热的最后一个块号（NULL 表示一直预热到关系的最后一个块）。返回值是被预热的块数。 手工预热示例： select sys_prewarm('t1'); 自动预热使用以下 2 个函数： autoprewarm_start_worker() RETURNS void 该函数启动主要的 autoprewarm 工作者。通常情况下系统会自动启动工作者，但是如果没有在服务器启动时配 置自动预热并且用户希望在稍晚的时候启动该工作者，这个函数就能发挥作用。 autoprewarm_dump_now() RETURNS int8 该函数立即更新 autoprewarm.blocks。如果 autoprewarm 工作者没有运行但用户希望它在下一次重启后运行， 则这个函数会很有用。返回值是写入到 autoprewarm.blocks 中的记录数。 88.5 插件 sys_prewarm 卸载方法 通过 drop extension 来卸载插件。 示例： 658 第 88 章 SYS_PREWARM drop extension sys_prewarm; 如果使用自动预热，设置了 shared_preload_libraries，则需要删除’sys_prewarm’。 shared_preload_libraries = '' 88.6 插件 sys_prewarm 升级方法 通过 alter extension 来升级插件。 示例，由 1.1 升级到 1.2： ALTER EXTENSION sys_prewarm UPDATE TO '1.2'; 659 第 89 章 第 89.1 SYS_QUALSTATS 89章 sys_qualstats 插件 sys_qualstats 简介 sys_qualstats 是一个 KingbaseES 的扩展，用于保存 WHERE 语句和 JOIN 子句中谓词的统计信息。如果希望 能够分析数据库中的最常执行的 quals（谓词），这非常的有用，该插件利用这点来提供索引建议。 • 插件名为 sys_qualstats • 插件版本 V1.0.9 89.2 插件 sys_qualstats 加载方式 在使用 sys_qualstats 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库 shared_preload_libraries = 'sys_qualstats,sys_stat_statements' # (change requires restart) sys_qualstats 插件依赖 sys_stat_statements 插件 进入 KingBase 中执行语句创建插件 create extension sys_qualstats; create extension sys_stat_statements; 系统自动创建 sys_stat_statements 插件 89.3 插件 sys_qualstats 的参数配置 可以在 kingbase.conf 中配置以下信息： 660 第 89 章 SYS_QUALSTATS • sys_qualstats.enabled 默认为 on 是否应该启用 sys_qualstats。 • sys_qualstats.max 默认为 1000，要保存的条目数。 • sys_qualstats.track_sys_catalog: 默认为 off，确定是否跟踪 sys_catalog 表上的谓词。 • sys_qualstats.resolve_oids: 默认为 off。确定在谓词收集期间，对象的实际名称是否应该和 OID 一起存储，开 销是不可忽视的，因为每个条目将占用 616 个字节而不是 168 个字节。 • sys_qualstats.track_constants: 默认为 on，是否单独跟踪每个常量值。如果为 true，则每个谓词的每个新值都 会产生一个新条目。 • sys_qualstats.sample_rate: 默认为 0.01，应该被采样的查询比例。1 表示对每个查询进行采样，0 表示基本禁 用该功能，-1 表示自动调整。 • sys_stat_statements.track=’top’:sys_stat_statements 插件配置，设置数据采集级别为’top’。 89.4 插件 sys_qualstats 的使用方法 89.4.1 sys_qualstats 返回每个限定符的计数 userid: 执行查询的用户 oid dbid: 已经执行查询的数据库的 oid lrelid, lattnum: 如果存在左侧 var，表示左侧 var 的关系和属性编号的 oid rrelid, rattnum: 如果存在右侧 var，表示右侧 var 的关系和属性编号的 oid opno: 表达式中使用运算符的 oid qualid 父 AND 表达式的规范化标识符，该标识符的计算不包括常量 qualnodeid 简单谓词的规范标识符，该标识符的计算包括常量 uniquequalid 简单谓词的唯一标识符，该标识符计算包括常量 parenthash: 父 AND 表达式的 hash 值 nbfiltered 此谓词丢弃的元组数 nodehash: 谓词 hash count: 此谓词出现的总次数 queryid: 如果安装了 sys_stat_statements，表示此查询的 queryid，用来追溯查询的 sql constvalue: 右侧常量字符串表示形式，截断为 80 个字符 execution_count 表示这个语句执行了多少次 eval_type 评估类型，f 表示扫描后评估的谓词，i 表示索引谓词 661 第 89 章 SYS_QUALSTATS \x select * from sys_qualstats; -[ RECORD 1 ]-----+--------------------userid | 10 dbid | 16249 lrelid | 17227 lattnum | 1 opno | 96 rrelid | rattnum | qualid | 570210875 uniquequalid | 420950748 qualnodeid | 2712005185 uniquequalnodeid | 2320559360 occurences | 1 execution_count | 3 nbfiltered | 2 constant_position | 28 queryid | -3480922324520548892 constvalue | 100::integer eval_type | f 使用\x 将数据纵向排列，方便阅读 89.4.2 sys_qualstats_reset() 重置内部计数器并清除每个遇到的 qual（谓词） select * from sys_qualstats_reset(); sys_qualstats_reset -------------------(1 row) 89.4.3 sys_qualstats_example_query 返回给定 queryid 的 SQL 语句 select * from sys_qualstats_example_query(-3480922324520548892); sys_qualstats_example_query --------------------------------------------------select * from t1 where id = 100 and name = 'abc'; (1 row) 662 第 89 章 SYS_QUALSTATS 89.4.4 sys_qualstats_names 返回所有存储的 SQL 语句 select * from sys_qualstats_names(); -[ RECORD 1 ]-----+--------------------userid | 10 dbid | 16249 lrelid | 17227 lattnum | 1 opno | 96 rrelid | rattnum | qualid | 570210875 uniquequalid | 420950748 qualnodeid | 2712005185 uniquequalnodeid | 2320559360 occurences | 1 execution_count | 3 nbfiltered | 2 constant_position | 28 queryid | -3480922324520548892 constvalue | 100::integer eval_type | f rolname | dbname | lrelname | lattname | opname | rrelname | rattname | 89.4.5 sys_qualstats_example_queries 返回所有存储的查询 sql select query from sys_qualstats_example_queries(); query --------------------------------------------------select * from t1 where id = 100; select * from t1 where id = 100 and name = 'abc'; select * from t1 where id = 100 and age = 300; (3 rows) 663 第 89 章 SYS_QUALSTATS 89.4.6 sys_qualstats_pretty 显示 sys_qualstats 视图中每个属性的可读形式 select * from sys_qualstats_pretty; left_schema | left_table | left_column | operator | right_schema | right_table | right_column | occurences | execution_count | nbfiltered ------------+------------+-------------+---------------+--------------+-------------+--------------+-----------+-----------------+-----------public | t1 | age 3 | 1 | public | t1 4 | | id | t1 1 | | | | | sys_catalog.= | | | | | sys_catalog.= | | | | 3 12 | public | sys_catalog.= | 9 | name 3 | 2 89.4.7 sys_qualstats_all 对每个属性/运算符的计数求和 select * from sys_qualstats_all; dbid | relid | userid | queryid | attnums | opno | qualid | occurences | execution_count | nbfiltered | qualnodeid -------+-------+--------+----------------------+---------+------+------------+------------+----------------+------------+-----------16249 | 17227 | 2 | | 96 | 570210875 | 1 | 3 | | 98 | 570210875 | 1 | 3 | 6307461809864648304 | {1,2} | 96 | 2519621490 | 2 | 6 | 6828434147671954623 | {1} | 96 | 2 | 6 | 570210875 16249 | 17227 | 2 | 10 | -3480922324520548892 | {1} 10 | -3480922324520548892 | {3} 570210875 16249 | 17227 | 10 | 6 | 2519621490 16249 | 17227 | 10 | | 4 | 2712005185 89.4.8 sys_qualstats_indexes 查找不存在索引的属性，并给出需要创建索引建议 select * from sys_qualstats_indexes; relid | attnames | possible_types | execution_count -------+-----------+--------------------------+----------------t1 | {age,id} | {brin,btree,hash} | 6 664 第 89 章 t1 | {id} | {brin,btree,hash} | 6 t1 | {id,name} | {brin,btree,hash,spgist} | 3 SYS_QUALSTATS 89.4.9 sys_qualstats_by_query 仅返回形式为 VAR OPERATOR CONSTANT 的谓词 select * from sys_qualstats_by_query; -[ RECORD 1 ]----+------------------------------------------------------------------------uniquequalnodeid | 41333584 dbid | 16249 userid | 10 qualnodeid | 1621559404 occurences | 1 execution_count | 9 nbfiltered | 0 queryid | -6920971673199143593 constvalues | {2::integer,2::integer} quals | {"(16457,1,523,i)","(16457,1,525,i)"} 89.4.10 使用索引建议 89.4.10.1 参数配置 kingbase.conf 中设置 shared_preload_libraries = 'sys_qualstats,sys_stat_statements,sys_hypo' # (change requires restart) sys_stat_statements.track='top' sys_qualstats.sample_rate=1 89.4.10.2 创建插件 create extension sys_qualstats; create extension sys_hypo; create extension sys_stat_statements; 插件 sys_stat_statements 由系统自动创建 665 第 89 章 89.4.10.3 SYS_QUALSTATS 示例 89.4.10.3.1 准备测试数据 create table t1(id int, name text); INSERT INTO t1 SELECT (random() * 1000000)::int, md5(g::text) FROM generate_series(1, 1000000) g; Select * from t1 where id = 100; id | name ----+--------------------------------100 | 71735fbd796ae9e347ad82f208f1232b 100 | 4fea58f776ef5d6e22156e08c2191b09 100 | 177848a70c96523b9c7a18dae7f9631d (3 rows) 89.4.10.3.2 查看执行计划 explain analyze Select * from t1 where id = 100; QUERY PLAN ----------------------------------------------------------Gather (cost=1000.00..15375.79 rows=5292 width=36) (actual time=18.471..183.579 rows=3 loops=1) Workers Planned: 2 Workers Launched: 0 -> Parallel Seq Scan on t1 (cost=0.00..13846.59 rows=2205 width=36) (actual time=18.043..183.089 rows=3 loops=1) Filter: (id = 100) Rows Removed by Filter: 999997 Planning Time: 0.134 ms Execution Time: 183.658 ms (8 rows) 89.4.10.3.3 查看索引建议 new_cost: 创建索引以后的 cost 值 old_cost 无索引情况的 cost 值 ddl_index 创建 index 的 sql 语句 benefit 创建索引后的收益值 \x select * from index_recommendation_by_qual; -[ RECORD 1 ]---+----------------------------------------- 666 第 89 章 nspname | public relid | t1 attnames | {id} possible_types | {brin,btree,hash} SYS_QUALSTATS execution_count | 1000000 queryid | -8700169081888605904 query | Select * from t1 where id = 100; ddl_index | CREATE INDEX ON public.t1 USING btree (id) old_cost | 15375.79 new_cost | 7864.65 benefit | 48.85 % maintenece_cost | 95.000000 使用\x 将数据纵向排列，方便阅读 89.4.10.4 根据索引建议创建索引 CREATE INDEX ON public.t1 USING btree (id); 89.4.10.5 查看创建完索引后的执行计划 explain analyze Select * from t1 where id = 100; QUERY PLAN -------------------------------------------------------Index Scan using t1_id_idx on t1 (cost=0.42..12.46 rows=2 width=37) (actual time=0.053..0.060 rows=2 loops=1) Index Cond: (id = 100) Planning Time: 0.171 ms Execution Time: 0.165 ms (4 rows) 89.5 插件 sys_qualstats 卸载方法 进入 KingbaseES 执行语句删除插件 drop extension sys_qualstats ; drop extension sys_hypo ; 667 第 89 章 89.6 SYS_QUALSTATS 插件 sys_qualstats 升级方法 sys_qualstats 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 668 第 90 章 第 90.1 SYS_RECOVERY 90章 sys_recovery 插件 sys_recovery 简介 插件 sys_recovery 是数据找回工具，通过读取死元组来恢复不可见的表数据，可以找回 update / delete / rollback / drop column 操作后的数据，并以表的形式返回，可以方便的各种查询，帮助寻找需要的数据。 • 插件名为 sys_recovery • 插件版本为 V1.0 90.2 插件 sys_recovery 加载方式 CREATE EXTENSION sys_recovery; 90.3 插件 sys_recovery 的参数说明配置 函数接口 sys_recovery() 按输出格式返回结果集（数组或表格）。 select * from sys_recovery(regclass, recoveryrow bool DEFAULT true) as (col1 type1, col2 type2, … , colN typeN); 传入参数 • regclass（关系名） • recoveryrow（类型为 bool，t 表示仅被恢复的元组，f 表示所有元组；不传入此项参数时，默认值为 true） 输出按照 as 后面指定的列进行输出。输出列包含： 1. 表中的列（type 是对应列的类型） 669 第 90 章 SYS_RECOVERY 2. 特殊列 sys_recovery 也支持指定输出表对象的系统隐含列，供恢复数据的筛选查询，如： • xmax、xmin（类型为 xid） • ctid（类型为 tid） • cmin、cmax（类型为 cid） • tableoid（类型为 oid） 如果列名或类型名错误、不匹配都会报错。 90.4 插件 sys_recovery 的使用方法 加载 sys_recovery 插件后，可使用如下函数对指定表查询待恢复的数据。 注意: 恢复数据前，请先设置 vacuum_defer_cleanup_age，防止死元组被清除。 1. 仅查询待恢复的数据 例如对表 test 进行查询。假设 test 有两列数据，分别是 int 列 a 和 char 列 b。 select * from sys_recovery('test') as (a int, b char); 2. 查询待恢复数据时附带系统列 例如对表 test 进行查询。假设 test 有两列数据，分别是 int 列 a 和 char 列 b。需要查询的系统列包括 xmin、 xmax 和 ctid。 select * from sys_recovery('test') as (ctid tid, xmin xid, xmax xid, a int, b char); 3. 查询包括可见数据和待恢复数据在内的所有数据 例如对表 test 进行查询。假设 test 有两列数据，分别是 int 列 a 和 char 列 b。 select * from sys_recovery('test', false) as (a int, b char); 4. 查询已删除列的数据 例如对表 test 进行查询。假设 test 有两列数据，分别是 int 列 a 和 char 列 b，列 b 已被删除。 此时需要先行获取已删除列的 attnum 值。 select attnum from sys_attribute, sys_class where attrelid = sys_class.oid and sys_class.relname='test' and attname~'dropped'; 再通过返回的 attnum 值进行查询。假设此处 attnum 返回值为 2。 670 第 90 章 SYS_RECOVERY select * from sys_recovery('test') as (a int, dropped_attnum_2 char); 90.5 插件 sys_recovery 卸载方法 通过 drop extension 来卸载插件。 drop extension sys_recovery; 90.6 插件 sys_stat_statements 升级方法 通过 alter extension 来升级插件。 示例，由 1.0 升级到 1.1 ALTER EXTENSION sys_recovery UPDATE TO '1.1'; 90.7 其它说明 sys_recovery 通过读取死元组来恢复不可见的表数据。如果死元组已经被清除掉，那么 sys_recovery 便不能恢复 出数据。 • vacuum_defer_cleanup_age 设置保留恢复最近多少个事务的数据。建议在数据恢复场景首先设置一个较大的 vacuum_defer_cleanup_age 参数来避免待恢复的数据被清除。vacuum_defer_cleanup_age 范围内的死元组无法被清理，可能会导致表膨 胀，占用更多的存储空间。 671 第 91 章 SYS_SPACEQUOTA 第 91.1 91章 sys_spacequota 插件 sys_spacequota 简介 sys_spacequota 可以对指定表空间的大小进行限额，一旦大于该限额，对此表空间里的数据进行 insert, update, copy to, select into, create index 操作将会被警告或终止（默认为警告，警告或者终止可以通过 GUC 参数 “ spacequota.fullwarningtype = 0/1“来配置）。 • 插件名为 sys_spacequota • 插件版本 V1.0 91.2 插件 sys_spacequota 加载方式 使用时需要创建扩展。 示例： create extension sys_spacequota; 91.3 插件 sys_spacequota 的参数配置 spacequota.warning_email_enable 表空间限额邮件告警的开关，参数为 bool 类型，默认为 false。 672 第 91 章 SYS_SPACEQUOTA 91.4 插件 sys_spacequota 的使用方法 91.4.1 开关及查询: 开关：创建扩展后，再开启参数开关，限额功能生效，开关不能执行在创建扩展之前。 alter system set spacequota.enable = on ; call sys_reload_conf(); 查询信息： select * from sys_space_quota; 91.4.2 remove_space_quota 删除表空间限额, 可调用 remove_space_quota(oid) 方法。 语法 remove_space_quota(oid) 参数 oid 表空间的 oid 值。 返回值 无返回值。 示例： call remove_space_quota(16384); 91.4.3 space_quota_check 核对表空间的限额，一旦大于该限额，对此表空间里的数据进行 insert, update, copy to , select into, create index 操作将会被警告或终止（默认为警告，警告或者终止可以通过 GUC 参数 “ spacequota.fullwarningtype = 0/1“来配 置）。 语法 space_quota_check() 参数 673 第 91 章 SYS_SPACEQUOTA 无参数。 返回值 无返回值。 91.4.4 set_space_quota(oid, quota) 设置或更改表空间限额, 可调用 set_space_quota(oid, quota) 方法，quota 的单位为字节。 语法 set_space_quota(oid, quota)。 参数 oid：表空间的 oid 值。 quota：设置的表空间限额值。 返回值 无返回值。 示例： select spcname,oid from sys_tablespace; spcname | oid -------------+------sys_default | 1663 sys_global | 1664 space1 | 16384 (3 rows) select set_space_quota(16384,11188800); set_space_quota ----------------(1 row) 91.5 插件 sys_spacequota 卸载方法 不需要使用时删除插件即可。 示例： 674 第 91 章 SYS_SPACEQUOTA drop extension sys_spacequota; 91.6 插件 sys_spacequota 升级方法 sys_spacequota 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 675 第 92 章 SYS_SQUEEZE 92章 sys_squeeze 第 92.1 插件 sys_squeeze 简介 sys_squeeze 是 KingbaseES 的一个扩展插件，该组件将提供人工调用命令实现对表 dead tuple 的清理工作。该 组件在清理表空间的过程中，不会全程加排他锁，能保证运行期间尽可能不影响对目标表的访问。该插件的实现依赖 于逻辑解码，因此使用该插件之前必须保证数据库 wal_level 等级设置为’logical’。 该 插 件 提 供 了 清 理 表 空 间 的 函 数， 创 建 插 件 并 设 置 好 wal_level 后， 通 过 调 用 select squeeze.squeeze_table(opt1,opt2,opt3,opt4,opt5) 进行清理操作。各参数的说明请见参数配置一节。 • 插件名为 sys_squeeze • 插件版本 V1.4 其他说明： • sys_squeeze 不支持对包含复合类型的表进行清理 • sys_squeeze 依赖逻辑复制，要求目标表有主键或唯一约束作为 IDENTITY INDEX，并占用一个复制槽 • sys_squeeze 清理重建表时，尽量避免该表的 ALTER TABLE、ALTER INDEX、VACUUM FULL、CLUSTER 或 TRUNCATE 并发操作 • sys_squeeze 不支持对分区表主表直接清理重建，需要对子表执行清理重建 • sys_squeeze 建议在非业务高峰期执行，建议尽量避免对大表使用 • sys_squeeze 需要额外的临时存储空间，请确保 data 目录或目标表空间容量充足，存储空间容量要求最多为目 标表（包括其索引、toast 表）的容量大小 92.2 插件 sys_squeeze 加载方式 首先确认 sys_squeeze 是否已存在于 kingbase.conf 的 shared_preload_libraries 配置项中，正常情况 下 sys_squeeze 默认会加载到 shared_preload_libraries， 可 直 接 执 行 下 一 步 语 句； 如 果 没 有 配 置， 需 要 将 ‘sys_squeeze’追加到该配置中，并重启数据库。 676 第 92 章 SYS_SQUEEZE 执行 create extension sys_squeeze; 语句。 shared_preload_libraries = 'sys_squeeze' 92.3 插件 sys_squeeze 的参数配置 函数接口 squeeze.squeeze_table(opt1,opt2,opt3,opt4,opt5) 有 5 个可配置参数： opt1: 填写所要清理的目标表的模式名，必须项 opt2: 填写所要清理的目标表名，必须项 opt3: 指定该表中已存在的 index 名，若指定，会在新生成的表空间中按照此 index 顺序物理排列 tuple，可选 项，不指定填 null opt4: 指定将新生成的表置入指定的表空间。可选项，若不指定填 null，表示仍然使用原有表空间。 opt5: 将相应 index 置入指定的表空间。可选项，若不指定填 null，表示仍然使用原有表空间。 92.4 插件 sys_squeeze 的使用方法 加载 sys_squeeze 插件后，可使用如下函数对指定表做清理。 1. 普通的清理 例如要对 public 模式下的 test 表做清理 select squeeze.squeeze_table('public','test',null,null,null); 2. 指定按照索引顺序对表内元祖进行物理排序 例如要对 public 模式下的 test 表，按照已有的索引 idx 对表内元祖重排 select squeeze.squeeze_table('public','test','idx',null,null); 3. 指定将重排后的表置入指定的表空间 例如要对 public 模式下的 test 表，放入表空间 tbl_spc1 select squeeze.squeeze_table('public','test',null,'tbl_spc1',null); 4. 指定将重排后的表及索引置入指定的表空间 例如要对 public 模式下的 test 表以及索引 idx，放入表空间 tbl_spc1 677 第 92 章 SYS_SQUEEZE select squeeze.squeeze_table('public','test',null,'tbl_spc1',ARRAY[['idx','tbl_spc1']]); 92.5 插件 sys_squeeze 卸载方法 执行 drop extension sys_squeeze; 语句。删除 kingbase.conf 文件中 shared_preload_libraries 内的 sys_squeeze 参数，重启数据库。 92.6 插件 sys_squeeze 升级方法 sys_squeeze 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 678 第 93 章 SYS_STAT_STATEMENTS 93章 sys_stat_statements 第 93.1 插件 sys_stat_statements 简介 插件 sys_stat_statements 是 KingbaseES 的一个扩展插件。该插件提供了一种获取服务器执行的所有 SQL 语句 统计信息的方法, 可以用于统计数据库的资源开销，如分析 TOP SQL。 • 插件名为 sys_stat_statements • 插件版本 V1.10 93.2 插件 sys_stat_statements 加载方式 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = 'sys_stat_statements' 93.3 插件 sys_stat_statements 的参数配置 该组件的主要配置参数 • sys_stat_statements.max（整数） sys_stat_statements.max 是模块跟踪的最大语句数（即 sys_stat_statements 视图中的最大行数）。如果观察 到的语句不同，则将丢弃关于执行最少的语句的信息。默认值为 5000。只能在服务器启动时设置此参数。 • sys_stat_statements.track（枚举） sys_stat_statements.track 控制模块计算哪些语句。指定 top 以跟踪顶级语句（由客户端直接发出的语句），全 部也可以跟踪嵌套语句（例如在函数内调用的语句），或者不指定以禁用语句统计信息收集。默认值为 top。仅超级 用户可以更改此设置。 注意该参数在 V9R5 里默认值为’top’，如果需要使用 sys_stat_statements 功能，需要将其配置为’top’。 679 第 93 章 SYS_STAT_STATEMENTS • sys_stat_statements.track_utility（boolean） sys_stat_statements.track_utility 控制模块是否跟踪实用程序命令。实用程序命令是除 SELECT，INSERT， UPDATE 和 DELETE 之外的所有命令。默认值为 on。仅超级用户可以更改此设置。 • sys_stat_statements.save（boolean） sys_stat_statements.save 指定是否在服务器关闭时保存语句统计信息。如果关闭，则统计信息不会在关闭时保 存，也不会在服务器启动时重新加载。默认值为 on。只能在 kingbase.conf 文件或服务器命令行中设置此参数。 该模块需要与 sys_stat_statements.max 成比例的附加共享内存。请注意，即使 sys_stat_statements.track 设置 为’none’，只要加载模块，就会消耗此内存。 这些参数必须在 kingbase.conf 中设置。典型用法是： ＃ kingbaseconf shared_preload_libraries ='sys_stat_statements' sys_stat_statements.max = 10000 sys_stat_statements.track = 'top' 93.4 插件 sys_stat_statements 的使用方法 KingbaseES 加载 sys_stat_statements 插件后，通过视图 sys_stat_statements 查看。 表 93.4.1: 视图结构 名称 类型 描述 userid oid 执行该语句的用户的 OID dbid oid 在其中执行该语句的数据库的 OID queryid bigint 内部哈希码，从语句的解析树计算得来 query text 语句的文本形式 calls bigint 被执行的次数 total_time double precision 在该语句中花费的总时间，以毫秒计 min_time double precision 在该语句中花费的最小时间，以毫秒计 max_time double precision 在该语句中花费的最大时间，以毫秒计 mean_time double precision 在该语句中花费的平均时间，以毫秒计 stddev_time double precision 在该语句中花费时间的总体标准偏差，以毫秒计 见续 680 第 93 章 SYS_STAT_STATEMENTS 表 93.4.1 – 续表 名称 类型 描述 rows bigint 该语句检索或影响的行总数 shared_blks_hit bigint 该语句造成的共享块缓冲命中总数 shared_blks_read bigint 该语句读取的共享块的总数 shared_blks_dirtied bigint 该语句弄脏的共享块的总数 shared_blks_written bigint 该语句写入的共享块的总数 local_blks_hit bigint 该语句造成的本地块缓冲命中总数 local_blks_read bigint 该语句读取的本地块的总数 local_blks_dirtied bigint 该语句弄脏的本地块的总数 local_blks_written bigint 该语句写入的本地块的总数 temp_blks_read bigint 该语句读取的临时块的总数 temp_blks_written bigint 该语句写入的临时块的总数 blk_read_time double precision 该语句花在读取块上的总时间，以毫秒计（如果 tra ck_io_timing 被启用，否则为零 blk_write_time double precision 该语句花在写入块上的总时间，以毫秒计（如果 tra ck_io_timing 被启用，否则为零 sys_stat_statements_all 视图结构： 表 93.4.2: 视图结构 名称 类型 描述 userid oid 执行该语句的用户的 OID dbid oid 在其中执行该语句的数据库的 OID queryid bigint 内部哈希码，从语句的解析树计算得来 parent_queryid bigint 上一层 SQL 的哈希码 query text 语句的文本形式 parses bigint 该语句被解析的次数 total_parse_time double precision 在该语句中解析花费的总时间，以毫秒计 见续表 681 第 93 章 SYS_STAT_STATEMENTS 表 93.4.2 – 续表 名称 类型 描述 min_parse_time double precision 在该语句中解析花费的最小时间，以毫秒计 max_parse_time double precision 在该语句中解析花费的最大时间，以毫秒计 mean_parse_time double precision 在该语句中解析花费的平均时间，以毫秒计 stddev_parse_time double precision 在该语句中解析花费时间的总体标准偏差，以毫秒计 plans bigint 该语句执行 Plan 的次数 total_plan_time double precision 在该语句中执行 Plan 花费的总时间，以毫秒计 min_plan_time double precision 在该语句中执行 Plan 花费的最小时间，以毫秒计 max_plan_time double precision 在该语句中执行 Plan 花费的最大时间，以毫秒计 mean_plan_time double precision 在该语句中执行 Plan 花费的平均时间，以毫秒计 stddev_plan_time double precision 在该语句中执行 P lan 花费时间的总体标准偏差，以毫秒计 calls bigint 被执行的次数 total_exec_time double precision 在该语句中花费的总时间，以毫秒计（该字段在 V9R5 里面为：total_time） min_exec_time double precision 在该语句中花费的最小时间，以毫秒计（该字段在 V9R5 里面为： min_time） max_exec_time double precision 在该语句中花费的最大时间，以毫秒计（该字段在 V9R5 里面为： max_time） mean_exec_time double precision 在该语句中花费的平均时间，以毫秒计（该字段在 V9R5 里面为： mean_time） stddev_exec_time double precision 在该语句中花费时间的总体标准偏差，以毫秒计（该字段在 V9R5 里面为：stddev_time） rows bigint 该语句检索或影响的行总数 shared_blks_hit bigint 该语句造成的共享块缓冲命中总数 shared_blks_read bigint 该语句读取的共享块的总数 shared_blks_dirtied bigint 该语句弄脏的共享块的总数 shared_blks_written bigint 该语句写入的共享块的总数 见续表 682 第 93 章 SYS_STAT_STATEMENTS 表 93.4.2 – 续表 名称 类型 描述 local_blks_hit bigint 该语句造成的本地块缓冲命中总数 local_blks_read bigint 该语句读取的本地块的总数 local_blks_dirtied bigint 该语句弄脏的本地块的总数 local_blks_written bigint 该语句写入的本地块的总数 temp_blks_read bigint 该语句读取的临时块的总数 temp_blks_written bigint 该语句写入的临时块的总数 blk_read_time double precision 该语句花在读取块上的总时间，以毫秒计 blk_write_time double precision 该语句花在写入块上的总时间，以毫秒计 出于安全原因，非超级用户不允许查看其他用户执行的 SQL 文本或 queryid。但是，如果视图已安装在数据库 中，则他们可以查看统计信息。 只要有计划的查询（即 SELECT，INSERT，UPDATE 和 DELETE）根据内部哈希计算具有相同的查询结构， 它们就会组合到单个 sys_stat_statements 条目中。通常，如果两个查询在语义上等效，则两个查询在此意义上相 同，只是出现在查询中的文字常量的值除外。但是，将严格根据实用程序命令（即所有其他命令）的文本查询字符串 进行比较。 当为了将查询与其他查询匹配而忽略了常量的值时，该常量将替换为’？’。在 sys_stat_statements 显示中，查 询文本的其余部分是第一个查询的文本，该查询具有与 sys_stat_statements 条目关联的特定 queryid 哈希值。 在某些情况下，文本明显不同的查询可能会合并到一个 sys_stat_statements 条目中。通常，这仅会在语义上等 效的查询中发生，但是散列冲突会导致不相关的查询合并到一个条目中的可能性很小。（但是，这对于属于不同用户 或数据库的查询不会发生） UTILITY 语句中的 CALL 语句与有计划的查询（即 SELECT，INSERT，UPDATE 和 DELETE）具有类似的 获取 queryid 和常量替换逻辑。需要说明：PLSQL/PLPGSQL 由于结果集缓存，执行 sys_stat_statements_reset() 后，部分 CALL proc(xxx); 语句中的常量无法替换。 93.5 插件 sys_stat_statements 卸载方法 通过 drop extension 来卸载插件。 drop extension sys_stat_statements; 683 第 93 章 SYS_STAT_STATEMENTS 93.6 插件 sys_stat_statements 升级方法 通过 alter extension 来升级插件。 示例，由 1.8 升级到 1.9 ALTER EXTENSION sys_stat_statements UPDATE TO '1.9'; 684 第 94 章 SYS_TRGM 94章 sys_trgm 第 94.1 插件 sys_trgm 简介 sys_trgm 模块提供用于决定基于 trigram 匹配的字母数字文本相似度的函数和操作符，以及支持快速搜索相似 字符串的索引操作符类。 • 插件名为 sys_trgm • 插件版本 V1.4 94.2 插件 sys_trgm 加载方式 create extension sys_trgm; 94.3 插件 sys_trgm 的参数配置 无需配置任何参数 94.4 插件 sys_trgm 的使用方法 94.4.1 函数 表 94.4.1 显示 sys_trgm 模块所提供的函数。 685 第 94 章 SYS_TRGM 表 94.4.1: sys_trgm 函数 函数 返回值 描述 similarity(text, text) real 返回一个数字指示两个参数有多相似。该结果的范围是 0（指示两个字符串完全不相似）到 1（指示两个字符串 完全一样）。 show_trgm(text) text[] 返回一个给定字符串中所有的 trigram 组成的一个数组 （实际上除了调试很少有用）。 word_similarity(text, text) real 返回一个数字表示第一个字符串中的 trigram 集合与第 二个字符串中 trigram 的有序集中任何连续部分的最大 相似度。详情请见下文的解释。 strict_word_similarity(text, text) real 与 word_similarity(text, text) 相同，但是强制连续 部分的边界与词边界相匹配。由于我们没有跨词的 trigram，这个函数实际上返回第一个字符串和第二个字符 串任意连续部分的相似度。 show_limit() real 返回% 操作符使用的当前相似度阈值。例如，这设定两 个词被认为足够相似时，它们之间应满足的最小相似度 （已废弃）。 set_limit(real) real 设定% 操作符使用的当前相似度阈值。该阈值必须介于 0 和 1 之间（默认为 0.3）。返回传递进来的同一个值 （已废弃）。 考虑下面的例子： SELECT word_similarity('word', 'two words'); word_similarity ----------------0.8 (1 row) 在第一个字符串中，trigram 集合是 {” w”,” wo”,”wor”,”ord”,”rd ”}。在第二个字符串中，trigram 的有序集是 {” t”,” tw”,”two”,”wo ”,” w”,” wo”,”wor”,”ord”,”rds”,”ds ”}。在第二个字符串中最相似的 trigram 有序集的部分是 {” w”,” wo”,”wor”,”ord”}，并且相似度是 0.8。 这个函数返回的值可以大概地理解为第一个字符串和第二个字符串任意子串的最大相似度。不过，这个函数不会 对该部分的边界加入填充。因此，除了失配的词边界之外，第二个字符串中存在的额外字符的数目没有被考虑。 同时，strict_word_similarity(text, text) 在第二个字符串中选择一个由词构成的部分。在上面的例子中， strict_word_similarity(text, text) 会选择单个词’words’ 形成的部分，其 trigram 集合为 {” w”,” wo”,”wor”,”ord”,” rds”,”ds ”}。 686 第 94 章 SYS_TRGM SELECT strict_word_similarity('word', 'two words'), similarity('word', 'words'); strict_word_similarity | similarity ------------------------+-----------0.5714286 | 0.5714286 (1 row) 因此，strict_word_similarity(text, text) 函数对于计算整个词的相似度有用，而 word_similarity(text, text) 更 适合于计算词的部分相似度。 注意: 在从一个字符串中提取 trigram 时，sys_trgm 会忽略非词字符（非字母数字）。在决定字符串中所含 的 trigram 集合时，每一个词被认为具有两个空格前缀和一个空格后缀。例如，字符串“cat”中的 trigram 集合 是：“c”、“ca”、“cat”以及“at ”。字符串“foo|bar”中的 trigram 集合是：“f”、“fo”、“foo”、“oo ”、“b”、“ba”、“bar”以及“ar ”。 94.4.2 操作符 表 94.4.2 显示 sys_trgm 模块所提供的操作符。 687 第 94 章 SYS_TRGM 表 94.4.2: sys_trgm 操作符 操作符 返回值 描述 text % text boolean 如果参数具有超过 sys_trgm.similarity_threshold 设置 的当前相似度阈值的相似度，则返回 true。 text <% text boolean 如果第一个参数中的 trigram 集合与第二个参数中有 序 trigram 集合的一个连续部分之间的相似度超过 sys_trgm.word_similarity_threshold 参数设置的当前 词相似度阈值，则返回 true。 text %> text boolean <% 操作符的交换子。 text «% text boolean 如果第二个参数有有序 trigram 集合的一个连续部分匹 配词边界，并且其与第一个参数的 trigram 集合的相似 度超过 sys_trgm.strict_word_similarity_threshold 参 数设置的当前严格词相似度阈值，则返回 true。 text %» text boolean «% 操作符的交换子。 text <-> text real 返回参数之间的“距离”，即 1 减去 similarity() 值。 text «-> text real 返 回 参 数 之 间 的 “距 离”， 它 是 1 减去 1 减去 word_similarity() 的值。 text <-» text real «-> 操作符的交换子。 text «<-> text real 返 回 参 数 之 间 的 “距 离”， 也 就 是 strict_word_similarity() 的值。 text <-»> text real «<-> 操作符的交换子。 94.4.3 GUC 参数 sys_trgm.similarity_threshold (real) 设置% 操作符使用的当前相似度阈值。该阈值必须位于 0 和 1 之间（默认是 0.3）。 sys_trgm.word_similarity_threshold (real) 设置 <% 和%> 操作符使用的当前词相似度阈值。该阈值必须位于 0 和 1 之间（默认是 0.6）。 sys_trgm.strict_word_similarity_threshold (real) 设置 «% 和%» 运算符使用的当前严格单词相似性阈值。阈值必须 介于 0 和 1 之间（默认值为 0.5）。 688 第 94 章 SYS_TRGM 94.4.4 索引支持 sys_trgm 模块提供了 GiST 和 GIN 索引操作符类，这允许你在一个文本列上创建索引用于快速相似度搜索的目 的。这些索引类型支持上述的相似度操作符，并且额外支持基于 trigram 的索引搜索用于 LIKE、ILIKE、~ 和 ~* 查 询（这些索引不支持等值或简单比较操作符，因此你可能还需要一个常规的 B-树索引）。 例子： CREATE TABLE test_trgm (t text); INSERT INTO test_trgm VALUES ('words'), ('word'), ('two words'),('ord'); CREATE INDEX trgm_idx ON test_trgm USING GIST (t gist_trgm_ops); 或 CREATE INDEX trgm_idx ON test_trgm USING GIN (t gin_trgm_ops); 此时，你将有一个 t 列上的索引，你可以用它进行相似度搜索。一个典型的查询是 SELECT t, similarity(t, 'word') AS sml FROM test_trgm WHERE t % 'word' ORDER BY sml DESC, t; t | sml -----------+-----------word | 1 words | 0.5714286 two words | 0.36363637 (3 rows) 这将返回在文本列中与 word 足够相似的所有值，按最佳匹配到最差匹配的方式排序。索引将被用来让这种搜索 变快，即使在一个非常大的数据集上。 上述查询的一种变体是 SELECT t, t <-> 'word' AS dist FROM test_trgm ORDER BY dist LIMIT 10; t | dist -----------+-----------word | 0 words | 0.4285714 two words | 0.6363636 ord | 0.71428573 (4 rows) 689 第 94 章 SYS_TRGM 这能够用 GiST 索引有效地实现，但是用 GIN 索引无法做到。当只想要少数最接近的匹配时，这通常会比第一 种形式更好。 也可以把一个 t 列上的索引用于词相似度或者严格词相似度。典型的查询是： SELECT t, word_similarity('word', t) AS sml FROM test_trgm WHERE 'word' <% t ORDER BY sml DESC, t; t | sml -----------+----word | 1 two words | 0.8 words | 0.8 (3 rows) 和 SELECT t, strict_word_similarity('word', t) AS sml FROM test_trgm WHERE 'word' <<% t ORDER BY sml DESC, t; t | sml -----------+----------word | 1 two words | 0.5714286 words | 0.5714286 (3 rows) 这将返回文本列中符合条件的所有值：这些值在其对应的有序 trigram 集中有一个连续部分与 word 的 trigram 集合足够相似，这些值会按照最好匹配到最差匹配的顺序排列。即便在非常大的数据集上，索引也将使得这一操作的 速度够快。 上述查询可能的变体有： SELECT t, 'word' <<-> t AS dist FROM test_trgm ORDER BY dist LIMIT 10; t | dist -----------+-----------word | 0 words | 0.19999999 two words | 0.19999999 ord | 0.6 (4 rows) 和 690 第 94 章 SYS_TRGM SELECT t, 'word' <<<-> t AS dist FROM test_trgm ORDER BY dist LIMIT 10; t | dist -----------+-----------word | 0 words | 0.4285714 two words | 0.4285714 ord | 0.71428573 (4 rows) 这可以用 GiST 索引很高效地实现，但是用 GIN 索引不行。 这些索引类型也支持用于 LIKE 和 ILIKE 的索引搜索，例如 该索引搜索通过从搜索字符串中抽取 trigram 并且在索引中查找它们来工作。搜索字符串中有更多 trigram，索 引搜索的效率更高。不像基于 B-树的搜索，搜索字符串不需要是左锚定的。 这些索引类型也支持用于正则表达式匹配（~ 和 ~* 操作符）的索引搜索，例如 SELECT * FROM test_trgm WHERE t ~ '(wo|rd)'; t ----------words word two words ord (4 rows) 该索引搜索通过从正则表达式中抽取 trigram 并且在索引中查找它们来工作。正则表达式中能抽取出更多 trigram，索引搜索的效率更高。不像基于 B-树的搜索，搜索字符串不需要是左锚定的。 对于 LIKE 和正则表达式搜索，记住没有可抽取 trigram 的模式将退化成一个全索引扫描。 GiST 和 GIN 索引之间的选择依赖于 GiST 和 GIN 的相对性能特性，这在其他地方讨论。 94.4.5 文本搜索集成 在与一个全文索引联合使用时，trigram 匹配是一种非常有用的工具。特别是它能有助于识别拼写错误的输入 词，这些词直接用全文搜索机制是不会被匹配的。 第一步是生成一个包含文档中所有唯一词的辅助表： CREATE TABLE words AS SELECT word FROM ts_stat('SELECT to_tsvector(''simple'', bodytext) FROM documents'); 691 第 94 章 SYS_TRGM 其中 documents 是一个具有我们希望搜索的文本域 bodytext 的表。对 to_tsvector 函数使用 simple 配置而不是 使用语言相关的配置的原因是，我们想要一个原始（没有去掉词根的）词的列表。 接下来，在词列上创建一个 trigram 索引： CREATE INDEX words_idx ON words USING GIN(word gin_trgm_ops); 现在，类似于前面例子的一个 SELECT 查询可以被用来为用户搜索术语中的拼写不当的词建议拼写。要求被选 择的词也与拼写不当的词具有相似的长度是一种有用的额外测试。 注意: 由于 words 表已经被生成为一个单独的、静态的表，它将需要被定期地重新生成，这样它能合理地与文档集 合保持一致。但是要求它完全与文档集合同步通常是不必要的。 94.5 插件 sys_trgm 卸载方法 drop extension sys_trgm; 94.6 插件 sys_trgm 升级方法 sys_trgm 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 692 第 95 章 SYS_VISIBILITY 95章 sys_visibility 第 95.1 插件 sys_visibility 简介 sys_visibility 提供了查看表的 VM 页数据和页级别可见性的函数。它还提供了用来检查 VM 页和表数据的一致 性、以及强制删除 VM 重建的函数。默认情况下，sys_truncate_visibility_map(relation regclass) 只能由超级用户执 行。其他函数可以由超级用户和 sys_stat_scan_tables 角色的成员执行。 • 插件名为 sys_visibility • 插件版本 V1.2 95.2 插件 sys_visibility 加载方式 CREATE EXTENSION sys_visibility; 95.3 插件 sys_visibility 的参数配置 无需配置任何参数。 95.4 插件 sys_visibility 的使用方法 sys_visibility 提供了以下函数： sys_visibility_map(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean) returns record 返回给定关系（relation）的给定块（blkno）在 VM 页面中的“全部可见”（all_visible）和“全部冻 结”（all_frozen）位。 693 第 95 章 SYS_VISIBILITY sys_visibility(relation regclass, blkno bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns record 返回给定关系（relation）的给定块（blkno）在 VM 页面中的“全部可见”（all_visible）和“全部冻 结”（all_frozen）位，外加块上的“全部可见”位（pd_all_visible）。 sys_visibility_map(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean) returns setof record 返回给定关系（relation）的每一个块（blkno）在 VM 页面中的“全部可见”（all_visible）和“全部冻 结”（all_frozen）位。 sys_visibility(relation regclass, blkno OUT bigint, all_visible OUT boolean, all_frozen OUT boolean, pd_all_visible OUT boolean) returns setof record 返回给定关系（relation）的每一个块（blkno）在 VM 页面中的“全部可见”（all_visible）和“全部冻 结”（all_frozen）位，外加块上的“全部可见”位（pd_all_visible）。 sys_visibility_map_summary(relation regclass, all_visible OUT bigint, all_frozen OUT bigint) returns record 返回给定关系（relation）的 VM 页面中记录的“全部可见”页面（all_visible）和“全部冻结”页面 （all_frozen）的数量。 sys_check_frozen(relation regclass, t_ctid OUT tid) returns setof tid 返 回 给 定 关 系 （relation） 中 没 有 冻 结 但 在 VM 页面中标记“全部冻结”的元组的 TID（t_ctid）。函数返回非空的结果说明 VM 页面已经损坏。 sys_check_visible(relation regclass, t_ctid OUT tid) returns setof tid 返回给定关系（relation）中没有全部可见但 在 VM 页面中标记“全部可见”的元组的 TID（t_ctid)。函数返回非空的结果说明 VM 页面已经损坏。 sys_truncate_visibility_map(relation regclass) returns void 清空给定关系（relation）的 VM 页面。如果该关系的 VM 页面可能已经损坏，函数可以用来望强制重建 VM 页面。清空后在该关系上的第一次 VACUUM 会重建 VM 页面，在此之前 VM 页面被认为存储了全 0 数据。 95.5 插件 sys_visibility 卸载方法 DROP EXTENSION sys_visibility; 95.6 插件 sys_visibility 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION sys_visibility UPDATE TO '1.1'; 694 第 96 章 SYSAUDIT 96章 sysaudit 第 96.1 插件 sysaudit 简介 sysaudit 是 KingbaseES 的一个扩展插件，主要用于支持数据库审计功能，对数据库系统中发生的动作（或事 件），将其对应的操作对象、操作时间等信息记录下来。 KingbaseES 数据库提供了一套完整的审计机制，用来保证对数据库中的各种行为进行监控，进而为数据库的安 全、可靠和有效提供有力的保障。 • 插件名为 sysaudit • 插件版本 V1.0 96.2 插件 sysaudit 加载方式 在使用 sysaudit 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'sysaudit' 96.3 插件 sysaudit 的参数配置 具体参考《KingbaseES 数据库安全指南》第 7 章数据库审计。 96.4 插件 sysaudit 使用方法 具体参考《KingbaseES 数据库安全指南》第 7 章数据库审计。 695 第 96 章 SYSAUDIT 96.5 插件 sysaudit 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 96.6 插件 sysaudit 升级方法 具体参考《KingbaseES 数据库安全指南》第 7 章数据库审计。 696 第 97 章 SYSENCRYPT 97章 sysencrypt 第 97.1 插件 sysencrypt 简介 sysencrypt 是一个 KingbaseES 的扩展，可以实现数据加解密。这种方式更为灵活，当数据库的实用场景需要数 据加解密时，加载插件即可。而不需要该功能时，卸载插件即可。 • 插件名为 sysencrypt • 插件版本 V1.0 97.2 插件 sysencrypt 加载方式 在使用 sysencrypt 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 shared_preload_libraries = 'sysencrypt' # (change requires restart) -- 创建插件 \c - system create extension sysencrypt; 97.3 插件 sysencrypt 参数配置 sysencrypt.encrypt_user_tablespace 是否默认创建表空间加密，默认值为 false 即创建表空间默认不加密。 show sysencrypt.encrypt_user_tablespace; encrypt_user_tablespace ------------------------off (1 row) 697 第 97 章 SYSENCRYPT \c - system alter system set sysencrypt.encrypt_user_tablespace to on; select sys_reload_conf(); show sysencrypt.encrypt_user_tablespace; encrypt_user_tablespace ------------------------on (1 row) 97.4 插件 sysencrypt 使用方法 具体参考《KingbaseES 数据库安全指南》章节 8.1.5.2 加密插件。 97.5 插件 sysencrypt 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 97.6 插件 sysencrypt 升级方法 sysencrypt 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 698 第 98 章 SYSMAC 98章 sysmac 第 98.1 插件 sysmac 简介 sysmac 是 KingbaseES 的一个扩展插件，主要用于支持标记和强制访问控制，保护用户数据，防止非法窃取。 强制访问控制（MAC）与 DAC 相比，MAC 提供更严格和灵活的控制方式。MAC 首先为所控制的主体和客体 指派安全标记，然后依据这些标记进行访问仲裁。并且，只有主体标记能支配客体标记时才允许主体访问。 • 插件名为 sysmac • 插件版本 V1.0 98.2 插件 sysmac 加载方式 在使用 sysmac 之前，我们需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。 示例： shared_preload_libraries = 'sysmac' 98.3 插件 sysmac 的参数配置 sysmac.enable_mac 启动强制访问控制功能的开关，取值范围为 true 或者 false ，缺省值为 false。 show sysmac.enable_mac; sysmac.enable_mac ------------------off (1 row) 699 第 98 章 SYSMAC alter system set sysmac.enable_mac = on; select sys_reload_conf(); show sysmac.enable_mac; sysmac.enable_mac ------------------on (1 row) sysmac.enable_col_mac 启用列级强制访问控制功能的开关，默认是 false，不开启。 98.4 插件 sysmac 使用方法 具体参考《KingbaseES 数据库安全指南》第 8 章标记和强制访问控制。 98.5 插件 sysmac 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 98.6 插件 sysmac 升级方法 插件 sysmac 与插件 sys_anon 的升级方式相同，具体参考《KingbaseES 数据库安全指南》第 8 章标记和强制访 问控制。 700 第 99 章 SYSPRIVILEGE 第 99.1 99章 sysprivilege 插件 sysprivilege 简介 sysprivilege 是一个 KingbaseES 的扩展，可以实现对数据库系统 ANY 权限的扩展。这种方式更为灵活，当数据 库的实用场景需要系统 ANY 权限时，加载插件即可。而不需要该功能时，卸载插件即可。 • 插件名为 sysprivilege • 插件版本 V1.0 99.2 插件 sysprivilege 加载方式 在使用 sysprivilege 插件之前，我们需要添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 kingbase 数据库。 示例： shared_preload_libraries = 'sysprivilege' 99.3 插件 sysprivilege 的参数配置 无 99.4 插件 sysprivilege 使用方法 系统 ANY 权限是属于系统级权限，目前支持的对象为四种：表，视图，序列，存储过程。ANY 权限还为每种 权限设置了 ADMIN 选项，标志是否为当前权限的 ADMIN 用户，如果是 ADMIN 用户，那么允许当前用户授权 ANY 权限给其他用户。注意:ANY 权限不可以操作数据库系统对象。 701 第 99 章 SYSPRIVILEGE 如下表所示： 表 99.4.1: ANY 权限介绍 对象类型 权限 说明 TABLE CREATE ANY TABLE 允许在所有模式下创建表 TABLE ALTER ANY TABLE 允许修改所有模式下的所有表 TABLE DROP ANY TABLE 允许删除或截断所有模式下的所有表 TABLE SELECT ANY TABLE 允许在所有模式下查询所有表 TABLE UPDATE ANY TABLE 允许在所有模式下更新所有表 TABLE INSERT ANY TABLE 允许在所有模式下的所有表中插入数据 TABLE DELETE ANY TABLE 允许在所有模式下的所有表中删除数据 VIEW CREATE ANY VIEW 允许在所有模式下创建视图 VIEW DROP ANY VIEW 允许在所有模式下删除视图 SEQUENCE CREATE SE- 允许在所有模式下创建序列 SEQUENCE ALTER ANY SEQUENCE 允许修改所有模式下的序列 SEQUENCE DROP ANY SEQUENCE 允许删除所有模式下的序列 SEQUENCE SELECT ANY SEQUENCE 允许对所有模式下的序列执行 currval，seedval，lastval 和 incre- ANY QUENCE mentval 函数 SEQUENCE UPDATE ANY SE- 允许对所有模式下的序列执行 setval 和 nextval 函数 QUENCE ANY PROCE- 允许在所有模式下创建存储过程和函数 ANY PROCE- 允许修改所有模式下的存储过程和函数 DURE DURE PROCE- DROP ANY PROCEDURE 允许删除所有模式下的存储过程和函数 PROCE- EXECUTE ANY PROCE- 允许执行所有模式下或包中存储过程和函数、引用任意包中变量 DURE DURE PROCE- CREATE DURE DURE PROCE- ALTER DURE 702 第 99 章 SYSPRIVILEGE 99.4.1 相关表和视图 • sys_sysprivilege 是一个系统表，查询出所有拥有系统 ANY 权限的用户。 • user_any_privs 是一个系统视图，用于提供权限 ID 的转换，显示为权限具体的名字。每个用户只可以查看自己的拥有的 ANY 权限。 sys_sysprivilege 视图的每个字段意义： grantee | privilege | admin_option ---------+-----------+-------------用户 OID | 权限 ID | 是否是 ADMIN 用户 user_any_privs 视图的每个字段意义： grantee | privilege | admin_option ---------+-----------+-------------用户 OID | 权限名字 99.4.2 | 是否是 ADMIN 用户 示例 create user u1; create user u2; set session authorization u1; create table testu1(id int); insert into testu1 values(123); set session authorization u2; select * from testu1; -- error set session authorization system; grant select any table to u2; set session authorization u2; select * from testu1; 99.5 插件 sysprivilege 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 示例： shared_preload_libraries = '' 703 第 99 章 SYSPRIVILEGE 99.6 插件 sysprivilege 升级方法 sysprivilege 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级这些插件。 704 第 100 章 SYSREUSE_RESIDUAL_DATA 100章 sysreuse_residual_data 第 100.1 插件 sysreuse_residual_data 简介 sysreuse_residual_data 是 KingbaseES 扩展插件，通过资源申请和释放的地方清除介质上的残留信息，以达到 客体重用的要求。 • 插件名为 sysreuse_residual_data • 插件版本 V1.0 100.2 插件 sysreuse_residual_data 加载方式 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = 'sysreuse_residual_data' 100.3 插件 sysreuse_residual_data 的参数配置 sysreuse_residual_data.enable_obj_reuse 启用客体重用功能，取值范围为 ture 或者 false，缺省为 false。 \c test system SHOW sysreuse_residual_data.enable_obj_reuse; sysreuse_residual_data.enable_obj_reuse ------------------------------false (1 row) ALTER SYSTEM SET sysreuse_residual_data.enable_obj_reuse = true; SHOW sysreuse_residual_data.enable_obj_reuse; sysreuse_residual_data.enable_obj_reuse 705 第 100 章 SYSREUSE_RESIDUAL_DATA ------------------------------true (1 row) 100.4 插件 sysreuse_residual_data 的使用方法 加载 sysreuse_residual_data 插件后，程序通过资源申请和释放的地方清除介质上的残留信息，以达到客体重用 的要求。 共享缓冲区销毁的方式：全 0 覆盖。 磁盘上文件残留信息销毁：采用置 0 方法。 示例： -- 创建插件 \c test system create extension sysreuse_residual_data; CREATE EXTENSION 100.5 插件 sysreuse_residual_data 卸载方法 修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。 shared_preload_libraries = '' 100.6 插件 sysreuse_residual_data 升级方法 sysreuse_residual_data 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插 件。 706 第 101 章 TABLEFUNC 101章 tablefunc 第 101.1 插件 tablefunc 简介 插件 tablefunc 是 KingbaseES 的一个扩展插件。tablefunc 插件提供了多个返回表 (多行) 的函数。tablefunc 插 件可作为如何编写返回多行的 C 函数的例子。 • 插件名为 tablefunc • 插件版本 V1.0 101.2 插件 tablefunc 加载方式 KingbaseES 数据库默认不加载 tablefunc 插件，用户可以使用如下命令自行人为加载。 示例： create extension tablefunc; 101.3 插件 tablefunc 的参数配置 无需配置任何参数 101.4 插件 tablefunc 的使用方法 表 tablefunc 函数列出了 tablefunc 插件提供的函数。 707 第 101 章 TABLEFUNC 函数 返回 描述 normal_rand(int numvals, float8 mean, float8 setof 产生一个正太分布的随机值集合 stddev) float8 croasstab(text sql) setof 产生一个包含多行的外加 N 个值的数据透视表，其中 record N 由调用查询中指定的行类型决定 setof ta- 产生一个包含行名称外加 N 个值的“数据透视表”， croasstabN(text sql) ble_croasstab_N croasstabl2, croasstabl3 和 croasstabl4 是预定义的， 但你可以按照下文所述创建额外的 croasstablN 函数 croasstable(text source_sql, text category_sql) setof 产生一个“数据透视表”，其值列由第二个查询指定 record setof crosstab(text) 的废弃版本。参数 N 现在被忽略，因 record 为值列的数量总是由调用查询所决定 keyid_fld, setof 产生一个层次树结构的表达 textorderby_fld record crosstab(text sql, int N) connectby(text text relname, parent_keyid_fld text [, ], text start_with, int max_depth [, text branch_delim ]) 101.5 插件 tablefunc 卸载方法 用户如想卸载 tablefunc 插件可使用如下命令。 示例： drop extension tablefunc; 101.6 插件 tablefunc 升级方法 tablefunc 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 708 第 102 章 TCN 102章 tcn 第 102.1 插件 tcn 简介 插件 tcn 是 KingbaseES 的一个扩展插件。tcn 模块提供一个触发器函数，它通知监听者有关它所附着的任意表 上的改变。它必须被用作一个行级 AFTER 触发器。 在一个 CREATE TRIGGER 语句中只可以为该函数提供一个参数，并且是可选的。如果提供该参数，它将被作 为用于通知的频道名。如果忽略它，频道名将使用 tcn。 通知的负载由表名、一个指示所执行操作类型的字母以及用于主键列的列名/值对构成。每一部分都用逗号与下 一部分隔开。为了便于解析对正则表达式的使用，表和列名总是被包裹在双引号内，并且数据值总是被包裹在单引号 内。嵌入的引号都被双写。 • 插件名为 tcn • 插件版本 V1.0 102.2 插件 tcn 加载方式 KingbaseES 数据库默认不加载 tcn 扩展插件。如果用户想使用此扩展插件功能。请参考如下示例，使用 CREATE EXTENSION 命令进行加载。 示例： CREATE EXTENSION tcn; 102.3 插件 tcn 的参数配置 无需配置任何参数。 709 第 102 章 TCN 102.4 插件 tcn 的使用方法 用户如果想使用 tcn 扩展插件，请参考如下示例。 示例： create table tcndata ( a int not null, b date not null, c text, primary key (a, b)); CREATE TABLE create trigger tcndata_tcn_trigger after insert or update or delete on tcndata for each row execute function triggered_change_notification(); CREATE TRIGGER listen tcn; LISTEN insert into tcndata values (1, date '2012-12-22', 'one'),(1, date '2012-12-23', 'another'),(2, date '201212-23', 'two'); INSERT 0 3 Asynchronous notification "tcn" with payload ""tcndata",I,"a"='1',"b"='2012-12-22'" received from server process with PID 22770. Asynchronous notification "tcn" with payload ""tcndata",I,"a"='1',"b"='2012-12-23'" received from server process with PID 22770. Asynchronous notification "tcn" with payload ""tcndata",I,"a"='2',"b"='2012-12-23'" received from server process with PID 22770. update tcndata set c = 'uno' where a = 1; UPDATE 2 Asynchronous notification "tcn" with payload ""tcndata",U,"a"='1',"b"='2012-12-22'" received from server process with PID 22770. Asynchronous notification "tcn" with payload ""tcndata",U,"a"='1',"b"='2012-12-23'" received from server process with PID 22770. delete from tcndata where a = 1 and b = date '2012-12-22'; DELETE 1 Asynchronous notification "tcn" with payload ""tcndata",D,"a"='1',"b"='2012-12-22'" received from server process with PID 22770. 102.5 插件 tcn 卸载方法 如果用户想卸载 tcn 扩展插件，请使用 DROP EXTENSION 命令进行卸载。 示例： 710 第 102 章 TCN DROP EXTENSION tcn; 102.6 插件 tcn 升级方法 tcn 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 711 第 103 章 TDS_FDW 103章 tds_fdw 第 插件 tds_fdw 简介 103.1 tds_fdw 是一个 KingbaseES 外部数据包装器，可以连接到使用表格数据流（TDS）协议的数据库，如 Sybase 数据库和 Microsoft SQL Server。 这个外部数据包装器需要一个实现 DB-Library 接口的库，比如 FreeTDS。本插件中已包含 FreeTDS-1.3。 当前版本暂不支持 JOIN 下推，以及写入操作（DML 操作）。 当 match_column_names 设为 enable 时，支持包含列名的 WHERE 条件下推。 • 插件名为 tds_fdw • 插件版本 V2.0.2 插件 tds_fdw 加载方式 103.2 CREATE EXTENSION tds_fdw; 103.3 插件 tds_fdw 的参数配置 103.3.1 外部服务器参数 外部服务器允许设置以下参数选项： • servername 必选：是 默认值：127.0.0.1 712 第 103 章 TDS_FDW 外部服务器的服务器名、地址或主机名。 可以是一个 DSN，如 freetds.conf 中所述。请参考 FreeTDS 名称查找。 可以将此选项设置为以逗号分隔的服务器名称列表，然后尝试每个服务器，直到连接成功。这种配置方法对于 自动故障切换至备用服务器非常有用。 • port 必选：否 外部服务器的端口。如果 servername 是 DSN 的话，可以在 freetds.conf 指定端口，不需要在此提供。 • database 必选：否 外部服务器将要连接到的数据库名称。 • dbuse 必选：否 默认值：0 当该选项为 0 时，tds_fdw 将直接连接到数据库。否则 tds_fdw 将连接到服务器的默认数据库，然后通过调用 DB-Li brary 中的 dbuse() 函数选择数据库。 对于 Azure，目前需要把 dbuse 选项设置为 0。 • language 必选：否 用于消息的语言设置以及日期格式的区域设置。在大多数系统中，FreeTDS 可能默认为 us_english 。也可以 在 freetds.conf 中进行修改。 • character_set 必选：否 用于连接的客户端字符集。 对于 TDS 协议版本在 7.0+ 的，连接始终使用 UCS-2，因此该参数在这些情况下不起作用。 • tds_version 必选：否 用于该外部服务器的 TDS 协议的版本。参考 FreeTDS 中 Choosing a TDS protocol version 和 History of TDS Versions 章节的说明。 • msg_handler 必选：否 默认值：blackhole 713 第 103 章 TDS_FDW 用于 TDS 消息处理程序的函数。可选值为 notice 和 blackhole。使用 notice 选项时，TDS 消息将转换为 KingbaseES 通知。使用 blackhole 选项时，TDS 消息将被忽略。 • fdw_startup_cost 必选：否 用于表示在查询计划中使用此 FDW 的开销。 • fdw_tuple_cost 必选：否 用于表示从查询计划中使用的此外部服务器获取行为的开销。 外部服务器定义过程中可接受的外部表参数： • use_remote_estimate • row_estimate_method 外部表参数 103.3.2 创建外部表允许设置以下参数选项： • query 必选：是（与 table 互斥） 用于查询外部表的查询语句。 • schema_name 必选：否 表所在的模式名。模式名也可以包含在 table_name 中，因此这里不是必须的。 • table_name 别名：table 必选：是（与 query 互斥） 要查询的外部服务器上的表。 • match_column_names 必选：否 设置是通过比较本地列和远程列的列名来进行匹配，还是直接使用它们在结果集中的排列顺序。 • use_remote_estimate 必选：否 设置通过在远程服务器上执行一些操作来估算表的大小（如 row_estimate_method 所定义）; 还是仅使用本地 估计（如 local_tuple_estimate 所定义）。 714 第 103 章 TDS_FDW • local_tuple_estimate 必选：否 当 use_remote_estimate 关闭时，使用的估计元组数的本地设置。 • row_estimate_method 必选：否 默认值：execute 可选值包含以下内容： – execute：在远程服务器上执行查询，并获取查询中的实际行数。 – showplan_all：使用 MS SQL Server 的 SET SHOWPLAN_ALL 来获取估计的行数。 外部表列参数： • column_name 必选：否 远程服务器上列的名称。如果未设置，则假定远程列名与本地列名相同。如果表的 match_column_names 设置 为 0，则将不会使用列名，此选项的设置将被忽略。 103.3.3 外部数据包装器参数 创建外部数据包装器允许设置以下参数选项： • username 必选：是 外部服务器上的用户名。 • password 必选：是 外部服务器上用户名对应的密码。 103.3.4 导入外部模式参数 导入外部模式允许设置以下参数选项： • import_default 必选：否 默认值：false 控制外部表的定义中是否包含列的默认值表达式。 715 第 103 章 TDS_FDW • import_not_null 必选：否 默认值：true 控制外部表定义中是否包含列的非空约束。 103.3.5 变量 • tds_fdw.show_before_row_memory_stats：在获取每一行之前，将内存上下文统计信息打印到 KingbaseES 日 志中。 • tds_fdw.show_after_row_memory_stats：在获取每一行之后，将内存上下文统计信息打印到 KingbaseES 日 志中。 • tds_fdw.show_finished_memory_stats：在查询完成之后，将内存上下文统计信息打印到 KingbaseES 日志 中。 103.4 插件 tds_fdw 使用方法 103.4.1 创建外部服务器 示例 CREATE SERVER mssql_svr FOREIGN DATA WRAPPER tds_fdw OPTIONS (servername '127.0.0.1', port '1433', database 'tds_fdw_test', tds_version '7.1'); 上面例子中 servername，port，database，tds_version 请根据实际环境填写 103.4.2 创建外部表 示例 使用 table_name 定义： CREATE FOREIGN TABLE mssql_table ( id integer, data varchar) SERVER mssql_svr OPTIONS (table_name 'dbo.mytable', row_estimate_method 'showplan_all'); 或者使用 schema_name 和 table_name 定义： 716 第 103 章 TDS_FDW CREATE FOREIGN TABLE mssql_table ( id integer, data varchar) SERVER mssql_svr OPTIONS (schema_name 'dbo', table_name 'mytable', row_estimate_method 'showplan_all'); 或者使用 query 定义： CREATE FOREIGN TABLE mssql_table ( id integer, data varchar) SERVER mssql_svr OPTIONS (query 'SELECT * FROM dbo.mytable', row_estimate_method 'showplan_all'); 或者设置一个远程表的列： CREATE FOREIGN TABLE mssql_table ( id integer, data varchar OPTIONS (column_name 'data')) SERVER mssql_svr OPTIONS (schema_name 'dbo', table_name 'mytable', row_estimate_method 'showplan_all'); 103.4.3 创建外部数据包装器 示例 CREATE USER MAPPING FOR system SERVER mssql_svr OPTIONS (username 'sa', password ''); 103.4.4 导入外部模式 示例 IMPORT FOREIGN SCHEMA dbo EXCEPT (mssql_table) FROM SERVER mssql_svr INTO public OPTIONS (import_default 'true'); 717 第 103 章 TDS_FDW 103.4.5 变量 设置变量 要设置变量，请使用 set 命令： SET tds_fdw.show_finished_memory_stats=1; 103.4.6 EXPLAIN EXPLAIN (VERBOSE) 将显示在远程系统上发出的查询语句。 103.4.7 关于字符集和编译的说明 1. 如果在使用 Unicode 数据时，MS SQL Server 出现如下错误： NOTICE: DB-Library notic: Msg #: 4004, Msg state: 1, Msg: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier., Server: PILLIUM\SQLEXPRESS, Process:, ERROR: DB-Library error: DB #: 4004, DB Msg: General SQL Server error: Check messages from the SQL Server 可能需要在 freetds.conf 中手动设置 tds 版本为 7.0 或更高。请参考 freetds.conf 文件和 FreeTDS 的 Choosing a TDS procotol version 章节。 尽管许多较新版本的 TDS 协议仅使用 USC-2 与服务器进行通信，FreeTDS 将 UCS-2 转换为你选择的客户 端字符集。要设置客户端字符集，可以在 freetds.conf 文件中设置 client chatset。参考 “ freetds.conf“文件和 Localization and TDS 7.0 章节。 103.4.8 加密连接 MSSQL 加密连接由 FreeTDS 处理。需要在 freetds.conf 中进行配置。可以在 freetds.conf 中搜索 encryption。 103.5 插件 tds_fdw 卸载方法 DROP EXTENSION tds_fdw; 718 第 103 章 TDS_FDW 103.6 插件 tds_fdw 升级方法 ALTER EXTENSION tds_fdw UPDATE TO new_version; 719 第 104 章 TSM_SYSTEM_ROWS 104章 tsm_system_rows 第 104.1 插件 tsm_system_rows 简介 插件 tsm_system_rows 是 KingbaseES 的一个扩展插件。提供了表采样方法 SYSTEM_ROWS，它可以用在 SELECT 命令的 TABLESAMPLE 子句中。 这种表采样方法接受一个整数参数，它是要读取的最大行数。得到的采样将总是包含正好这么多行，除非该表中 没有足够的行，在那种情况下整个表都会被选择出来。 和内建的 SYSTEM 采样方法一样，SYSTEM_ROWS 执行块级别的采样，所以采样不是完全随机的，而是服从 于聚簇效果，特别是只要求少量行时。SYSTEM_ROWS 不支持 REPEATABLE 子句。 • 插件名为 tsm_system_rows • 插件版本 V1.0 104.2 插件 tsm_system_rows 加载方式 KingbaseES 数据库默认不加载 tsm_system_rows 扩展插件，如果用户想使用 tsm_system_rows 功能，请使用 CREATE EXTENSION 命令进行加载。 示例： CREATE EXTENSION tsm_system_rows; 104.3 插件 tsm_system_rows 的参数配置 无需配置任何参数 720 第 104 章 TSM_SYSTEM_ROWS 104.4 插件 tsm_system_rows 的使用方法 KingbaseES 加载 tsm_system_rows 插件后，用户使用 tsm_system_rows 可参考如下示例. 示例： SELECT * FROM my_table TABLESAMPLE SYSTEM_ROWS(100); 这个命令从表 my_table 中返回一个 100 行的采样 (除非该表没有 100 个可见行，那时将会返回其中所有的行)。 104.5 插件 tsm_system_rows 卸载方法 如果用户不想再使用 tsm_system_rows 扩展插件的功能，可以使用 DROP EXTENSION 命令进行卸载。 示例： DROP EXTENSION tsm_system_rows; 104.6 插件 tsm_system_rows 升级方法 tsm_system_rows 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 721 第 105 章 TSM_SYSTEM_TIME 105章 tsm_system_time 第 105.1 插件 tsm_system_time 简介 插件 tsm_system_time 提供了表采样方法 SYSTEM_TIME，它可以用在 SELECT 命令的 TABLESAMPLE 子 句中。这种表采样方法接受一个浮点类型的参数，指定花在读取上的最大时间，单位毫秒。这个方法可以直接控制采 样的查询时间，但代价是采样的大小难以预测。和内建的 SYSTEM 采样方法一样，SYSTEM_TIME 执行块级别的 采样，所以采样不是完全随机的，而是服从于聚簇效果，特别是只采样少量行时。 SYSTEM_TIME 不支持 REPEATABLE 子句。 • 插件名为 tsm_system_time • 插件版本 V1.0 105.2 插件 tsm_system_time 加载方式 CREATE EXTENSION tsm_system_time; 105.3 插件 tsm_system_time 的参数配置 无需配置任何参数 105.4 插件 tsm_system_time 的使用方法 KingbaseES 加载 tsm_system_time 插件后，用户使用 tsm_system_time 可参考如下示例。 示例： 722 第 105 章 TSM_SYSTEM_TIME SELECT * FROM my_table TABLESAMPLE SYSTEM_TIME(1000); 这个命令从表 my_table 中返回 1000 毫秒内可以读取到的采样（如果表在时间内被读完将返回所有行）。 105.5 插件 tsm_system_time 卸载方法 DROP EXTENSION tsm_system_time; 105.6 插件 tsm_system_time 升级方法 通过 ALTER EXTENSION 升级插件。 示例，升级到 1.1： ALTER EXTENSION tsm_system_time UPDATE TO '1.1'; 723 第 106 章 UNACCENT 106章 unaccent 第 106.1 插件 unaccent 简介 unaccent 是一个文本搜索字典，它能从词位中移除重音（附加符号）。它是一个过滤词典，这表示它的输出总是 会被传递给下一个字典（如果有），这和字典的通常行为不同。这允许为全文搜索做与重音无关的处理。 unaccent 的当前实现不能被用作 thesaurus 字典的正规化字典。 106.2 插件 unaccent 加载方式 create extension unaccent; 106.3 插件 unaccent 的参数配置 unaccent 字典接受下列选项： * RULES 是包含翻译规则列表的文件的基本名。这个文件必须被存储在 $SHAREDIR/ tsearch_data/（这里 $SHAREDIR 表示 KingbaseES 安装的共享数据目录）中。它的名称必须以.rules（不包含在 RULES 参数中）结束。 规则文件具有下面的格式： * 每一行表示一个由带有重音的字符和不带重音的字符构成的对。第一个字符将被翻译成第二个。例如： À A Ằ A Ặ A 两个字符必须由空格分隔，并且一行上的任何前导或尾随空白都将被忽略。 * 或者，如果一行只给出一个字符，则删除该字符的实例; 这在用单独的字符表示重音的语言中是有用的。 724 第 106 章 UNACCENT * 实际上，每个“字符”可以是不包含空格的任何字符串，因此，除了去除变音符之外，unaccent 字典也可以用 于其他类型的字符串替换。 * 规则文件必须以 UTF-8 编码方式存储。加载时，数据将自动转换为当前数据库的编码。任何含有不可翻译字 符的行都将被忽略，因此规则文件可以包含当前编码中不适用的规则。在 unaccent.rules 中可以找到一个更完整的例 子，它可以直接用于大部分欧洲语言，当 unaccent 模块被安装时，它被安装在 $SHAREDIR/tsearch_data/中。 106.4 插件 unaccent 的使用方法 安装 unaccent 扩展会创建一个文本搜索模板 unaccent 和一个基于前者的字典 unaccent。unaccent 字典有默认的 参数设置 RULES=’unaccent’，这会让该字典使用标准的 unaccent.rules 文件。如果希望修改该参数，可以 alter text search dictionary unaccent (rules='my_rules'); 其中 my_rules 需要用户自行建立。 或者基于该模板创建新的字典。 要测试该字典，可以尝试如下方法： select ts_lexize('unaccent','Hộtel'); ts_lexize ----------{Hotel} (1 row) 这里是一个展示把 unaccent 字典插入到一个文本搜索配置的例子： create text search configuration fr ( copy = french ); alter text search configuration fr alter mapping for hword, hword_part, word with unaccent, french_stem; select to_tsvector('fr','Hộtels de la Mer'); to_tsvector ------------------'hotel':1 'mer':4 (1 row) select to_tsvector('fr','Hộtel de la Mer') @@ to_tsquery('fr','Hotels'); ?column? ---------t (1 row) 725 第 106 章 UNACCENT select ts_headline('fr','Hộtel de la Mer',to_tsquery('fr','Hotels')); ts_headline -----------------------Hộtel de la Mer (1 row) unaccent() 函数从一个给定的字符串中移除重音（附加符号）。基本上，它是 unaccent 字典的一个包装器，但 是它能在普通的文本搜索环境之外使用。 unaccent([dictionary regdictionary, ] string text) returns text 如果省略 dictionary 参数，则使用名为 unaccent 并且与 unaccent() 函数有相同模式的文本搜索词典。 例如： select unaccent('unaccent', 'Hộtel'); unaccent ----------Hotel (1 row) select unaccent('Hộtel'); unaccent ----------Hotel (1 row) 106.5 插件 unaccent 卸载方法 drop extension unaccent; 106.6 插件 unaccent 升级方法 unaccent 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 726 第 107 章 UTL_FILE 107章 utl_file 第 107.1 插件 utl_file 简介 插件 utl_file 补充了一些对于文件操作的函数。 • 插件名为 utl_file • 插件版本 V1.0 107.2 插件 utl_file 加载方式 在命令行执行 create extension utl_file; 示例 create extension utl_file; 107.3 插件 utl_file 的参数配置 无需配置任何参数 107.4 插件 utl_file 的使用方法 加载插件 ltree 后，按照如下方式使用相应功能 107.4.1 utl_file.fopen utl_file.fopen 打开一个文件，返回一个文件句柄 727 第 107 章 UTL_FILE 语法 fopen(location text, filename text, open_mode text, max_linesize integer, encoding name) 返回 integer fopen(location text, filename text, open_mode text, max_linesize integer) 返回 integer 参数 location：指定文件的位置。 filename：指定要打开的文件名。 open_mode：指定文件要打开的模式。 encoding：指定编码字符集。 返回值 UTL_FILE.FILE_TYPE（int 类型）。open_mode 可以是’R’,’W’,’A’。utl_file.fopen 为 procedure。 示例 DROP DIRECTORY IF EXISTS MY_DIR; CREATE DIRECTORY MY_DIR AS '/tmp/'; -- 这个目录需要存在，或者人为手工创建。 DROP PROCEDURE IF EXISTS TEST_FOPEN; \set SQLTERM / CREATE OR REPLACE PROCEDURE TEST_FOPEN( V_OUT_DATA IN VARCHAR2, V_SQLPARAM IN VARCHAR2 ) AS DECLARE OUT_DATA VARCHAR2(30000); FILE_HANDLE UTL_FILE.FILE_TYPE; FILD_NAME VARCHAR2(1000) DEFAULT 'output.txt'; BEGIN OUT_DATA := V_OUT_DATA; FILE_HANDLE := UTL_FILE.FOPEN('MY_DIR', FILD_NAME, 'A', 30000); UTL_FILE.PUT_LINE(FILE_HANDLE, OUT_DATA); UTL_FILE.PUT_LINE(FILE_HANDLE, V_SQLPARAM); UTL_FILE.FCLOSE(FILE_HANDLE); END TEST_FOPEN; / \set SQLTERM ; CALL TEST_FOPEN('111', '222'); --执行成功后可看到输入的文字。 728 第 107 章 UTL_FILE \! cat /tmp/output.txt 107.4.2 utl_file.put_line utl_file.put_line 在文件中写入一行内容 语法 put_line(file file_type, buffer text); put_line(file file_type, buffer text, autoflush bool); 参数 file：指定 UTL_FILE.FILE_TYPE 类型值。 buffer：指定目标文件名。 autoflush：指定是否自动刷新。 返回值 无返回值。 注解 utl_file.put_line 为 procedure。 示例 DROP DIRECTORY IF EXISTS MY_DIR; CREATE DIRECTORY MY_DIR AS '/tmp/'; -- 这个目录需要存在，或者人为手工创建。 DROP PROCEDURE IF EXISTS TEST_FOPEN; \set SQLTERM / CREATE OR REPLACE PROCEDURE TEST_PUT_LINE( V_OUT_DATA IN VARCHAR2, V_SQLPARAM IN VARCHAR2 ) AS DECLARE OUT_DATA VARCHAR2(30000); FILE_HANDLE UTL_FILE.FILE_TYPE; FILD_NAME VARCHAR2(1000) DEFAULT 'output.txt'; BEGIN 729 第 107 章 UTL_FILE OUT_DATA := V_OUT_DATA; FILE_HANDLE := UTL_FILE.FOPEN('MY_DIR', FILD_NAME, 'A', 30000); UTL_FILE.PUT_LINE(FILE_HANDLE, OUT_DATA); UTL_FILE.PUT_LINE(FILE_HANDLE, V_SQLPARAM); UTL_FILE.FCLOSE(FILE_HANDLE); END TEST_PUT_LINE; / \set SQLTERM ; call TEST_PUT_LINE('111', '222'); --执行成功后可看到输入的文字。 \! cat /tmp/output.txt 107.4.3 utl_file.put utl_file.put 将数据强制写入到文件中 语法 put(file file_type, buffer text); 参数 file：指定 UTL_FILE.FILE_TYPE 类型值。buffer：指定目标文件名。 返回值 无返回值 注解 utl_file.put 为 procedure。 示例 同 utl_file.putline。 107.4.4 utl_file.fclose utl_file.fclose 关闭目标文件 语法 fclose(file file_type); 730 第 107 章 UTL_FILE 参数 file 指定 UTL_FILE.FILE_TYPE 类型值。 返回值 无返回值。 返回值 utl_file.fclose 为 procedure。 示例 \set SQLTERM / CREATE or replace PROCEDURE proc1() as DECLARE dirname VARCHAR(100) DEFAULT 'my_dir'; v_empfile_src UTL_FILE.FILE_TYPE; v_empfile_tgt UTL_FILE.FILE_TYPE; v_src_file VARCHAR(20) DEFAULT 'output.txt'; v_dest_file VARCHAR(20) DEFAULT 'test.txt'; v_empline VARCHAR(200); begin v_empfile_src = UTL_FILE.FOPEN(dirname,v_src_file,'r'); v_empfile_tgt = UTL_FILE.FOPEN(dirname,v_dest_file,'w'); LOOP BEGIN UTL_FILE.GET_LINE(v_empfile_src,v_empline); UTL_FILE.PUT(v_empfile_tgt,v_empline); UTL_FILE.NEW_LINE(v_empfile_tgt); UTL_FILE.FFLUSH(v_empfile_tgt); EXCEPTION WHEN OTHERS THEN EXIT; END; END LOOP; DBMS_OUTPUT.PUT_LINE('Updated file: ' || v_dest_file); UTL_FILE.FCLOSE(v_empfile_tgt); UTL_FILE.FCLOSE(v_empfile_src); END proc1; / \set SQLTERM ; 731 第 107 章 UTL_FILE 107.4.5 utl_file.fclose_all utl_file.fclose_all 关闭所有文件 语法 utl_file.fclose_all(); 参数 无参数 返回值 无返回值。 注解 utl_file.fclose_all 为 procedure。 示例 \set SQLTERM / CREATE OR REPLACE FUNCTION read_file(dir text) RETURNS void AS $$ DECLARE f utl_file.file_type; BEGIN f := utl_file.fopen(dir, 'regress_orafce.txt', 'r'); FOR i IN 1..11 LOOP RAISE NOTICE '[%] >>%<<', i, utl_file.get_line(f); END LOOP; RAISE NOTICE '>>%<<', utl_file.get_line(f, 4); RAISE NOTICE '>>%<<', utl_file.get_line(f, 4); RAISE NOTICE '>>%<<', utl_file.get_line(f); RAISE NOTICE '>>%<<', utl_file.get_line(f); EXCEPTION -- WHEN no_data_found THEN, 8.1 plpgsql doesn't know no_data_found WHEN others THEN RAISE NOTICE 'finish % ', sqlerrm; RAISE NOTICE 'is_open = %', utl_file.is_open(f); PERFORM utl_file.fclose_all(); RAISE NOTICE 'is_open = %', utl_file.is_open(f); END; $$ LANGUAGE plpgsql; / \set SQLTERM ; 732 第 107 章 UTL_FILE 107.4.6 utl_file.get_line utl_file.get_line 返回文件的一行。 语法 get_line(file integer, OUT buffer text); get_line(file integer, OUT buffer text, len integer); 参数 file：指定 UTL_FILE.FILE_TYPE 类型值。 buffer：指定输出的文件。 len：指定想要输出的特定行。 返回值 无返回值。 注解 utl_file.get_line 为 procedure。 示例 \set SQLTERM / CREATE OR REPLACE PROCEDURE TEST_GET_LINE as vInHandle UTL_FILE.FILE_TYPE; vNewLine VARCHAR2(250); BEGIN vInHandle = utl_file.fopen('MY_DIR', 'test.txt','R'); utl_file.get_line(vInHandle, vNewLine); RAISE NOTICE '>>%<<', vNewLine; utl_file.fclose(vInHandle); END TEST_GET_LINE; / \set SQLTERM ; 107.4.7 utl_file.new_line utl_file.new_line 为文本增加行终止符。 语法 733 第 107 章 UTL_FILE new_line(file integer); new_line(file integer, lines int); 参数 file：指定 UTL_FILE.FILE_TYPE 类型值。 lines：指定需要操作的行数。 返回值 无返回值。 注解 utl_file.new_line 为 procedure。 示例 \set SQLTERM / CREATE DIRECTORY MY_DIR AS '/tmp/'; declare vInHandle utl_file.file_type; begin vInHandle := utl_file.fopen('MY_DIR', 'output.txt', 'w'); utl_file.new_line(vInHandle, 2); utl_file.fclose(vInHandle); end; / \set SQLTERM ; 107.4.8 utl_file.fflush utl_file.fflush 清空目标文件。 语法 fflush(file integer); 参数 file 指定 UTL_FILE.FILE_TYPE 类型值。 返回值 无返回值。 注解 734 第 107 章 UTL_FILE utl_file.fflush 为 procedure。 示例 \set SQLTERM / CREATE or replace PROCEDURE proc1() as DECLARE dirname VARCHAR(100) DEFAULT 'my_dir'; v_empfile_src UTL_FILE.FILE_TYPE; v_empfile_tgt UTL_FILE.FILE_TYPE; v_src_file VARCHAR(20) DEFAULT 'output.txt'; v_dest_file VARCHAR(20) DEFAULT 'test.txt'; v_empline VARCHAR(200); begin v_empfile_src = UTL_FILE.FOPEN(dirname,v_src_file,'r'); v_empfile_tgt = UTL_FILE.FOPEN(dirname,v_dest_file,'w'); LOOP BEGIN UTL_FILE.GET_LINE(v_empfile_src,v_empline); UTL_FILE.PUT(v_empfile_tgt,v_empline); UTL_FILE.NEW_LINE(v_empfile_tgt); UTL_FILE.FFLUSH(v_empfile_tgt); EXCEPTION WHEN OTHERS THEN EXIT; END; END LOOP; DBMS_OUTPUT.PUT_LINE('Updated file: ' || v_dest_file); UTL_FILE.FCLOSE(v_empfile_tgt); UTL_FILE.FCLOSE(v_empfile_src); END proc1; / \set SQLTERM ; 107.5 插件 utl_file 卸载方法 卸载时 drop extension utl_file 即可。 示例 735 第 107 章 UTL_FILE drop extension utl_file; 107.6 插件 utl_file 升级方法 utl_file 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 736 第 108 章 UUID-OSSP 108章 uuid-ossp 第 108.1 插件 uuid-ossp 简介 插件 uuid-ossp 是 uuid 生成工具。 • 插件名为 uuid-ossp • 插件版本 V1.0 108.2 插件 uuid-ossp 加载方式 使用时需要在命令行执行 create extension ”uuid-ossp”; 示例： create extension "uuid-ossp"; 108.3 插件 uuid-ossp 的参数配置 无需配置任何参数。 108.4 加载插件 插件 uuid-ossp 的使用方法 uuid-ossp 后， 用 uuid_generate_v1() 或 uuid_generate_v4() 函数生成 UUID 值。 uuid_generate_v1() 与计算机的 MAC 地址和时间戳有关。uuid_generate_v4() 生成随机的 uuid。 示例： 737 第 108 章 UUID-OSSP select uuid_generate_v1(); uuid_generate_v1 -------------------------------------c12bedf0-d7b4-11ec-8340-20040feac55c (1 行记录) select uuid_generate_v4(); uuid_generate_v4 -------------------------------------83e19b37-8195-4823-a6b7-82a1ed5cc668 (1 行记录) 108.5 插件 uuid-ossp 卸载方法 卸载时 drop extension uuid-ossp 即可。 示例： drop extension "uuid-ossp"; 108.6 插件 uuid-ossp 升级方法 uuid-ossp 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 738 第 109 章 WALMINER 109章 walminer 第 请参考 WalMiner 日志逻辑解码工具 739 第 110 章 XML2 110章 xml2 第 110.1 插件 xml2 简介 xml2 是 KingbaseES 的一个扩展插件，主要提供 XPath 查询和 XSLT 功能。 • 插件名为 xml2 • 插件版本 V1.1 在核心服务器中就已经有基于 SQL/XML 标准的 XML 相关功能，这些功能覆盖了 XML 语法检查和 XPath 查 询。xml2 同样支持这些功能，但是提供的 API 并不是完全兼容，保留 xml2 插件的目的是为了保持向后兼容。我们 已经有计划将 xml2 从 KingbaseES 一个未来版本中移除，因此我们鼓励您尝试转换您的应用。 110.2 插件 xml2 加载方式 CREATE EXTENSION xml2; 110.3 插件 xml2 的参数配置 无需配置任何参数。 110.4 插件 xml2 的使用方法 下表展示了 xml2 插件提供的函数。这些函数提供了直接的 XML 解析和 XPath 查询。所有参数都是 text 类型， 为了简洁省略了参数类型。 740 第 110 章 XML2 表 110.4.1: xml2 函数 函数 返回 描述 xml_is_well_formed(document) bool 这个函数解析其参数中的文档文本并且在该文档是一个 结构良好的 XML 时返回真。 xpath_string(document, query) text 在提供的文档上计算 XPath 查询，并且将结果造型为指 定的类型。 xpath_number(document, query) float4 在提供的文档上计算 XPath 查询，并且将结果造型为指 定的类型。 xpath_bool(document, query) bool 在提供的文档上计算 XPath 查询，并且将结果造型为指 定的类型。 xpath_nodeset(document, query, toptag, text 这个函数在文档上计算查询并且把结果包装在 XML 标 签中。如果 toptag 或者 itemtag 是一个空字符串，相关 itemtag) 的标签会被忽略。 xpath_nodeset(document, query) text 与 xpath_nodeset(document, query, toptag, itemtag) 相 似，但是结果忽略两种标签。 xpath_nodeset(document, query, itemtag) text 与 xpath_nodeset(document, query, toptag, itemtag) 相 似，但是结果忽略 toptag。 xpath_list(document, query, separator) text 这个函数返回多个值，并且用指定的分隔符分隔，例如 分隔符是”,”，结果就是 Value 1,Value 2,Value 3。 xpath_list(document, query) text 这是上面函数的一个包装器，它用”,” 作为分隔符。 110.4.1 xpath_table xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record xpath_table 是一个表函数，它在一组文档中的每一个上计算一组 XPath 查询，并且将结果作为一个表返回。来 自原始文档表的主键域被返回为结果的第一列，这样结果集可以被用于连接。 741 第 110 章 XML2 表 110.4.2: xpath_table 参数 参数 描述 key “key”字段的名称—这只是被用作输出表中第一列的字段，即它标识每个输出行是来自于哪个记录 document 包含 XML 文档的域的名称 relation 包含文档的表或视图的名称 xpaths 一个或多个 XPath 表达式，用英文竖线分隔 criteria WHERE 子句的内容，这不能被忽略，因此如果你想要处理关系中的所有行，可以使用 true 或 1=1 这些参数（除了 XPath 字符串）会被替换到一个纯粹的 SQL SELECT 语句中，因此可以是特定位置上合法的 任何内容。（注意：这种简单方法要求您验证任何用户提供的值，以避免 SQL 注入攻击） SELECT ,FROMWHERE; 该函数必须被使用在一个 FROM 表达式中，并带有一个 AS 子句来指定输出列，例如： SELECT * FROM xpath_table('article_id', 'article_xml', 'articles', '/article/author|/article/pages|/article/title', 'date_entered > ''2003-01-01'' ') AS t(article_id integer, author text, page_count integer, title text); AS 子句定义了输出表中列的名称和类型。第一个是“key”域并且剩下的对应于 XPath 查询。如果 XPath 查询 比结果列多，额外的查询将被忽略。如果结果列比 XPath 查询多，额外的列将是 NULL。 注意: 这个例子将 page_count 结果列定义为一个整数。该函数在内部处理字符串表示，因此当您想要在输出中使用 整数时，它将采用 XPath 结果的字符串表示，并使用 KingbaseES 的输入函数来把它转换成整数（或者 AS 子句要求 的任何类型）。如果无法执行此操作（例如：结果为空），则会导致错误。因此如果您认为您的数据有任何问题，您 可能希望仅将 text 作为列类型。 调用的 SELECT 语句不必只是 SELECT *，它可以按名称引用输出列或者将它们连接到其他表。该函数会产生一 个虚拟表，您可以在其上执行您想要的任何操作（例如聚集、连接、排序等）。因此我们也可以有下面的更复杂的例 子。当然，您也可以把所有这些包装在一个视图中。 SELECT t.title, p.fullname, p.email FROM xpath_table('article_id', 'article_xml', 'articles', '/article/title|/article/author/@id', 'xpath_string(article_xml,''/article/@date'') > ''2003-03-20'' ') AS t(article_id integer, title text, author_id integer), tblPeopleInfo AS p WHERE t.author_id = p.person_id; 742 第 110 章 110.4.1.1 XML2 多值结果 xpath_table 函数假定每一个 XPath 查询的结果可能是多值的，因此该函数返回的行数可能与输入文档的数目不 同。被返回的第一行包含来自每一个查询的第一个结果，第二行则是来自每一个查询的第二个结果。如果其中一个查 询的值比其他查询少，则会为它返回空值。 在某些情况下，用户将知道给定的 XPath 查询将只返回一个结果（可能是唯一文档标识符）。如果和一个返回 多值的 XPath 查询一起使用，单值结果将只出现在结果的第一行中。对于这种情况的解决方案是使用键字段作为针 对一个更简单 XPath 查询连接的一部分。一个例子： CREATE TABLE test ( id int PRIMARY KEY, xml text ); INSERT INTO test VALUES (1, '123112233'); INSERT INTO test VALUES (2, '111222333111222333'); SELECT * FROM xpath_table('id','xml','test', '/doc/@num|/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c', 'true') AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int) WHERE id = 1 ORDER BY doc_num, line_num; id | doc_num | line_num | val1 | val2 | val3 ----+---------+----------+------+------+-----1 | C1 | L1 | 1 | 2 | 3 1 | | L2 | 11 | 22 | 33 要在每一行上得到 doc_num，解决方案是使用两次 xpath_table 调用并连接结果： SELECT t.*,i.doc_num FROM xpath_table('id', 'xml', 'test', '/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c', 'true') AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int), xpath_table('id', 'xml', 'test', '/doc/@num', 'true') AS i(id int, doc_num varchar(10)) 743 第 110 章 XML2 WHERE i.id=t.id AND i.id=1 ORDER BY doc_num, line_num; id | line_num | val1 | val2 | val3 | doc_num ----+----------+------+------+------+--------1 | L1 | 1 | 2 | 3 | C1 1 | L2 | 11 | 22 | 33 | C1 (2 rows) 110.4.2 XSLT 函数 如果安装了 libxslt，那么可以使用下列函数： xslt_process(text document, text stylesheet, text paramlist) returns text 这个函数将 XSL 样式表应用于文档，并且返回转换过的结果。paramlist 是一个被用在转换中的参数赋值列表， 以 a=1,b=2 的形式指定。 注意: 参数解析是非常简单的，参数值不能包含逗号！ 还有一个双参数版本的 xslt_process，它不会向转换传递任何参数。 110.5 插件 xml2 卸载方法 DROP EXTENSION xml2; 110.6 插件 xml2 升级方法 xml2 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级该插件。 ALTER EXTENSION xml2 UPDATE TO new_version; 744 第 111 章 ZHPARSER 111章 zhparser 第 111.1 插件 zhparser 简介 zhparser 是一个 KingbaseES 的扩展，主要用于全文搜索的中文分词。zhparser 中文分词插件支持 utf8 和 gbk 字 符集。 • 插件名为 zhparser • 插件版本 V1.0 111.2 插件 zhparser 加载方式 CREATE EXTENSION zhparser; 111.3 插件 zhparser 的参数配置 zhparser.dict_in_memory 将词典全部加载到内存中，bool 类型，默认值：false zhparser.punctuation_ignore 忽略所有的标点等特殊符号，bool 类型，默认值：false zhparser.seg_with_duality 闲散文字自动以二元分词法聚合，bool 类型，默认值：false zhparser.multi_short 短词复合，bool 类型，默认值：false zhparser.multi_duality 散字二元复合，bool 类型，默认值：false zhparser.multi_zmain 重要单字复合，bool 类型，默认值：false zhparser.multi_zall 全部单字复合，bool 类型，默认值：false zhparser.extra_dicts 用户自定义词典文件列表，自定义词典文件必须放在 share/tsearch_data 目录中，示例： zhparser.extra_dicts =’dict.txt,mydict.xdb’，string 类型，默认值：无 745 第 111 章 ZHPARSER 插件 zhparser 的使用方法 111.4 CREATE EXTENSION zhparser; CREATE TEXT SEARCH CONFIGURATION testzhcfg (PARSER = zhparser); ALTER TEXT SEARCH CONFIGURATION testzhcfg ADD MAPPING FOR n,v,a,i,e,l WITH simple; SELECT * FROM ts_parse('zhparser', 'KingbaseES 中文分词插件测试'); tokid | token -------+-----------101 | KingbaseES 110 | 中文 118 | 分词 110 | 插件 118 | 测试 (5 rows) SELECT to_tsvector('testzhcfg','KingbaseES 中文分词插件测试'); to_tsvector ---------------------------------------------------'kingbasees':1 '中文':2 '分词':3 '插件':4 '测试':5 (1 row) SELECT to_tsquery('testzhcfg', '分词'); to_tsquery -----------'分词' (1 row) 中国纪年法分词检索步骤说明： 1、创建插件 zhparser CREATE EXTENSION zhparser; 2、创建配置 lunar，并在配置中建立词的映射，将想要的记号类型如 t,n,m,r,x,d,v,k,a，绑定到词典 simple 上。注意：其 中 t 为必选项，其他均为任选项。 CREATE TEXT SEARCH CONFIGURATION lunar (PARSER = zhparser); ALTER TEXT SEARCH CONFIGURATION lunar ADD MAPPING FOR n,m,r,t,x,d,v,k,a WITH simple; 部分记号类型的说明如下： tokid 记号类型 描述 97 a adjective 100 d adverb 746 第 111 章 107 k tail 109 m numral 110 n noun 114 r pronoun 116 t time 118 v verb 120 x unknown ZHPARSER 其中记号类型的 tokid 可通过 ts_parser 函数查询，如： SELECT * FROM ts_parse('zhparser', '甲'); tokid | token -------+------110 | 甲 (1 rows) 3、添加用户自定义词典文件列表，自定义词典文件必须放在$SHAREDIR/tsearch_data 目录中（其中$SHAREDIR 表示 KingbaseES 安装的共享数据目录）。 中国纪年法分词检索所需的词典文件已添加到指定路径，可直接使用该文件，选择的文件与数据库初始化时的编码一致。其中 gbk 编码的文件名为 lunar_calendar.txt，utf-8 编码的文件名为 lunar_calendar.utf8.txt。 注意：添加词典后需重启数据库才生效！ ALTER SYSTEM SET zhparser.extra_dicts='lunar_calendar.utf8.txt'; show zhparser.extra_dicts; zhparser.extra_dicts ---------------------lunar_calendar.utf8.txt (1 row) 4、测试分词检索 SELECT to_tsvector('lunar','甲子年乙丑年丙寅年丁卯年戊辰年己巳年庚午年辛未年'); to_tsvector ----------------------------------------------------------------------------------------'丁卯年':4 '丙寅年':3 '乙丑年':2 '己巳年':6 '庚午年':7 '戊辰年':5 '甲子年':1 '辛未年':8 (1 row) SELECT to_tsquery('lunar','今年是壬寅年'); to_tsquery -------------------------'今年' & '是' & '壬寅年' (1 row) 747 第 111 章 111.5 ZHPARSER 插件 zhparser 的卸载方法 drop extension zhparser; 111.6 插件 zhparser 升级方法 zhparser 扩展插件通常随着 KingbaseES 安装包一并升级。通常情况下用户无须单独升级些插件。 748 版权声明 版权声明 北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。 未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修 改、传播、翻译成其他语言、将其全部或部分用于商业用途。 免责声明 本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通 知或者提示的情况下对手册内容进行修改的权利。 本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错 误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。 技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 749 服务周期承诺 服务周期承诺 由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本 生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。 表 1: KingbaseES 产品生命周期里程碑 关键里程碑点 定义 产品发布日期 产品正式发布版本，即 GA（general availability）版本的发布日期。 停止销售日期 正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。 停止功能升级日期 在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功 能维护等服务。 停止功能维护日期 在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务 停止安全维护日期 在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。 产品服务终止日期 停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的 所有服务支持（包括服务热线和远程/现场支持）。 服务周期策略 金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。 服务终止策略 金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。 注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 750 服务周期承诺 开方式宣布产品服务终止日期。 751