KingbaseES客户端应用参考手册.pdf

KingbaseES 客户端应用参考手册金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024）发布日期：2023 年 10 月 12 日北京人大金仓信息技术股份有限公司目目录录第 1 章前言 2 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 sys_bulkload 4 2.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.4 配置文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.5 支持的数据文件格式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.6 支持的写入方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 BUFFERED 方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.7 支持的导出方式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.8 性能调优 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.8.1 服务器参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.8.2 sys_bulkload 参数配置 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 导入数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.9.1.1 以 BUFFERED 方式导入 TEXT 文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.9.1.2 导入二进制文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 导出数据 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.10 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.11 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.6.1 2.9 2.9.1 2.9.2 第 3 章 clusterdb 19 3.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 I 目录 3.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 3.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 第 4 章 createdb 23 4.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 第 5 章 createuser 27 5.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 第 6 章 dropdb 32 6.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 6.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 第 7 章 dropuser 35 7.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 7.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 7.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 II 7.8 目录参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 第 8 章 kbbadger 38 8.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 8.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.4 配置参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 8.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 8.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 8.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 8.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 第 9 章 oid2name 44 9.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 9.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 9.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 9.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 9.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 9.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 9.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 第 10 章 reindexdb 50 10.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 10.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 10.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 10.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 10.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 10.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 10.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 10.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 第 11 章 sys_basebackup 54 11.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 11.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 11.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 11.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 11.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 11.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 11.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 11.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 第 12 章 sys_config 12.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 61 III 目录 12.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 12.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 12.4 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 12.5 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 12.6 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 第 13 章 sys_dump 64 13.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 13.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 13.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 13.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 13.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 13.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 13.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 13.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 第 14 章 sys_dumpall 77 14.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 14.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 14.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 14.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 14.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 14.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 14.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 14.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 第 15 章 sys_isready 84 15.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 15.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 15.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 15.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 15.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 15.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 15.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.7.1 退出状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 15.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 第 16 章 sys_receivewal 87 16.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 16.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 16.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 16.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 16.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 IV 目录 16.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 16.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 16.7.1 退出状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 16.8 参见 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 第 17 章 sys_restore 92 17.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 17.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 17.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 17.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 17.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 17.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 第 18 章 kbbench 102 18.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 18.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 18.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 18.3.1 初始化选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 18.3.2 基准选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 18.3.3 普通选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 18.4 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 18.4.1 创建测试库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 18.4.2 初始化测试库 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 18.4.3 以 32 并发 32 线程为例，进行测试 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 18.5 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 18.5.1 在 kbbench 中实际执行的“事务”是什么？ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 18.5.2 自定义脚本 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 18.5.3 内建操作符 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 18.5.4 内建函数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 18.5.5 对每个事务做日志 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 18.5.6 聚合的日志记录 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 18.5.7 每语句延迟 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 18.5.8 良好的做法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 18.5.9 安全性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 18.5.10 退出状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 18.6 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 第 19 章 vacuumdb 119 19.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 19.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 19.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 V 目 19.4 环境变量录 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 19.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 19.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 19.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 19.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 第 20 章 vacuumlo 124 20.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 20.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 20.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 20.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 20.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 20.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 20.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 20.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 第 21 章 wrap 127 21.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 21.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 21.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 21.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 21.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 21.6 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 21.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 21.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 版权声明 130 服务周期承诺 131 VI 目录这一部分包含 KingbaseES 客户端应用和支持工具的参考信息。其他工具程序在 KingbaseES 客户端应用中列出。不是所有客户端应用都是通用的，部分应用需要特殊权限。但共同特征是，不管数据库服务器在哪里，这些应用可在任意主机上运行。当在命令行上指定用户和数据库名时，大小写会被保留、出现空格或特殊字符时需使用引号。表名和其他标识符的大小写不会被保留并且需要使用引号。 1 第 1 章前言 1 第章前言本文档描述了 KingbaseES 客户端应用和支持工具的参考信息。前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者本文档面向所有使用 KingbaseES 的用户，主要是数据库管理员 (DBAs) 和应用程序开发人员。 1.2 相关文档无。 1.3 术语术语定义聚簇为提高某个属性（或属性组）的查询速度，把这个或这些属性上具有相同值的元组集中存放在连续的物理块。集群由数据节点，管理节点，HA 组件构成的一套 7*24 小时不间断可访问数据的管理系统。 2 第 1 章前言 1.4 手册约定本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下：注意: 用于突出重要/关键信息、最佳实践等。提示: 用于突出小窍门、捷径等。警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。另请参阅: 用于突出参考、参阅等。以下程序代码书写约定适用于本文档：符号说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。 ... 表示其之前的元素可以被重复。斜体表示占位符或者需要提供特定值的变量。大写表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以小写形式输入。小写表示由用户提供的元素。 3 第2章 SYS_BULKLOAD 2 第章 sys_bulkload 2.1 简介 sys_bulkload 是 KingbaseES 提供的快速加载数据的命令行工具。用户使用 sys_bulkload 工具能够把一定格式的文本数据简单、快速的加载到 KingbaseES 数据库中，或将 KingbaseES 数据库中的数据快速导出到 CSV 文件中。使用前需要用户手动创建 sys_bulkload 插件，需要说明的是 sys_bulkload 工具是随数据库版本一同发布的，使用时请使用对应发布的数据库版本，其他数据版本则不保证能正常工作。 2.2 命令行参数 sys_bulkload [ options ][ control_file_path ] 2.3 参数说明 options 参数加载选项 -i in_file --input in_file 指定待加载文件或需要导出数据的表，同配置文件的 INPUT 选项。 -O output_table --output output_table 快速加载的目标表或者接收导出数据的文件路径，同配置文件的 OUTPUT 选项。 -l log_file --logfile log_file 结果日志路径，同配置文件中的 LOGFILE 选项。 -P bad_file --parse-badfile bad_file 记录无法正确解析或写失败的日志路径，同配置文件的 PARSE_BADFILE 选项。 4 第2章 SYS_BULKLOAD -u duplicate_badfile --duplicate-badfile duplicate_badfile 重建索引时与唯一性约束冲突而导入失败的记录的写入路径，同配置文件中的 DUPLI- CATE_BADFILE 选项。 -o optional --option optional 任何在配置文件中任何可使用的选项，参见配置文件。可以传入多次选项。对于加载的必填选项如 input, output 等，为指定参数的方便和简洁已在上面提供了单独长短项配置。连接选项 -d dbname --dbname dbname 指定连接的数据库。如未指定，数据库名将从环境变量 KINGBASE_DATABASE 中读取。如未设置该环境变量，使用连接的用户名。 -h host --host host 指定运行服务器的主机名。如果值以/开始，被用作 unix 域套接字的目录。 -p port --port port 指定 TCP 的端口号或者本地 unix 域套接字文件扩展名的服务器监听端口号。 -U username --username username 指定连接的用户名。 -W password --password password 连接用户的数据库登录密码。需要说明的是-W 后面必须指定密码, 否则会报错。一般选项 -e --echo 输出发送给服务器的命令。 -E --elevel 设置输出信息的级别，其中级别包括：DEBUG, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, and PANIC。默认为 INFO。 --help 输出帮助信息 --version 输出版本号 control_file_path 参数指定配置文件的路径。配置文件写法参见配置文件使用说明： 5 第2章 SYS_BULKLOAD 快速加载工具 sys_bulkload 可以通过短选项、长选项、配置文件三种方式来指定配置加载选项。由于加载的选项比较多，并且一些加载选项的信息比较固定和反复使用，可以把这些加载选项配置在配置文件中，直接指定配置文件的路径。配置加载选项规则如下: a. 启动参数的短选项和长选项是等价的。 b. 在启动参数选项中仍然可以指定配置文件中配置的加载选项，其作用主要是临时替换配置文件的选项，以避免去修改配置文件中的选项，配置文件和启动参数同时指定则以启动参数指定为准。 c. 如果使用启动参数则需要注意 input，output，logfile，parse_badfile，duplicate_badfile 不能多次指定，否则报错：specified only once。其他选项可以多次指定，并且以后指定的选项为准。 2.4 配置文件功能：包含了加载数据时所需要的一些配置。导入时只需要将配置文件的路径 + 文件名作为参数传入快速加载提供的系统函数或可执行程序即可。配置文件中参数选项说明：必填参数 TYPE = CSV | TEXT | BINARY | DB 加载的数据源的类型 CSV 从 CSV 格式的文本文件加载数据 TEXT 从 TEXT 格式的文本文件加载数据 BINARY 从二进制格式的文件加载数据 DB 从数据库的表中导出数据 INPUT = PATH | [schema_name.] table_name 需要导入的数据文件路径或者导出数据的源表 PATH 需要导入的数据源文件路径。如果是相对路径，在控制文件中指定时，它将与控制文件相同；当在命令行参数中指定时，相对于当前工作目录。KingbaseES 服务器的用户必须具有该文件的读取权限。在“TYPE = CSV | TEXT | BINARY”时可用。 6 第2章 SYS_BULKLOAD [schema_name.] table_name 需要导出数据的表名。仅在“TYPE = DB”时可用。 OUTPUT = [schema_name.] table_name | PATH 指定将数据导入的目标表或者目标文件。 [schema_name.] table_name 导入数据的表名。在“TYPE = CSV | TEXT | BINARY ”时可用。 PATH 导出数据的文件路径。如果是相对路径，在控制文件中指定时，它将与控制文件相同；当在命令行参数中指定时，相对于当前工作目录。KingbaseES 服务器的用户必须具有该文件的读取权限。仅在“TYPE = DB”时可用。 LOGFILE = PATH 指定一个文件记录日志。如果指定为相对路径，则指定规则与 INPUT 相同。默认值为 $KINGBASE_DATA/sys_bulkload/___

.log 非必填参数 WRITER = BUFFERED | CSV_FILE 指定数据的加载方式，默认值为 BUFFERED。 BUFFERED 通过共享缓冲区将数据加载到表中。使用共享缓冲区编写 WAL 日志，并可使用 KingbaseES 的 WAL 日志进行恢复。 CSV_FILE 当数据的加载方式指定为 CSV_FILE 时，表示将数据库中的数据导出到 CSV 格式的文本文件中，该参数一般与“TYPE = DB”配合使用。 LIMIT = n LIMIT 只在导入数据文件时有效，加载 n 行即停止加载。默认值为最大的 64 位整数（即 (2^64)/2-1 = 9223372036854775807），当 n 为 0 或默认值时表示不限制加载行数。 ENCODING = encoding 指定输入数据的编码格式，检查指定的编码格式是否合法。默认不检查。若有需要，转化输入文件的格式为数据库的编码格式。如果可以确保输入文件格式与数据库格式一致，不指定该选项，会有助于加载速度的提高，因为会忽略字符集的检查和转化。配置文件中 ENCODING 选项与数据库编码选项的转化关系详见下表。 7 第2章 SYS_BULKLOAD 表 2.4.1: 配置文件中 ENCODING 选项与数据库编码选项的转化关系配置文件中 Encoding 选项指定 SQL ASCII non-SQL ASCII 未指定既不检查也不转化既不检查也不转化 SQL_ASCII 既不检查也不转化只检查非 SQL_ASCII，与数据库一致只检查只检查非 SQL_ASCII，与数据库不一致只检查检查并转化 CHECK_CONSTRAINTS = YES | NO 指定加载时是否进行约束检查（只检查 check 约束），默认为 NO。注意: 当前不支持分区约束检查，所以直接插入分区时需要保证数据正确。 PARSE_ERRORS = n 允许出现的错误次数。若错误次数超过该设置值，则快速加载退出运行。-1 表示不限制错误个数，0 为默认值，表示不允许错误，其他表示允许的错误次数。 FILTER = [schema_name.] function_name[(arg_value，...)] 只在导入数据文件时有效，指定过滤函数用来转换输入文件的每行，如果函数名在数据库中唯一，可以忽略函数的参数类型定义。如果该选项未指定，输入数据将直接被解析到目标表中。 DUPLICATE_ERRORS = n 允许违反唯一约束的忽略的元组个数。冲突的元组将从表中删除并被记录在重复失败的文件中。如果大于等于重复记录数，记录会被回滚。默认值为 0，表示不允许重复记录数，-1 表示忽略所有错误。 BUFFERED 模式不支持该参数，指定时会被忽略。 ON_DUPLICATE_KEEP = NEW | OLD 执行元组如何处理违反唯一约束。被删除的元组会被记录在出错文件中。设置了该选项，同样需要设置 DUPLOCATE_ERRORS 大于 0。默认值为 NEW。 NEW 采用输入文件中的最新一条记录的数据替换表中原有的数据。 OLD 保持表中原有数据，删除输入文件中的元组。 PARSE_BADFILE = PATH 8 第2章 SYS_BULKLOAD 指定一个文件路径（若指定路径的文件不存在则自动创建一个新文件），默认值与 bulkload 工具同目录，文件名为导入数据文件的文件名 +”.bad”后缀的文件。保存数据文件中解析失败的数据行。若在数据文件解析的过程中解析失败，则该数据行追加记录到该文件。 DUPLICATE_BADFILE = PATH 指定一个文件路径（若指定路径的文件不存在则自动创建一个新文件），默认值与 bulkload 工具同目录，文件名为导入数据的文件名 +”.dupbad”后缀的文件。若存在不能被写入到数据库的元组，则该元组对应的数据文件中的行追加记录到该文件。例如在数据导入过程中元组违背了约束（唯一，主键，非空，check）原则，则该元组不能写入 +”.dupbad”后缀的文件路径。若在数据文件解析的过程中解析失败，则该数据行追加记录到该文件。 TRUNCATE = YES | NO 是否删除所有目标表中的数据，默认值为 NO。多进程并行和 TYPE 为 DB 时不支持该选项。 VERBOSE = YES | NO 出错的元组是否写入到服务器日志中，默认值为 NO。 DELIMITER = delimiter_character 间隔符，数据文件中列与列的间隔符，为单个字符，可以为任何可视化字符。默认值为逗号 ( , )。当需要一个 TAB 字符作为间隔符时，用双引号包裹 TAB 字符，如 DELIMITER = ”” 。 QUOTE = quote_character QUOTE 在文件格式为 CSV 时有效，详情参考 COPY 语句。默认值为双引号 ( ” )。 ESCAPE = escape_character ESCAPE 在文件格式为 CSV 时有效，详情参考 COPY 语句。默认值为反斜杠 ( \ )。 REINDEX = YES | NO 导入数据后是否重建索引。默认值为 NO。 SKIP_LAST_EMPTY_VALUE = YES | NO 只对 CSV 格式有用，最后一列数据为空，是否把它当成一列数据，还是只是当分隔符。默认值为 NO。用 TPCH 测试时生成的 CSV 文件在行末尾会加一个分隔符，指定该选项为 YES，忽略最后一个分隔符。 SKIP = n SKIP 只在导入 TEXT 和 CSV 格式的数据文件时有效，TEXT 和 CSV 格式的数据文件以行为单位进行导入，该选项可以设置跳过多少行数据，这些数据不导入数据库。默认值为 0。 NULL = null_string 指定表示一个空值的字符串。默认值是一个没有引号的空字符串。 FORCE_NOT_NULL = column_name 该选项强制要求指定的列不为 NULL 值，默认情况下将空字符串按照 NULL 值处理，如果指定了该值，则空字符串不再按照 NULL 值处理，而是按照零长字符串处理。该选项不能与 FILTER 一起使用。 9 第2章 SYS_BULKLOAD TRACKING_INTERVAL = n 指定导入过程中的时间间隔（单位为：秒），客户端反馈导入状况，防止在导入过程中因异常卡死，但用户不知道。默认为 0，表示不反馈导入信息，其它非 0 整数为反馈时间间隔。 PROCESSOR_COUNT = n 指定服务器并行处理的进程数，具体参数值可根据用户服务器的 CPU 个数指定。默认值为 1。TYPE 为 BIANRY 方式不支持该参数，TYPE 为 DB 方式时该参数恒为 1。 ASYNC_WRITE = YES | NO 指定服务器的写文件是否独立的进程，默认值为 NO。当 WRITER 为 CSV_FILE 时，如果 PROCESSOR_COUNT 大于 1，则无论是否指定 ASYNC_WRITE，其值始终为 YES。 DUMP_PARAMS = YES | NO 是否将配置参数信息导入到日志文件中。默认值为 YES。 SPECIFY_COLUMN = COLUMN NAME [FILTER | LLS],... 将数据加载到指定的列上, COLUMN NAME 为具体的列名; 列名之前使用“,”分隔, 如果列名包含逗号则需要使用单引号将列名括起来, 如果列名包含单引号则需要使用’\’ 进行转义, 例如列名为 i,’d 则写为’i, \’d’。FILTER 表示跳过对应的列, LLS 表示对应字段加载方式使用 lob location specify 方式加载。 LLS 方式，加载的内容不是文本本身所指的内容而是字段指定文件中的内容，对应的加载内容格式如下： filename:offset:length filename：为待加载的数据文件名，支持 zip 文件 offset：文件的偏移量 length：加载的数据量（字节数）注意: 如果加载的数据文件为 zip 等压缩文件，length 长度一般为整个文件大小，否则会导致加载数据不完整，导出后无法正常解压缩。另外如果加载的对象为 clob，zip 等压缩文件是含有 0 可能加载过程中会造成数据截断，所以 clob 不建议采用 zip 压缩文件进行加载。 LOB_DIR = PATH LLS 方式加载时，对应 filename 所对应文件所在的路径需要通过 LOB_DIR 指定。 CLIENT_LOB = TRUE | FALSE 远端 LLS 方式加载时，需要设置 CLIENT_LOB = TRUE，默认值为 FALSE。 SCHEMA_SAMEAS_USER = TRUE | FALSE 导入时 INPUT 参数可以指定 [schema_name.] table_name，如果对应用户只有一个与用户名相同的 SCHEMA 则可以设置 SCHEMA_SAMEAS_USER=TRUE, 这样可以不填写 schema_name，bulkload 会自动补全为 username.table_name 。这样做是为了兼容 oracle。 REMOTE_FILE = PATH 10 第2章 SYS_BULKLOAD 远端加载导入时，INPUT 填写为 stdin，待加载的数据文件可以通过 REMOTE_FILE 指定。其中配置文件中的选项不区分大小写，每个选项占用一行，选项和选项值之间通过等号进行连接，选项的值可以有引号也可以没有引号。如果字符串中有空格、等号等特殊值，则必须加引号。可以通过在正文内容前加入“#”表示注释该行后面的配置。具体格式如下： PROCESSOR_COUNT = 4 DELIMITER = "," # Delimiter QUOTE = "\"" # Quoting character LOGFILE = /home/bulkload.log DUPLICATE_BADFIL = /home/bad.dat TYPE = CSV INPUT = /home/data.csv OUTPUT = test_table 2.5 支持的数据文件格式 KingbaseES 支持 CSV、TEXT 和 BINARY 三种数据文件格式。数据文件可以通过 Copy To 语句生成，三种文件格式详见”COPY” 命令中文件格式部分。 2.6 支持的写入方式 KingbaseES 提供了 BUFFERED 方式来写入数据库文件，如果导入的目标表已建立索引，要求加载完数据后索引仍然生效。 2.6.1 BUFFERED 方式 BUFFERED 同普通 Insert 语句相比，优势在于节省了语句解析过程中带来的时间损耗。BUFFERED 方式，（与 INSERT 一样）在目标表上添加 Row Exclusive 锁，因此所有与 Row Execlusive 锁互斥的操作均会被阻塞。具体如下表（未罗列出来的 SQL 语句均可顺利执行）： 11 第2章 SYS_BULKLOAD 表 2.6.1: BUFFERED 方式下的阻塞语句不会被阻塞的 SQL 被阻塞的 SQL 被间接阻塞的 SQL （由于删除其他对象而导致表被删除或表定义被修改） DML：SELECT、UPDATE、DELETE、 ALTER TABLE、DROP TABLE、TRUN- DROP MERGE INTO、COPY FROM、COPY CATE （表所在的模 TO、VACUUM、ANALYZE、GRANT、 CREATE INDEX、DBCC CHECKDB、式）、DROP REVOKE、CREATE DBCC OWNED（表 INDEX、COM- TABLE、VACUUM FULL、 CHECKALLOCATE、DBCC SCHEMA 对 MENT ON TABLE、DBCC CHECKCAT- CHECKTABLESPACE、CREATE TRIG- 应的用户）、RE- ALOG、CREATE TABLE…INHERITS、 GER、REINDEX、ALTER ASSIGN CREATE VIEW、ALTER INDEX RE- GER、APPLY_TABLE_POLICY()、 NAME TO、ALTER REMOVE_TABLE_POLCY() INDEX SET（storag ALTER e_parameter）、 INDEX..UNUSABLE、ALTER SCHEMA、ALTER TABLESPACE、 CREATE VIEW、ALTER INDEX、 ALTER SCHEMA、CREATE ROLE、 TRIG- OWNED （表对应的用户） CREATE RULE、ALTER INDEX SET TABLESPACE、DROP INDEX、CRE- ATE INDEX、CLUSTER、LOCK ALTER ROLE、DROP ROLE、ALTER SEQUENCE、CHECKPOINT、INSERT 2.7 支持的导出方式 KingbaseES 支持将数据库的数据导出到一个 CSV 文件格式的文件中。其功能与 COPY TO 导出数据库数据到一个 CSV 格式文件相同。 2.8 性能调优使用 sys_bulkload 时，如对性能需求较高，可通过修改服务器配置（即修改 kingbase.conf），来改变服务器的资源调度，以提高 sys_bulkload 性能。但此类配置参数的修改会对服务器的相关资源调度产生影响，因此建议用户使用完成后还原成修改之前的配置。除了服务器参数，部分 sys_bulkload 的配置参数也会影响到传输速率。 2.8.1 服务器参数配置下表给出了会对 sys_bulkload 性能产生影响的服务器参数，以及它的默认值和建议修改值。在实际应用过程中，可以依据服务器的硬件环境适当调整各参数的值。 12 第2章 SYS_BULKLOAD 表 2.8.1: 修改服务器配置参数服务器配置参数默认值建议值 shared_buffers 128M 2GB work_mem 4M 100MB maintenance_work_mem 64M 1GB autovacuum on off fsync on off full_page_writes on off checkpoint_timeout 5min 1d wal_buffers -1 1GB max_wal_size 1GB 150GB track_activities on off 2.8.2 sys_bulkload 参数配置 LIMIT 在导入 CSV 文件并且已知文件行数的情况下，设置 LIMIT 参数为导入文件的行数可提升导入速度。 REINDEX 若导入数据不需要建立索引，则将 REINDEX 参数设置为 NO(默认值)，可提升导入速度。 PROCESSOR_COUNT 使用 BUFFERED 方式导入，可以根据当前物理环境合理配置 PROCESSOR_COUNT 参数优化导入速度。 2.9 示例创建导入数据表 create table test(id int primary key, info text, crt_time timestamp); 数据文件示例：将下列数据以 test.csv 为文件名保存到 KingbaseES 服务器所在目录 13 第2章 SYS_BULKLOAD 1,29b35ff06c949e7e442c929e1df86396,2017-10-08 10:52:47.746062 2,06fde814525395de5ab85f6d92b04e87,2017-10-08 10:52:47.746573 3,c93f02e8677c9cd7c906c6ad5dbd450e,2017-10-08 10:52:47.746627 4,6541700070ae3d051f965fcef43baf45,2017-10-08 10:52:47.746835 5,3d7e7246016acaa842526b6614d0edf5,2017-10-08 10:52:47.746869 6,1d1ae5a03ef0bad3bc14cd5449ba0985,2017-10-08 10:52:47.746894 7,7745c57c54b97656bec80a502ec13ec7,2017-10-08 10:52:47.746918 8,3c377131f6ef82c3284dc77a3b4ffdf7,2017-10-08 10:52:47.746942 9,5ef98d40aeeadf65eb1f0d7fd86ed585,2017-10-08 10:52:47.746968 10,312c0a0188da9e34fe45aa19d0d07427,2017-10-08 10:52:47.746993 2.9.1 导入数据 2.9.1.1 以 BUFFERED 方式导入 TEXT 文件配置文件示例（以 test.ctl 为名保存到服务器所在目录，也可自行指定其他目录。) TABLE = test INPUT = /home/kingbase/test.csv TYPE = CSV SKIP = 2 LIMIT = 5 WRITER = BUFFERED PROCESSOR_COUNT = 3 使用配置文件导入命令示例 ./sys_bulkload -h localhost -d TEST /home/kingbase/test.ctl -U SYSTEM -W 123 使用配置文件导入结果导入成功提示信息： NOTICE: BULK LOAD START NOTICE: BULK LOAD START NOTICE: BULK LOAD START NOTICE: BULK LOAD END 2 Rows skipped. 1 Rows successfully loaded. 0 Rows not loaded due to parse errors. 0 Rows not loaded due to duplicate errors. 0 Rows replaced with new rows. log path: /home/test/test.log parse error path: /home/test/test.bad 14 第2章 SYS_BULKLOAD duplicate error path: /home/test/test.dupbad ctrl file path: /home/test/test.ctl data file path: /home/test/test.csv Run began on 2021-03-27 22:53:26.933617+08 Run ended on 2021-03-27 22:53:26.934448+08 NOTICE: BULK LOAD END 4 Rows skipped. 3 Rows successfully loaded. 0 Rows not loaded due to parse errors. 0 Rows not loaded due to duplicate errors. 0 Rows replaced with new rows. log path: /home/test/test.log parse error path: /home/test/test.bad duplicate error path: /home/test/test.dupbad ctrl file path: /home/test/test.ctl data file path: /home/test/test.csv Run began on 2021-03-27 22:53:26.933694+08 Run ended on 2021-03-27 22:53:26.934543+08 NOTICE: BULK LOAD END 3 Rows skipped. 2 Rows successfully loaded. 0 Rows not loaded due to parse errors. 0 Rows not loaded due to duplicate errors. 0 Rows replaced with new rows. log path: /home/test/test.log parse error path: /home/test/test.bad duplicate error path: /home/test/test.dupbad ctrl file path: /home/test/test.ctl data file path: /home/test/test.csv Run began on 2021-03-27 22:53:26.933770+08 Run ended on 2021-03-27 22:53:26.934522+08 导入结果查询（配置指定跳过前 2 行，限制导入条数 5 条）： test=# select * from test; id | info | crt_time ----+----------------------------------+---------------------------3 | c93f02e8677c9cd7c906c6ad5dbd450e | 2017-10-08 10:52:47.746627 4 | 6541700070ae3d051f965fcef43baf45 | 2017-10-08 10:52:47.746835 5 | 3d7e7246016acaa842526b6614d0edf5 | 2017-10-08 10:52:47.746869 6 | 1d1ae5a03ef0bad3bc14cd5449ba0985 | 2017-10-08 10:52:47.746894 7 | 7745c57c54b97656bec80a502ec13ec7 | 2017-10-08 10:52:47.746918 (5 行记录) 15 第2章 2.9.1.2 SYS_BULKLOAD 导入二进制文件利用 COPY TO 将数据库表中的数据导入到一个二进制文件中作为测试数据。导入二进制文件数据命令示例 ./sys_bulkload -i /home/kingbase/test.bin -O test -o "TYPE=BINARY" -o "WRITER=BUFFERED" -h localhost -d TEST -U SYSTEM -W 123 二进制文件导入结果导入成功提示信息： NOTICE: BULK LOAD START NOTICE: BULK LOAD END 0 Rows skipped. 10 Rows successfully loaded. 0 Rows not loaded due to parse errors. 0 Rows not loaded due to duplicate errors. 0 Rows replaced with new rows. log path: /home/test/test.log parse error path: /home/test/test.bad duplicate error path: /home/test/test.dupbad ctrl file path: data file path: /home/test/test.csv Run began on 2021-03-27 22:53:26.690476+08 Run ended on 2021-03-27 22:53:27.496344+08 导入结果查询： test=# select * from test; ID | INFO | CRT_TIME ----+----------------------------------+---------------------------1 | 29b35ff06c949e7e442c929e1df86396 | 2017-10-08 10:52:47.746062 2 | 06fde814525395de5ab85f6d92b04e87 | 2017-10-08 10:52:47.746573 3 | c93f02e8677c9cd7c906c6ad5dbd450e | 2017-10-08 10:52:47.746627 4 | 6541700070ae3d051f965fcef43baf45 | 2017-10-08 10:52:47.746835 5 | 3d7e7246016acaa842526b6614d0edf5 | 2017-10-08 10:52:47.746869 6 | 1d1ae5a03ef0bad3bc14cd5449ba0985 | 2017-10-08 10:52:47.746894 7 | 7745c57c54b97656bec80a502ec13ec7 | 2017-10-08 10:52:47.746918 8 | 3c377131f6ef82c3284dc77a3b4ffdf7 | 2017-10-08 10:52:47.746942 9 | 5ef98d40aeeadf65eb1f0d7fd86ed585 | 2017-10-08 10:52:47.746968 10 | 312c0a0188da9e34fe45aa19d0d07427 | 2017-10-08 10:52:47.746993 (10 行记录) 16 第2章 2.9.2 SYS_BULKLOAD 导出数据将 text.csv 文件导入表 test 中作为测试数据。导出数据命令示例 ./sys_bulkload -d TEST -i TEST -O test_out.csv -o "TYPE=DB" -o "WRITER=CSV_FILE" -o "DELIMITER=|" -h localhost -U SYSTEM -W 123 导出数据结果导出成功提示信息： NOTICE: BULK LOAD START NOTICE: BULK LOAD END 0 Rows skipped. 10 Rows successfully loaded. 0 Rows not loaded due to parse errors. 0 Rows not loaded due to duplicate errors. 0 Rows replaced with new rows. log path: /home/test/test.log parse error path: test.bad duplicate error path: test.dupbad ctrl file path: data file path: test Run began on 2021-03-27 22:53:26.690476+08 Run ended on 2021-03-27 22:53:27.496344+08 导出结果查询： cat test_out.csv 1|29b35ff06c949e7e442c929e1df86396|2017-10-08 10:52:47.746062 2|06fde814525395de5ab85f6d92b04e87|2017-10-08 10:52:47.746573 3|c93f02e8677c9cd7c906c6ad5dbd450e|2017-10-08 10:52:47.746627 4|6541700070ae3d051f965fcef43baf45|2017-10-08 10:52:47.746835 5|3d7e7246016acaa842526b6614d0edf5|2017-10-08 10:52:47.746869 6|1d1ae5a03ef0bad3bc14cd5449ba0985|2017-10-08 10:52:47.746894 7|7745c57c54b97656bec80a502ec13ec7|2017-10-08 10:52:47.746918 8|3c377131f6ef82c3284dc77a3b4ffdf7|2017-10-08 10:52:47.746942 9|5ef98d40aeeadf65eb1f0d7fd86ed585|2017-10-08 10:52:47.746968 10|312c0a0188da9e34fe45aa19d0d07427|2017-10-08 10:52:47.746993 2.10 备注无 17 第2章 2.11 SYS_BULKLOAD 参考无 18 第 3 章 CLUSTERDB 3 第章 clusterdb 3.1 简介 clusterdb —聚簇一个 KingbaseES 数据库。 clusterdb 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。用来对一个 KingbaseES 数据库中的表进行重新聚簇。它会寻找之前已经被聚簇过的表，并且再次在最后使用过的同一个索引上对这些表重新聚簇。没有被聚簇过的表将不会受影响。 clusterdb 是 SQL CLUSTER 命令的一个包装器。通过这个工具和其他方法访问服务器来聚簇数据库之间没有实质性的区别。 3.2 命令行参数 clusterdb [ connection-option ...] [ --verbose | -v ] [ --table | -t table ] ... [ dbname ] clusterdb [ connection-option ...] [ --verbose | -v ] --all | -a 3.3 参数说明 clusterdb 接受下列命令行参数： -a --all 聚簇所有数据库。 [-d] dbname [--dbname=]dbname 指定要被聚簇的数据库名称。如果这个参数没有被指定并且-a（或--all）没有被使用，数据库名将从环境变量 KINGBASE_DATABASE 中读出。如果该环境变量也没有被设置，指定给该连接的用户名将被用作数据库名。 -e --echo 19 第 3 章 CLUSTERDB 回显 clusterdb 生成并发送给服务器的命令。 -q --quiet 不显示进度消息。 -t table --table=table 只聚簇 “table“。可以通过写多个-t 开关来聚簇多个表。 -v --verbose 在处理期间打印详细信息。 -V --version 打印 clusterdb 版本并退出。 -? --help 显示关于 clusterdb 命令行参数的帮助并退出。 -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 要使用哪个用户来连接数据库。 -w --no-password 从不发出一个输入密码提示。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接尝试将会失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 强制 clusterdb 在连接到一个数据库之前提示要求输入一个密码。这个选项不是必不可少的，因为如果服务器要求密码认证，clusterdb 将自动提示要求输入一个密码。但是，clusterdb 将浪费一次连接尝试来发现服务器想要一个密码。在某些情况下值得用-W 来避免额外的连接尝试。 --maintenance-db=dbname 指定要连接到用来发现那些其它数据库应该被集簇的数据库的名字。如果没有指定，将使用 kingbase 数据库。而如果它也不存在，将使用 template1。 20 第 3 章 CLUSTERDB 3.4 环境变量 clusterdb 在使用时，如果用户没有指定相关参数，clusterdb 会使用以下环境变量信息。命令行参数优先高于环境变量。 KINGBASE_DATABASE 指定连接的数据库名，默认和用户名相同。 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KCIUSER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 3.5 错误信息诊断在有错误发生时，可以在 CLUSTER 和 ksql 中找潜在问题和错误消息的提示信息。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 3.6 示例要聚簇数据库 test： $ clusterdb test 要聚簇在数据库 xyzzy 中的一个表 foo： $ clusterdb --table=foo xyzzy 3.7 备注无 21 第 3 章 CLUSTERDB 3.8 参考 CLUSTER 22 第4章 4 第章 4.1 CREATEDB createdb 简介 createdb 创建一个新的 KingbaseES 数据库。 createdb 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。通常，执行这个命令的数据库用户将成为新数据库的所有者。但是，如果执行用户具有合适的权限，可以通过-O 选项指定一个不同的所有者。 createdb 是 SQL 命令 CREATE DATABASE 的一个包装器。在通过这个工具和其他方法访问服务器来创建数据库之间没有实质性的区别。 4.2 命令行参数 createdb [ connection-option ...] [ option ...] [ dbname [ description ]] 4.3 参数说明 createdb 接受下列命令行参数： dbname 指定要被创建的数据库名。该名称必须在这个集簇中所有 KingbaseES 数据库名中唯一，默认是创建一个与当前系统用户同名的数据库。 description 指定与新创建的数据库相关联的一段注释信息。 -D tablespace --tablespace=tablespace 指定该数据库使用的默认表空间（这个名称被当做一个双引号引用的标识符处理）。 -e --echo 23 第4章 CREATEDB 回显 createdb 生成并发送到服务器的命令信息。 -E encoding --encoding=encoding 指定要在这个数据库中使用的字符编码模式。KingbaseES 服务器支持的字符集在字符集支持中描述。 -l locale --locale=locale 指定要在这个数据库中使用的区域。这等效于同时指定--lc-collate 和--lc-ctype。 --lc-collate=locale 指定要在这个数据库中使用的 LC_COLLATE 设置。 --lc-ctype=locale 指定要在这个数据库中使用的 LC_CTYPE 设置。 -O owner --owner=owner 指定拥有这个新数据库的数据库用户（这个名称被当做一个双引号引用的标识符处理）。 -T template --template=template 指定用于创建这个数据库的模板数据库（这个名称被当做一个双引号引用的标识符处理）。 -V --version 打印 createdb 版本并退出。 -? --help 显示关于 createdb 命令参数的帮助信息并退出。选项-D、-l、-E、-O 和 -T 对应于底层 SQL 命令 CREATE DATABASE 的选项，关于这些选项的信息可见该命令的内容。 createdb 也接受下列命令行参数用于连接参数： -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 要使用哪个用户连接到数据库。 -w --no-password 从不发出一个输入密码提示。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接尝试将会失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 24 第4章 CREATEDB 强制 createdb 在连接到一个数据库之前提示要求输入一个密码。这个选项不是必不可少的，因为如果服务器要求密码认证，createdb 将自动提示要求输入一个密码。但是，createdb 将浪费一次连接尝试来发现服务器想要一个密码。在某些情况下值得用-W 来避免额外的连接尝试。 --maintenance-db=dbname 指定要连接到用来发现那些其它数据库应该被集簇的数据库的名字。如果没有指定，将使用 kingbase 数据库。而如果它也不存在，将使用 template1。 4.4 环境变量 KINGBASE_DATABASE 如果被设置，就是要创建的数据库名，默认和用户名相同，除非在命令行中覆盖。 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KCIUSER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci。 4.5 错误信息诊断在有错误发生时，可以在 CREATE DATABASE 和 ksql 中找潜在问题和错误消息的提示信息。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 4.6 示例要使用默认数据库服务器创建数据库 demo： $ createdb demo 25 第4章 CREATEDB 要在主机 eden、端口 5000 上使用 template0 模板数据库创建数据库 demo，这里是命令行命令和底层 SQL 命令： $ createdb -p 5000 -h eden -T template0 -e demo CREATE DATABASE demo TEMPLATE template0; 4.7 备注无 4.8 参考 dropdb , CREATE DATABASE 26 第 5 章 CREATEUSER 5 第章 createuser 5.1 简介 createuser —定义一个新的 KingbaseES 用户账户。 createuser 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。用来创建一个新的 KingbaseES 用户（或者更准确些，是一个角色）。只有超级用户和具有 CREATEROLE 特权的用户才能创建新用户，因此 createuser 必须被以上两种用户调用。如果你希望创建一个新的超级用户，你必须作为一个超级用户连接，而不仅仅是具有 CREATEROLE 特权。作为一个超级用户意味着绕过数据库中所有访问权限检查的能力，因此超级用户地位不能轻易被授予。 5.2 命令行参数 createuser [ connection-option ...] [ option ...] [ username ] 5.3 参数说明 createuser 接受下列命令行参数： username 指定要被创建的 KingbaseES 用户的名称。这个名称必须与这个 KingbaseES 安装中所有现存角色名字不同。 -c number --connection-limit=number 为该新用户设置一个最大连接数。默认值为不设任何限制。 -d --createdb 新用户将被允许创建新数据库。 -D --no-createdb 27 第 5 章 CREATEUSER 新用户将不被允许创建新数据库。这是默认值。 -e --echo 回显 createuser 生成并发送给服务器的命令信息。 -E --encrypted 此选项已过时，但为了实现向后兼容仍然接受。 -g role --role=role 指定一个角色，这个角色将立即加入其中成为其成员。如果要把这个角色加入到多个角色中作为成员，可以写多个-g 开关。 -i --inherit 新角色将自动继承把他作为成员的角色的特权。这是默认值。 -I --no-inherit 新角色将不会自动继承把他作为成员的角色的特权。 --interactive 如果在命令行没有指定用户名，提示要求用户名，并且在命令行没有指定选项 -d/-D、-r/-R、-s/-S 时也提示（一直到 KingbaseES V8R3 这都是默认行为）。 -l --login 新用户将被允许登入（即，该用户名能被用作初始会话用户标识符）。这是默认值。 -L --no-login 新用户将不被允许登入（一个没有登录特权的角色仍然可以作为管理数据库权限的方式而存在）。 account unlock 如果给定，account unlock 将解锁用户，并且允许用户登录，这是默认值。不可以和-l,--login 同时使用。 account lock 如果给定，account lock 将锁定用户，并且不允许以该用户登录。不可以和-L,--no-login 同时使用。 -P --pwprompt 如果给定，createuser 将发出一个提示要求新用户的口令。如果你没有计划使用口令认证，这就不是必须的。 -r --createrole 新用户将被允许创建新的角色（即，这个用户将具有 CREATEROLE 特权）。 -R --no-createrole 新用户将不被允许创建新角色。这是默认值。 -s --superuser 28 第 5 章 CREATEUSER 新用户将成为一个超级用户。 -S --no-superuser 新用户将不会成为一个超级用户。这是默认值。 -V --version 打印 createuser 版本并退出。 --replication 新用户将具有 REPLICATION 特权，这在 CREATE ROLE 的文档中有更完整的描述。 --no-replication 新用户将不具有 REPLICATION 特权，这在 CREATE ROLE 的文档中有更完整的描述。 -? --help 显示有关 createuser 命令行参数的帮助并退出。 createuser 也接受下列命令行参数作为连接参数： -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 要使用哪个用户来连接数据库。（不是要创建的用户名）。 -w --no-password 从不发出一个输入密码提示。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接尝试将会失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 强制 createuser 在连接到一个数据库之前提示要求输入一个密码。这个选项不是必不可少的，因为如果服务器要求密码认证，createuser 将自动提示要求输入一个密码。但是，createuser 将浪费一次连接尝试来发现服务器想要一个密码。在某些情况下值得用-W 来避免额外的连接尝试。 5.4 环境变量 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 29 第 5 章 CREATEUSER KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KCIUSER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 5.5 错误信息诊断在有错误发生时，可以在 CREATE ROLE 和 ksql 中找潜在问题和错误消息的提示信息。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 5.6 示例要在默认数据库服务器上创建一个用户 joe： $ createuser joe 要在默认数据库服务器上创建一个用户 joe 并提示要求一些额外属性： $ createuser --interactive joe Shall the new role be a superuser? (y/n) n Shall the new role be allowed to create databases? (y/n) n Shall the new role be allowed to create more new roles? (y/n) n 要使用在主机 eden、端口 5000 上的服务器创建同一个用户 joe，并带有显式指定的属性，看看下面的命令： $ createuser -h eden -p 5000 -S -D -R -e joe CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN; 要创建用户 joe 为一个超级用户并且立刻分配一个口令： $ createuser -P -s -e joe Enter password for new role: xyzzy Enter it again: xyzzy CREATE ROLE joe PASSWORD 'md5b5f5ba1a423792b526f799ae4eb3d59e' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN; 30 第 5 章 CREATEUSER 在上面的例子中，在录入新口令时新口令并没有真正的被回显，但是为了清晰，我们特意把它列了出来。如你所见，该口令在被发送给客户端之前会被加密。 5.7 备注无 5.8 参考 dropuser , CREATE ROLE 31 第 6 章 DROPDB 6 第章 dropdb 6.1 简介 dropdb —移除一个 KingbaseES 数据库。 dropdb 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。用来删除一个现有的 KingbaseES 数据库。执行这个命令的用户必须是一个数据库超级用户或是该数据库的拥有者。 dropdb 是 SQL 命令 DROP DATABASE 的一个包装器。在通过这个工具和其他方法访问服务器来删除数据库之间没有实质性的区别。 6.2 命令行参数 dropdb [ connection-option ...] [ option ...] dbname 6.3 参数说明 dropdb 接受下列命令行参数： dbname 指定要被删除的数据库的名字。 -e --echo 回显 dropdb 生成并发送给服务器的命令信息。 -i --interactive 在做任何破坏性的工作之前发出一个验证提示。 -V --version 打印 dropdb 的版本信息并退出。 32 第 6 章 DROPDB --if-exists 如果指定的数据库不存在也不抛出一个错误。在这种情况下会发出一个提醒。 -? --help 显示有关 dropdb 命令的帮助信息并退出。 dropdb 也接受下列命令行参数作为连接参数： -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 要使用哪个用户来连接数据库。 -w --no-password 从不发出一个输入密码提示。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接尝试将会失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 强制 dropdb 在连接到一个数据库之前提示要求输入一个密码。这个选项不是必不可少的，因为如果服务器要求密码认证，dropdb 将自动提示要求输入一个密码。但是，dropdb 将浪费一次连接尝试来发现服务器想要一个密码。在某些情况下值得用-W 来避免额外的连接尝试。 --maintenance-db=dbname 指定要连接到用来发现那些其它数据库应该被集簇的数据库的名字。如果没有指定，将使用 kingbase 数据库。而如果它也不存在，将使用 template1。 6.4 环境变量 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KCIUSER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 33 第 6 章 DROPDB SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 6.5 错误信息诊断在有错误发生时，可以在 DROP DATABASE 和 ksql 中找潜在问题和错误消息的提示信息。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 6.6 示例要在默认数据库服务器上毁掉数据库 demo： $ dropdb demo 要使用在主机 eden、端口 5000 上的服务器中毁掉数据库 demo，并带有验证和回显，看看下面的命令： $ dropdb -p 5000 -h eden -i -e demo Database "demo" will be permanently deleted. Are you sure? (y/n) y DROP DATABASE demo; 6.7 备注无 6.8 参考 createdb , DROP DATABASE 34 第7章 DROPUSER 7 第章 dropuser 7.1 简介 dropuser —删除一个 KingbaseES 用户账户。 dropuser 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。用来删除一个已有的 KingbaseES 用户。只有超级用户以及具有 CREATEROLE 特权的用户能够移除 KingbaseES 用户（要移除一个超级用户，你必须自己是一个超级用户）。 dropuser 是 SQL 命令 DROP ROLE 的一个包装器。在通过这个工具和其他方法访问服务器来删除用户之间没有实质性的区别。 7.2 命令行参数 dropuser [ connection-option ...] [ option ...] [ username ] 7.3 参数说明 dropuser 接受下列命令行参数： username 指定要删除的 KingbaseES 用户的名字。如果没有在命令行指定并且使用了-i/--interactive 选项，你将被提醒要求输入一个用户名。 -e --echo 回显 dropuser 生成并发送给服务器的命令信息。 -i --interactive 在实际删除该用户之前提示要求确认，并且在没有在命令行指定用户名提示要求输入一个用户名。 35 第7章 DROPUSER -V --version 打印 dropuser 版本信息并退出。 --if-exists 如果用户不存在时不要抛出一个错误。在这种情况下将发出一个提示。 -? --help 显示有关 dropuser 命令的帮助并退出。 dropuser 也接受下列命令行参数作为连接参数： -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 要使用哪个用户来连接数据库（不是要移除的用户名）。 -w --no-password 从不发出一个输入密码提示。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接尝试将会失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 强制 dropuser 在连接到一个数据库之前提示要求输入一个密码。这个选项不是必不可少的，因为如果服务器要求密码认证，dropuser 将自动提示要求输入一个密码。但是，dropuser 将浪费一次连接尝试来发现服务器想要一个密码。在某些情况下值得用-W 来避免额外的连接尝试。 7.4 环境变量 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KCIUSER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 SYS_COLOR 36 第7章 DROPUSER 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 7.5 错误信息诊断在有错误发生时，可以在 DROP ROLE 和 ksql 中找潜在问题和错误消息的提示信息。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 7.6 示例要从默认数据库服务器删除用户 joe： $ dropuser joe 要使用在主机 eden、端口 5000 上的服务器删除用户 joe，并带有验证和回显，可使用下面的命令： $ dropuser -p 5000 -h eden -i -e joe Role "joe" will be permanently removed. Are you sure? (y/n) y DROP ROLE joe; 7.7 备注无 7.8 参考 createuser , DROP ROLE 37 第 8 章 KBBADGER 8 第章 8.1 kbbadger 简介 kbbadger 是一个命令行工具，可以分析大型的日志文件。当日志文件足够长时，kbbadger 可以自动检测日志文件的格式（syslog，stderr，csvlog 或 jsonlog）。 kbbadger 生成的所有图表都是可缩放的并且可单独下载为 PNG 文件。另外，在生成的报告中 SQL 查询将突出显示。 kbbadger 生成的报告中包含的关于 SQL 查询的信息有： • 总体统计 • 占用时间最多的查询 • 最常见的查询 • 最常见的错误 • 查询时间直方图 • 会话时间直方图 • 参与顶级查询的用户 • 涉及顶级查询的应用程序 • 生成最多取消的查询 • 大多数查询已取消 • 最耗时的准备/绑定查询报告也会提供每小时的统计图表，其内容包括： • SQL 查询统计信息 • 临时文件统计 • 检查点统计 • 自动 vacuum 和自动分析统计 38 第 8 章 KBBADGER • 已取消查询 • 错误事件（死机、致命、错误和警告） • 错误的类分布 8.2 命令行参数 kbbadger [ options ...] logfile ... 8.3 参数说明 kbbadger 接受下列命令行参数： -e --end datetime 通过日志解析数据的结束时间。 -b --begin datetime 通过日志解析数据的开始时间。 -p --prefix string 标注在 Kingbase.conf 文件中使用的自定义项 log_line_prefix 的值，之后将给出使用案例。 -J --Jobs number 指定并行解析的日志文件的数量，默认为 1，即单线解析。 -j --jobs number 指定同时运行的工作数量，默认为 1，即单线工作。 “ “ --exclude-query regex 将与’regex’ 匹配的查询排除在报告之外，例如”^(VACUUM“COMMIT)”，并且你可以多次使用此参数。 -f --format logtype 指定日志的文件格式。例如 syslog, syslog2, stderr, csv 和 bouncer，当不使用 kbLogAnalyse 时可以使用 stderr 自动识别。 8.4 配置参数必须在 kingbase.conf 中启用并设置一些配置指令 39 第 8 章 KBBADGER # 您必须首先启用 SQL 查询日志记录才能进行解析 log_min_duration_statement = 0 # 用于 syslog 日志文件格式 log_line_prefix = 'user=%u,db=%d,app=%a,client=%h ' # stderr 输出的日志行前缀也可以是 log_line_prefix = '%t [%p]: db=%d,user=%u,app=%a,client=%h ' # 或用于 syslog 输出 log_line_prefix = 'db=%d,user=%u,app=%a,client=%h ' # 您也可以在 kingbase.conf 中启用其他参数，以从日志文件中获取更多信息 log_checkpoints = on log_connections = on log_disconnections = on log_lock_waits = on log_temp_files = 0 log_autovacuum_min_duration = 0 log_error_verbosity = default 注意: 数据库日志中的内容必须为英文，否则 kbbadger 可能无法解析日志中的内容： lc_messages='en_US.UTF-8' 注意: 不要启用 log_statement，因为 kbBadger 不会解析它的日志格式并且如果您将 log_statement 设置为’all’，则不会通过 log_min_duration_statement 指令记录任何内容。 log_statement='none' 8.5 错误信息诊断无 8.6 示例要通过所有 2019-10-26 15:44 的日志生成报告。 40 第 8 章 KBBADGER $ kbbadger ./ sys_log/kingbase-2019-10-26_1544* -f stderr -J 12 -j 32 [========================>] Parsed 283210387 bytes of 283210387 (100.00%), queries: 327810, events: 51 LOG: Ok, generating html report... 最终会生成 html 文件生成的统计信息效果图如下： 41 第 8 章 KBBADGER 其他情况下实例 $ kbbadger /var/log/kingbase.log $ kbbadger /var/log/kingbase.log.2.gz /var/log/kingbase.log.1.gz /var/log/kingbase.log $ kbbadger /var/log/kingbase/kingbase-2012-05-* $ kbbadger --exclude-query="^(COPY|COMMIT)" /var/log/kingbase.log $ kbbadger -b "2012-06-25 10:56:11" -e "2012-06-25 10:59:11" /var/log/kingbase.log $ cat /var/log/kingbase.log | kbbadger $ kbbadger --prefix '%t [%p]: user=%u,db=%d,client=%h' /sys_log/kingbase-2012-08-21* $ kbbadger --prefix '%m %u@%d %p %r %a : ' /sys_log/kingbase.log # Log line prefix with syslog log output $ kbbadger --prefix 'user=%u,db=%d,client=%h,appname=%a' /sys_log/kingbase-2012-08-21* # Use my 8 CPUs to parse my 10GB file faster, much faster $ kbbadger -j 8 /sys_log/kingbase-10.1-main.log 8.7 备注无 42 第 8 章 KBBADGER 8.8 参考无 43 第 9 章 OID2NAME 9 第章 9.1 oid2name 简介 oid2name —解析一个 KingbaseES 数据目录中的 OID 和文件结点。 oid2name 是一个帮助管理员检查 KingbaseES 文件结构的工具程序。使用该工具，需要熟悉数据库文件结构。 9.2 命令行参数 oid2name [ option ...] 9.3 参数说明 oid2name 接受下列命令行参数： -f filenode --filenode=filenode 显示文件结点 “filenode“对应的表的信息 -i --indexes 在列举中包括索引和序列 -o oid --oid=oid 显示 OID “oid“对应的表的信息 -q --quiet 忽略头部（用于脚本） -s --tablespaces 显示表空间 OID 44 第 9 章 OID2NAME -S --system-objects 包括系统对象（位于 “information_schema“、sys_toast 和 sys_catalog 模式中） -t tablename_pattern --table=tablename_pattern 显示匹配 “tablename_pattern“的表的信息 -V --version 打印 oid2name 版本并退出。 -x --extended 为要显示的每个对象显示更多信息：表空间名、模式名以及 OID -? --help 显示有关 oid2name 命令行参数的帮助并退出。 -d database --dbname=database 要连接的数据库 -h host --host=host 数据库服务器的主机 -p port --port=port 数据库服务器的端口 -U username --username=username 指定连接的用户名要显示特定表，通过使用-o、-f 和-t 选择要显示哪个表。-o 采用一个 OID，-f 采用一个文件节点，而-t 采用一个表名（实际上，它是一个 LIKE 模式，因此你可以用诸如 foo% 之类的东西）。这些选项你想用多少就用多少，最后的列举将包括匹配任意一个选项的所有对象。但是注意这些选项只能显示由-d 给定的数据库中的对象。如果你没有给出任何-o、-f 或者-t，但是给出了-d，它将列出由-d 指定的数据库中的所有表。在这种模式下， -S 和-i 选项控制什么会被列出。如果你也没有给出-d，它将显示一个数据库 OID 的列表。你也可以给出-s 来得到一个表空间列表。 9.4 环境变量 KINGBASE_HOST KINGBASE_PORT KCIUSER 默认的连接参数。 45 第 9 章 OID2NAME 错误信息诊断 9.5 oid2name 要求一个运行着的数据库服务器并且其系统目录没有损坏。因此它对于数据库损坏的情况用处有限。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。示例 9.6 $ # 在这个数据库服务器中到底有什么？ $ oid2name All databases: Oid Database Name Tablespace ---------------------------------17228 alvherre sys_default 17255 regression sys_default 17227 template0 sys_default 1 template1 sys_default $ oid2name -s All tablespaces: Oid Tablespace Name ------------------------1663 sys_default 1664 sys_global 155151 fastdisk 155152 bigdisk $ # OK，让我们看看数据库 alvherre 里面 $ cd $KINGBASE_DATA/base/17228 $ # 得到默认表空间中前十个数据库对象，按尺寸排序 $ ls -lS * | head -10 -rw------- 1 alvherre alvherre 136536064 sep 14 09:51 155173 -rw------- 1 alvherre alvherre 17965056 sep 14 09:51 1155291 -rw------- 1 alvherre alvherre 1204224 sep 14 09:51 16717 -rw------- 1 alvherre alvherre 581632 sep -rw------- 1 alvherre alvherre 237568 sep 14 09:50 16674 -rw------- 1 alvherre alvherre 212992 sep 14 09:51 1249 -rw------- 1 alvherre alvherre 204800 sep 14 09:51 16684 -rw------- 1 alvherre alvherre 196608 sep 14 09:50 16700 -rw------- 1 alvherre alvherre 163840 sep 14 09:50 16699 -rw------- 1 alvherre alvherre 122880 sep 6 17:51 1255 6 17:51 16751 46 第 9 章 OID2NAME $ # 我好奇文件 155173 是 ... $ oid2name -d alvherre -f 155173 From database "alvherre": Filenode Table Name ---------------------155173 accounts $ # 你可以请求多于一个对象 $ oid2name -d alvherre -f 155173 -f 1155291 From database "alvherre": Filenode Table Name ------------------------155173 accounts 1155291 accounts_pkey $ # 你可以混合选项，并且用 -x 得到更多细节 $ oid2name -d alvherre -t accounts -f 1155291 -x From database "alvherre": Filenode Table Name Oid Schema Tablespace -----------------------------------------------------155173 accounts 155173 public sys_default 1155291 accounts_pkey 1155291 public sys_default $ # 为每个数据库对象显示磁盘空间 $ du [0-9]* | > while read SIZE FILENODE > do > echo "$SIZE `oid2name -q -d alvherre -i -f $FILENODE`" > done 16 1155287 branches_pkey 16 1155289 tellers_pkey 17561 1155291 accounts_pkey ... $ # 相同，但是按尺寸排序 $ du [0-9]* | sort -rn | while read SIZE FN > do > echo "$SIZE `oid2name -q -d alvherre -f $FN`" > done 133466 155173 accounts 17561 1155291 accounts_pkey 1177 16717 sys_proc_proname_args_nsp_index 47 第 9 章 OID2NAME ... $ # 如果你想看看表空间里有什么，使用 sys_tblspc 目录 $ cd $KINGBASE_DATA/sys_tblspc $ oid2name -s All tablespaces: Oid Tablespace Name ------------------------1663 sys_default 1664 sys_global 155151 fastdisk 155152 bigdisk $ # 哪些数据库在表空间 "fastdisk" 中有对象？ $ ls -d 155151/* 155151/17228/ 155151/SYS_VERSION $ # 噢，什么是数据库 17228 ？ $ oid2name All databases: Oid Database Name Tablespace ---------------------------------17228 alvherre sys_default 17255 regression sys_default 17227 template0 sys_default 1 template1 sys_default $ # 让我们看这个数据库在该表空间中有哪些对象。 $ cd 155151/17228 $ ls -l total 0 -rw------- 1 kingbase kingbase 0 sep 13 23:20 155156 $ # OK，这是个很小的表，但是哪一个是它？ $ oid2name -d alvherre -f 155156 From database "alvherre": Filenode Table Name ---------------------155156 foo 48 第 9 章 OID2NAME 9.7 备注名称“oid2name”是有历史原因的，它确实有些误导性，因为在你使用它的大部分时间里，你实际关心的是表的文件结点编号（在数据目录中是可见的文件名）。请确定你理解表 OID 和表文件结点之间的区别！ oid2name 连接到一个目标数据库并且抽取 OID、文件节点或者表名信息。你也可以让它显示数据库 OID 或表空间 OID。 9.8 参考无 49 第 10 章第 10.1 REINDEXDB 10章 reindexdb 简介 reindexdb —重建一个 KingbaseES 数据库索引。 reindexdb 是用于重建一个 KingbaseES 数据库中索引的工具。 reindexdb 是 SQL 命令 REINDEX 的一个包装器。在通过这个工具和其他方法访问服务器来重索引数据库之间没有实质性的区别。 10.2 命令行参数 reindexdb [ connection-option ...] [ option ...] [ --schema | -S schema ] ... [ --table | -t table ] ... [ --index | -i index ] ... [ dbname ] reindexdb [ connection-option ...] [ option ...] --all | -a reindexdb [ connection-option ...] [ option ...] --system | -s [ dbname ] 10.3 参数说明 reindexdb 接受下列命令行参数： -a --all 重建所有数据库索引。 --concurrently 使用 CONCURRENTLY 选项。更多信息参考 REINDEX 。 [-d] dbname [--dbname=]dbname 50 第 10 章 REINDEXDB 指定重建索引的数据库名。如果没有指定该参数并且没有使用-a（或--all），那么数据库名可以从环境变量 KINGBASE_DATABASE 中被读出。如果环境变量也未设置，那么连接指定的用户名将作为数据库名使用。 -e --echo 回显 reindexdb 生成并发送到服务器的命令。 -i index --index=index 只对 “index“重建索引。可以通过写多个-i 开关来重建多个索引。 -q --quiet 不显示进度消息。 -s --system 重建数据库系统目录的索引。 -S schema --schema=schema 只对 “schema“重建索引。通过写多个-S 开关可以指定多个要重建索引的模式。 -t table --table=table 只对 “table“重建索引。可以通过写多个-t 开关来重索引多个表。 -v --verbose 在处理时打印详细信息。 -V --version 打印 reindexdb 版本并退出。 -? --help 显示有关 reindexdb 命令行参数的帮助并退出。 -h host --host=host 指定运行数据库机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定数据库正在监听连接的 TCP 端口或本地 Unix 域套接字扩展文件。 -U username --username=username 指定连接的用户名。 -w --no-password 不提示输入密码。如果服务器要求密码认证并且没有其他方式提供密码（例如一个.kbpass 文件），那么连接将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入密码。 -W --password 51 第 10 章 REINDEXDB reindexdb 连接数据库之前，提示输入密码。这个选项不是必须的，因为如果服务器要求密码认证，reindexdb 将自动提示要求输入一个密码，同时 reindexdb 将浪费一次密码尝试机会。在某些情况下需要用-W 来避免额外的连接尝试。 --maintenance-db=dbname 使用 “-a/--all“ 参数时，通过 dbname 指定要连接的数据库名，以确定哪些数据库需要重建索引。如果没有指定，将使用 kingbase 数据库。而如果它也不存在，将使用 template1。 10.4 环境变量 KINGBASE_DATABASE KINGBASE_HOST KINGBASE_PORT KCIUSER 默认连接参数 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 10.5 错误信息诊断在有错误发生时，可以在 REINDEX 和 ksql 中找潜在问题和错误消息的讨论。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 10.6 示例要重索引数据库 test： $ reindexdb test 要重索引名为 abcd 的数据库中的表 foo 和索引 bar： $ reindexdb --table=foo --index=bar abcd 10.7 备注 reindexdb 可能需要多次连接到 KingbaseES 服务器，每一次都会询问一个密码。在这种情况下使用一个 ~/. kbpass 文件会更方便。 52 第 10 章 10.8 REINDEXDB 参考 REINDEX 53 第 11 章 SYS_BASEBACKUP 11章 sys_basebackup 第 11.1 简介 sys_basebackup —获得一个 KingbaseES 集群的一个基础备份 sys_basebackup 被用于获得一个正在运行的 KingbaseES 数据库集群的基础备份。获得这些备份不会影响连接到该数据库的其他客户端，并且可以被用于时间点恢复以及用作一个日志传送或流复制后备服务器的开始点。 sys_basebackup 建立数据库集群文件的一份二进制副本，同时保证系统进入和退出备份模式。备份总是从整个数据库集群获得，不能备份单个数据库或数据库对象。关于个体数据库备份，必须使用sys_dump 的工具。备份通过一个常规 KingbaseES 连接制作，并且使用复制协议。该连接必须由一个超级用户或者一个具有 REPLICATION 权限（角色属性）的用户建立，并且 sys_hba.conf 必须显式地允许该复制连接。该服务器必须由 max_wal_senders 配置，设置足够高的级别，留出至少一个会话用于备份以及一个用于 WAL 流（如果使用流）。在同一时间可以有多个 sys_basebackup 运行，但是从性能角度来说最好只做一个备份并且复制结果。 sys_basebackup 不仅能从主库也能从备库创建一个基础备份。要从备库获得一个备份，设置备库让它能接受复制连接（也就是，设置 max_wal_senders 和 hot_standby ，并且配置基于主机的认证（见 sys_hba.conf 文件））。你将也需要在主库上启用 full_page_writes 。注意在来自备库的在线备份中有一些限制： • 不会在被备份的数据库集群中创建备份历史文件。 • 如果正在使用-X none，不保证备份所需的所有 WAL 文件在备份结束时被归档。 • 如果备库在执行备份期间备库被提升为主库，备份会失败。 • 本工具不支持 UNLOGGED TABLE 的数据内容的备份和还原。 • 备份所需的所有 WAL 记录必须包含足够的全页写，这要求你在主库上启用 full_page_writes，并且 WAL 文件不能被类似 sys_compresslog 的工具以 archive_command 方式移除全页写。 54 第 11 章 SYS_BASEBACKUP 命令行参数 11.2 sys_basebackup [ option ...] 参数说明 11.3 下列命令行选项控制输出的位置和格式。 -D directory --kingbase_data=directory 基础备份输出目录。必要时 sys_basebackup 将创建该目录及任何父目录。该目录可能已经存在，但是如果该目录已经存在并且非空就是一个错误。当备份处于 tar 模式中并且目录被指定为-（破折号）时，tar 文件将被写到 stdout。这个选项是必需的。 -F format --format=format 为输出选择格式。“format“可以是下列之一： p plain 把输出写成普通文件，使用与当前数据目录和表空间相同的布局。当集群没有额外表空间时，整个数据库将被放在目标目录中。如果集群包含额外的表空间，主数据目录将被放置在目标目录中，但是所有其他表空间将被放在它们位于服务器上的相同的绝对路径中。这是默认格式。 t tar 将输出写成目标目录中的 tar 文件。主数据目录将被写入到一个名为 base.tar 的文件中，并且其他表空间将被以其 OID 命名。如果值-（破折号）被指定为目标目录，tar 内容将被写到标准输出，适合于管道输出到其他程序，例如 gzip。只有当集群没有额外表空间并且没有使用 WAL 流时这才是可能的。 -r rate --max-rate=rate 从该服务器传输数据的最大传输率。值的单位是千字节每秒。加上一个后缀 M 表示兆字节每秒。也接受后缀 k，但是没有效果。合法的值在 32 千字节每秒到 1024 兆字节每秒之间。其目标是限制在运行服务器上的 sys_basebackup 产生的影响。这个选项总是会影响数据目录的传输。如果收集方法是 fetch 时，只有 WAL 文件受到影响。 -R --write-recovery-conf 在输出目录中（或者当使用 tar 格式时在基础归档文件中）创建 standby.signal 并附加连接设置到 kingbase.auto.conf 来简化设置一个后备服务器。kingbase.auto.conf 文件将记录连接设置（如果有）以及 sys_basebackup 所使用的复制槽，这样流复制后面就会使用相同的设置。 55 第 11 章 SYS_BASEBACKUP -T olddir=newdir --tablespace-mapping=olddir=newdir 在备份期间将目录 “olddir“中的表空间重定位到 “newdir“中。为使之有效，“olddir“必须正好匹配表空间所在的路径（但如果备份中没有包含 “olddir“中的表空间也不是错误）。“olddir“和 “newdir“必须是绝对路径。如果一个路径凑巧包含了一个 = 符号，可用反斜线对它转义。对于多个表空间可以多次使用这个选项。示例见下文。如果以这种方法重定位一个表空间，主数据目录中的符号链接会被更新成指向新位置。因此新数据目录已经可以被一个所有表空间位于更新后位置的新服务器实例使用。 --waldir=waldir 指定用于预写式日志目录的位置。“waldir“必须是绝对路径。只有当备份是普通文件 “plain“模式时才能指定事务日志目录。 -X method --wal-method=method 在备份中包括所需的预写式日志文件（WAL 文件）。这包括所有在备份期间产生的预写式日志。除非指定了方法 none，可以直接在提取出的目录中启动 kingbase 而无需参考日志归档，所以这样得到的是一种完整的独立备份。支持下列收集预写式日志的方法： n none 不要在备份中包括预写式日志。 f fetch 在备份末尾收集预写式日志文件。因此，有必要把 wal_keep_segments 参数设置得足够高，这样在备份末尾之前日志不会被移除。如果在要传输日志时它已经被更迭，备份将失败并且是不可用的。如果使用 tar 格式，预写式日志文件将被写入到 base.tar 文件。 s stream 在备份被创建时流传送预写式日志。这将开启一个到服务器的第二连接，并且在运行备份时并行开始流传输预写式日志。因此，它将使用最多两个由 max_wal_senders 参数配置的连接。只要客户端能保持接收预写式日志，使用这种模式不需要在主库上保存额外的预写式日志。如果使用 tar 格式，预写式日志文件被写入到一个单独的名为 sys_wal.tar 的文件。这个值是默认值。 -z --gzip 启用对 tar 文件输出的 gzip 压缩，使用默认的压缩级别。只有使用 tar 格式时压缩才可用，并且会在所有 tar 文件名后面自动加上后缀.gz。 -Z level --compress=level 启用对 tar 文件输出的 gzip 压缩，并且制定压缩机别（0 到 9，0 是不压缩，9 是最佳压缩）。只有使用 tar 格式时压缩才可用，并且会在所有 tar 文件名后面自动加上后缀.gz。 56 第 11 章 SYS_BASEBACKUP 下列命令行选项控制备份的生成和程序的运行。 -c fast|spread --checkpoint=fast|spread 将检查点模式设置为 fast（立刻）或 spread（默认）。 -C --create-slot 这个选项会导致在开始备份前创建一个由--slot 选项指定名称的复制槽。如果槽已经存在则会发生错误。 -l label --label=label 为备份设置标签。如果没有指定，将使用一个默认值“sys_basebackup base backup”。 -n --no-clean 默认情况下，当 sys_basebackup 因为一个错误而中止时，它会把它意识到无法完成该工作之前已经创建的目录（例如数据目录和预写式日志目录）都移除。这个选项可以禁止这种清洗，因此可以用于调试。注意不管哪一种方式都不会清除表空间目录。 -N --no-sync 默认情况下，sys_basebackup 将等待所有文件被安全地写到磁盘上。这个选项导致 sys_basebackup 不做这种等待就返回，这样会更快一些，但是也意味着后续发生的操作系统崩溃可能会使得这个基础备份损坏。通常这个选项对测试比较有用，在创建生产安装时不应该使用。 -P --progress 启用进度报告。启用这个选项将在备份期间发表一个大致的进度报告。由于数据库可能在备份期间改变，这仅仅是一种近似进度并且可能不会刚好在 100% 结束。特别地，当 WAL 日志被包括在备份中时，总数据量无法预先估计，并且这种情况下一旦传递的总估计不包含 WAL, 那么估计的大小写还会增加。当这个选项被启用时，备份开始时会计算整个数据库的尺寸，接着开始发送实际的内容。这可能使备份需要多花一点点时间，特别是在发送第一个数据之前需要花费更长时间。 -S slotname --slot=slotname 这个选项仅能与-X stream 一起使用。它导致 WAL 流使用指定的复制槽。如果该基础备份的目的是被用作一台使用复制槽的流复制后备，则它应该使用与 primary_slot_name 中相同的复制槽名称。通过这种方式，可以确保服务器不会移除位于该基础备份结束与流复制开始之间产生的任何所需的 WAL 数据。指定的复制槽必须已经存在，除非同时使用了选项-C。如果这个选项没有被指定并且服务器支持临时复制槽，则会自动使用一个临时复制槽来进行 WAL 流。 -v --verbose 启用冗长模式。将在启动和关闭期间输出一些额外步骤，并且如果进度报告也被启用，还会显示当前正在被处理的确切文件名。 --no-slot 如果服务器支持临时复制槽，这个选项防止备份期间创建临时复制槽。 57 第 11 章 SYS_BASEBACKUP 在使用日志流时，如果没有用选项-S 指定槽名称，则默认会创建临时复制槽。这个选项的主要目的是允许在服务器没有空闲复制槽可用时制作基础备份。使用复制槽几乎总是最好的方式，因为它能防止备份期间所需的 WAL 被删除。 --no-verify-checksums 如果在取基础备份的服务器上启用了校验码验证，则禁用校验码验证。默认情况下，校验码会被验证并且校验码失败将会导致一种非零的退出状态。不过，基础备份在这种情况下将不会被移除，就好像使用了--no-clean 选项一样。校验和校验失败也将被在 sys_stat_database 视图中被报告。下列命令行选项控制数据库连接参数。 -d connstr --dbname=connstr 以一个连接字符串的形式指定用于连接到服务器的参数。为了和其他客户端应用一致，该选项被称为--dbname。但是因为 sys_basebackup 并不连接到集群中的任何特定数据库，连接字符串中的数据库名将被忽略。 -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。默认值取自 KINGBASE_HOST 环境变量（如果设置），否则会尝试一个 Unix 域套接字连接。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认用 KINGBASE_PORT 环境变量中的值（如果设置），或者一个编译在程序中的默认值。 -s interval --status-interval=interval 指定发送回服务器的状态包之间的秒数。这允许我们更容易地监控服务器的进度。一个零值完全禁用这种周期性的状态更新，不过当服务器需要时还是会有一个更新会被发送来避免超时导致的断开连接。默认值是 10 秒。 -U username --username=username 要作为哪个用户连接。 -w --no-password 从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个.kbpass 文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。 -W --password 强制 sys_basebackup 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，sys_basebackup 将自动提示要求一个口令。但是，sys_basebackup 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W 来避免额外的连接尝试。 58 第 11 章 SYS_BASEBACKUP 其他选项也可用： -V --version 打印 sys_basebackup 版本并退出。 -? --help 显示有关 sys_basebackup 命令行参数的帮助并退出。 11.4 环境变量和大部分其他 KingbaseES 工具相似，这个工具也使用 libpq 支持的环境变量。环境变量 SYS_COLOR 指定使用诊断信息中的颜色。可能的值是 always、auto、never. 11.5 错误信息诊断无 11.6 示例创建服务器 mydbserver 的一个基础备份并将它存储在本地目录/opt/Kingbase/ES/V9/data 中： $ sys_basebackup -h mydbserver -D /opt/Kingbase/ES/V9/data 创建本地服务器的一个备份，为其中每一个表空间产生一个压缩过的 tar 文件，并且将它存储在目录 backup 中，在运行期间显示一个进度报告： $ sys_basebackup -D backup -Ft -z -P 创建一个单一表空间本地数据库的备份并且使用 bzip2 压缩它： $ sys_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2 （如果在该数据库中有多个表空间，这个命令将失败）。创建一个本地数据库的备份，其中/opt/ts 中的表空间被重定位到./backup/ts： $ sys_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts 创建一个本地数据库的备份，在备份过程上输出备份进度 59 第 11 章 SYS_BASEBACKUP $ sys_basebackup -Fp -Pv -Xf -D backup/data 11.7 备注在备份的开始时，需要向从中拿去备份的服务器写一个检查点。尤其在没有使用选项--checkpoint=fast 时，这可能需要一点时间，在其间 sys_basebackup 看起来处于闲置状态。备份将包括数据目录和表空间中的所有文件，包括配置文件以及由第三方放在该目录中的任何额外文件，不过由 KingbaseES 管理的特定临时文件除外。但只有常规文件和目录会被拷贝，但用于表空间的符号链接会被保留。指向 KingbaseES 已知的特定目录的符号链接被拷贝为空目录。其他符号链接和特殊设备文件会被跳过。表空间默认将以普通格式备份到与它们在服务器上相同的路径中，除非使用了--tablespace-mapping 选项。如果没有这个选项并且表空间正在使用，在同一台服务器上进行普通格式的基础备份将无法工作，因为备份必须要写入到与原始表空间相同的目录位置。在使用 tar 格式模式时，用户应负责在启动 KingbaseES 服务器前解压每一个 tar 文件。如果有额外的表空间，用于它们的 tar 文件需要被解压到正确的位置。在这种情况下，服务器将根据包含在 base.tar 文件中的 tablespace_map 文件的内容为那些表空间创建符号链接。 sys_basebackup 可以和具有相同或较低主版本的服务器一起工作，最低是 KingbaseES V8R2 。WAL 流模式（-X 流）只能和版本为 KingbaseES V8R3 及以上版本的服务器一起工作。当前版本的 tar 格式模式（--format=tar）只能用于版本 KingbaseES V8R3 及以上的服务器。如果在源集群上启用了组权限，在 plain 以及 tar 模式中 sys_basebackup 将保留组权限。 11.8 参考 sys_dump 60 第 12 章 SYS_CONFIG 12章 sys_config 第 12.1 简介 sys_config —获取已安装的 KingbaseES 的系统信息。 sys_config 是一个命令行工具，该命令行工具位于 KingbaseES 安装目录的 bin 目录下。用来打印当前安装版本的 KingbaseES 的配置参数信息。它的设计目的便于那些想与 KingbaseES 交互的软件包能够找到所需的头文件和库文件信息。 12.2 命令行参数 sys_config [ option ...] 12.3 参数说明要使用 sys_config，提供一个或多个下列选项： --bindir 打印用户可执行文件的位置。例如使用这个选项来寻找 ksql 程序。这通常也是 sys_config 程序所在的位置。 --docdir 打印文档文件的位置。 --htmldir 打印 HTML 文档文件的位置。 --includedir 打印客户端接口的 C 头文件的位置。 61 第 12 章 SYS_CONFIG --pkgincludedir 打印其它 C 头文件的位置。 --includedir-server 打印用于服务器编程的 C 头文件的位置。 --libdir 打印对象代码库的位置。 --pkglibdir 打印动态可载入模块的位置，或者服务器可能搜索它们的位置（其它架构独立数据文件可能也被安装在这个目录）。 --localedir 打印区域支持文件的位置（如果在 KingbaseES 被编译时没有配置区域支持，这将是一个空字符串）。 --mandir 打印手册页的位置。 --sharedir 打印架构独立支持文件的位置。 --sysconfdir 打印系统范围配置文件的位置。 --sysxs 打印扩展 makefile 的位置。 --configure 打印当 KingbaseES 被配置编译时给予 configure 脚本的选项。这可以被用来重新得到相同的配置，或者找出是哪个选项编译了一个二进制包（不过注意二进制包通常包含厂商相关的自定补丁）。参见下面的例子。 --cc 打印用来编译 KingbaseES 的 CC 变量值。这显示被使用的 C 编译器。 --cppflags 打印用来编译 KingbaseES 的 CPPFLAGS 变量值。这显示在预处理时需要的 C 编译器开关（典型的是-I 开关）。 --cflags 打印用来编译 KingbaseES 的 CFLAGS 变量值。这显示被使用的 C 编译器开关。 --cflags_sl 打印用来编译 KingbaseES 的 CFLAGS_SL 变量值。这显示被用来编译共享库的额外 C 编译器开关。 62 第 12 章 SYS_CONFIG --ldflags 打印用来编译 KingbaseES 的 LDFLAGS 变量值。这显示链接器开关。 --ldflags_ex 打印用来编译 KingbaseES 的 LDFLAGS_EX 变量值。这只显示被用来编译可执行程序的链接器开关。 --ldflags_sl 打印用来编译 KingbaseES 的 LDFLAGS_SL 变量值。这只显示被用来编译共享库的链接器开关。 --libs 打印用来编译 KingbaseES 的 LIBS 变量值。这通常包含用于链接到 KingbaseES 中的外部库的-l 开关。 --version 打印 KingbaseES 的版本。 -? --help 显示有关 sys_config 命令行参数的帮助并退出。如果给定多于一个选项，将按照相同的顺序打印信息，每行一项。如果没有给定选项，将打印所有可用信息，并带有标签。 12.4 示例要重建当前 KingbaseES 安装的编译配置，可运行下列命令： eval ./configure `sys_config --configure` sys_config --configure 的输出包含 shell 引号，这样带空格的参数可以被正确地表示。因此，为了得到正确的结果需要使用 eval。 12.5 选备注项--docdir、--pkgincludedir、--localedir、--mandir、--sharedir、--sysconfdir、--cc、 --cppflags、--cflags、--cflags_sl、--ldflags、--ldflags_sl 和--libs 在 KingbaseES V7 被加入。选项--htmldir 在 KingbaseES V7 被加入。选项--ldflags_ex 在 KingbaseES V8R2 被加入。 12.6 参考无 63 第 13 章 SYS_DUMP 13章 sys_dump 第 13.1 简介 sys_dump —把 KingbaseES 数据库抽取为一个脚本文件或其他归档文件 sys_dump 是一种用于备份 KingbaseES 数据库的工具。即使数据库正在并发使用，它也能创建一致的备份。 sys_dump 不阻塞其他用户访问数据库（读取或写入）。 sys_dump 只转储单个数据库。要备份整个集簇，或备份集簇中所有数据库公共的全局对象（例如角色和表空间），请使用sys_dumpall。转储以脚本或归档文件格式输出。脚本转储是包含 SQL 命令的纯文本文件，可以使用该脚本文将数据库恢复到转储时的状态。要从这样的脚本恢复数据库，请将其提供给 ksql。即使在其他机器和其他架构上，脚本文件也可用于恢复数据库；在经过一些修改后，甚至可以在其他 SQL 数据库产品上恢复数据库。另一种可选的归档文件格式，须与sys_restore 配合使用来恢复数据库。它们允许sys_restore 选择要恢复的内容，甚至可以在恢复之前对条目重排序。归档文件格式旨在跨架构迁移。当一种归档文件格式与sys_restore 结合使用时，sys_dump 提供了一种灵活的归档和传输机制。sys_dump 可用于备份整个数据库，而sys_restore 可用于检查归档并/或选择要恢复数据库的哪些部分。最灵活的输出文件格式是 “自定义”格式（-Fc）和“目录”格式（-Fd）。它们允许选择和重排序所有已归档项，支持并行恢复，并且默认是压缩的。“目录”格式是唯一支持并行转储的格式。当运行 sys_dump 时，请检查输出是否有任何警告（打印在标准错误上）。 13.2 命令行参数 sys_dump [ connection-option ...] [ option ...] [ dbname ] 13.3 参数说明下列命令选项控制输出的内容和格式。 64 第 13 章 SYS_DUMP dbname 指定要转储的数据库名。如果没有指定，将使用环境变量 KINGBASE_DATABASE。如果环境变量也没有设置，则使用指定给该连接的用户名。 -a --data-only 只转储数据，而不转储模式（数据定义）。表数据、大对象和序列值都会被转储。这个选项类似于指定--section=data，但是由于历史原因又不完全相同。 -b --blobs 在转储中包括大对象。这是默认行为，除非指定了--schema、--table 或--schema-only。因此，只有在请求转储一个特定方案或者表的情况中，-b 开关才对向转储中加入大对象有用。请注意，blobs 是被视为数据，因此在使用--data-only 时将包括在内，但在使用--schema-only 时则不会包括。 -B --no-blobs 排除转储中的大对象。当同时给定-b 和-B 时，行为是输出大对象，当数据被转储时，请参考-b 文档。 -c --clean 在输出创建数据库对象的命令之前，输出清除（删除）它们的命令（除非还指定了--if-exists，否则如果目标数据库中不存在任何对象，恢复可能会产生一些无害的错误消息）。这个选项只对纯文本格式有意义。对于归档格式，您可以在调用sys_restore 时指定该选项。 -C --create 该命令使得在输出的开始是创建数据库，并且重新连接到被创建的数据库（使用这种形式的脚本，在运行脚本之前连接的是目标安装中的哪个数据库都没有关系）。如果还指定了--clean，脚本会在重新连接之前删除并重建目标数据库。使用--create 时，输出还会包括数据库的注释（如果有）以及与这个数据库相关的配置变量的设置，也就是任何提到了这个数据库的 ALTER DATABASE ... SET ... 命令和 ALTER ROLE .. . IN DATABASE ... SET ... 命令。除非指定有--no-acl，否则该数据库本身的访问特权也会被转储。这个选项只对纯文本格式有意义。对于归档格式，您可以在调用sys_restore 时指定这个选项。 -E encoding --encoding=encoding 以指定的字符集编码创建转储。默认情况下，转储会以数据库的编码创建（另一种得到相同结果的方式是将 KCICLIENTENCODING 环境变量设置成想要的转储编码）。 -f file --file=file 将输出发送到指定文件。对于基于输出格式的文件，这个参数可以被忽略，在这种情况下将使用标准输出。但是，对于目录输出格式必须给定这个参数，在目录输出格式中指定的是一个目录而不是一个文件。在这种情况中，该目录会由 sys_dump 创建，并且之前不能存在。 -F format --format=format 65 第 13 章 SYS_DUMP 选择输出的格式。format 可以是下列之一： p plain 输出一个纯文本形式的 SQL 脚本文件（默认值）。 c custom 输出一个适合于作为sys_restore 输入的自定义格式归档。和目录输出格式一起，这是最灵活的输出格式，它允许在恢复时手动选择和排序已归档的项。默认情况下，此格式也是压缩的。 d directory 输出一个适合作为sys_restore 输入的目录格式归档。这将创建一个目录，其中每个被转储的表和大对象都有一个文件，外加一个所谓的目录文件，该文件以一种sys_restore 能读取的机器可读格式描述转储的对象。可以使用标准 Unix 工具操作目录格式归档，例如一个未压缩归档中的文件可以使用 gzip 工具压缩。这种格式默认是压缩的，也支持并行转储。 t tar 输出一个适合于输入到sys_restore 中的 tar 格式归档。tar 格式可以兼容目录格式，抽取一个 tar 格式的归档会产生一个合法的目录格式归档。但是 tar 格式不支持压缩。此外，在使用 tar 格式时，表数据项的相对顺序不能在恢复过程中被更改。 -j njobs --jobs=njobs 通过同时归档 njobs 表来运行并行转储。这个选项缩减了转储的时间，但是它也增加了数据库服务器上的负载。您只能和目录输出格式一起使用这个选项，因为这是唯一一种让多个进程能在同一时间写其数据的输出格式。 sys_dump 将打开 njobs + 1 个到该数据库的连接，因此请确保您的 max_connections 设置地足够高，可以容纳所有的连接。在运行一次并行转储时请求数据库对象上的排他锁可能导致转储失败。其原因是，sys_dump 主控进程会在工作者进程将要稍后转储的对象上请求共享锁，以便确保在转储运行时不会有人删除它们并让它们出错。如果另一个客户端接着请求一个表上的排他锁，那个锁将不会被授予，但是会被排入队列等待主控进程的共享锁被释放。因此，任何其他对该表的访问将不会被授予，并且将在排他锁请求之后排队。这包括尝试转储该表的工作者进程。如果没有任何防范措施，这可能会是一种经典的死锁情况。要检测这种冲突，sys_dump 工作者进程使用 NOWAIT 选项请求另一个共享锁。如果该工作者进程没有被授予这个共享锁，那么肯定是其他进程同时请求了一个排他锁，并且没有办法继续转储，因此 sys_dump 除了中止转储之外别无选择。对于一致的备份，数据库服务器需要支持同步快照，这是在 KingbaseES 的主服务器和后备服务器中引入了一种特性。有了这种特性，即便数据库客户端使用不同的连接，也可以保证他们看到相同的数据集。 sys_dump -j 使用多个数据库连接，它用主控进程连接到数据一次，并且为每一个工作者任务再一次连接数据库。如果没有同步快照特征，在每一个连接中不同的工作者任务将不能被保证看到相同的数据，这可能导致一个不一致的备份。如果要运行 KingbaseES 之前的服务器的并行转储，您需要确保从主控进程连接到数据库一直到最后一个工作者任务连接到数据库之间，数据库内容不会发生改变。做这些最简单的方法是在开始备份之前停止任 66 第 13 章 SYS_DUMP 何访问数据库的数据修改进程（DDL 和 DML）。当对 KingbaseES 之前版本的 KingbaseES 服务器运行 sys_dump -j 时，还需要指定--no-synchronized-snapshots 参数。 -K --key=encryptkey 备份数据时候指定加密秘钥。1. 秘钥长度不能超过 16 字节。2. 不能和压缩同时使用。3. 只能用于二进制格式输出。 -n pattern --schema=pattern 只转储匹配 pattern 的模式，这会选择模式本身以及它所包含的所有对象。当没有指定这个选项时，目标数据库中所有非系统模式都将被转储。多个模式可以通过书写多个-n 开关来选择。另外，pattern 参数可以被解释为一种根据 ksql 的 \d 命令所用的相同规则编写的模式，这样多个模式也可以通过在该模式中书写通配字符来选择。在使用通配符时，如果需要，请小心引用该模式，防止 shell 扩展通配符；请详见下面的示例。注意: 指定-n 时，sys_dump 不会尝试转储所选模式可能依赖的任何其他数据库对象。因此，无法保证特定模式转储的结果可以自行成功地恢复到一个干净的数据库中。注意: 指定-n 时，非模式对象（如二进制大对象）不会被转储。您可以使用--blobs 开关将二进制大对象添加回该转储中。 -N pattern --exclude-schema=pattern 不转储匹配 pattern 的任何模式。该模式根据与-n 相同的规则进行解释。可以多次给定-N 来排除与多个模式中的任何一个匹配的模式。当-n 和-N 都被给定时，该行为是只转储匹配至少一个-n 开关但是不匹配-N 开关的模式。如果只有-N 而没有-n，那么匹配-N 的模式会被从一个正常转储中排除。 -O --no-owner 不输出设置对象拥有关系来匹配原始数据库的命令。默认情况下，sys_dump 会发出 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置被创建的数据库对象的拥有关系。除非该脚本是由超级用户（或是拥有脚本中所有对象的同一个用户）启动的，这些语句都将会失败。要使一个脚本能够被任意用户恢复，只有把所有对象的拥有关系都赋予这个用户，可指定-O。这个选项只对纯文本格式有意义。对于归档格式，您可以在调用sys_restore 时指定该选项。 -R --no-reconnect 这个选项已经废弃，但是为了向后兼容仍然保留。 -s --schema-only 只转储对象定义（模式），而非数据。这个选项与--data-only 选项相反。它和指定--section=pre-data --section=post-data 相似，但是由于历史原因又不完全相同。（不要把这 67 第 13 章 SYS_DUMP 个选项和--schema 选项混淆，后者在“schema”的使用上有不同的含义）。要为数据库中表的一个子集排除表数据，见--exclude-table-data。 -S username --superuser=username 指定要在禁用触发器时使用的超级用户的用户名。只有使用--disable-triggers 时，这个选项才相关（通常，最好省去这个选项，而是以超级用户身份来启动生成的脚本）。 -t pattern --table=pattern 只转储名字匹配 pattern 的表，table 可以是视图、物化视图、序列和外部表。通过写多个-t 开关可以选择多个表。另外，pattern 参数可以被解释为一种根据 ksql 的 \d 命令所用的相同规则编写的模式，这样多个表也可以通过在该模式中书写通配符来选择。在使用通配符时，如果需要，请小心引用该模式，防止 shell 扩展通配符，请参加见下面示例。使用-t 时，-n 和-N 开关不会有效果，因为无论那些开关如何，都将转储-t 选择的表，并且不会转储非表对象。注意: 指定-t 时，sys_dump 不会尝试转储所选表可能依赖的任何其他数据库对象。因此，无法保证特定表转储的结果能够自行成功地恢复到一个干净的数据库中。 -T pattern --exclude-table=pattern 不转储匹配 pattern 模式的任何表。该模式根据与-t 相同的规则被解释。-T 可以多次给定来排除与多个模式中的任何一个模式匹配的表。当同时给定-t 和-T 时，该行为是只转储匹配至少一个-t 开关但是不匹配-T 开关的表。如果只有-T 而没有-t，那么匹配-T 的表将从一个正常转储中排除。 -v --verbose 指定冗长模式。这将导致 sys_dump 向标准错误输出详细的对象注释以及转储文件的开始/停止时间，还有进度消息。 -V --version 打印 sys_dump 版本并退出。 -x --no-privileges --no-acl 防止转储访问特权（授予/收回命令）。 -Z 0..9 --compress=0..9 指定要使用的压缩级别。零意味着不压缩。对于自定义归档格式，这会指定个体表数据段的压缩，并且默认是进行中等级别的压缩。对于纯文本输出，设置一个非零压缩级别会导致整个输出文件被压缩，就好像它被 gzip 处理过一样，但是默认是不压缩。tar 归档格式当前完全不支持压缩。 --binary-upgrade 这个选项用于就地升级功能。我们不推荐也不支持把它用于其他目的。这个选项在未来的发行中可能被改变而不做通知。 68 第 13 章 SYS_DUMP --column-inserts --attribute-inserts 将数据转储为带有显式列名的 INSERT 命令（INSERT INTO table (column, ...) VALUES ...）。这将使得恢复过程非常慢，这主要用于使转储能够被载入到非 KingbaseES 数据库中。在重新加载期间发生的任何错误只会导致有问题的 INSERT 的一部分的行丢失，而不是整个表的内容。 --copy-binary 将数据转储使用 COPY 命令时以二进制形式进行。这个选项不能与输出一个纯文本形式的 SQL 脚本文件 “-Fp“参数以及使用 INSERT 等转储命令参数同时使用。 --disable-dollar-quoting 这个选项禁止在函数体中使用美元符号引用，并且强制它们使用 SQL 标准字符串语法进行引用。 --disable-triggers 只有在创建一个只转储数据的转储时，这个选项才相关。它指示 sys_dump 包括在数据被重新载入时能够临时禁用目标表上的触发器的命令。如果您在表上有引用完整性检查或其他触发器，并且您在数据重新载入期间不想调用它们，请使用这个选项。当前，为--disable-triggers 发出的命令必须作为超级用户来执行。因此，您还应当使用-S 指定一个超级用户名，或者宁可作为一个超级用户启动生成的脚本。这个选项只对纯文本格式有意义。对于归档格式，您可以在调用sys_restore 时指定这个选项。 --enable-row-security 只有在转储具有行安全性的表的内容时，这个选项才相关。默认情况下，sys_dump 将把 row_security 设置为 off 来确保从该表中转储出所有的数据。如果用户不具有足够能绕过行安全性的特权，那么会抛出一个错误。这个参数指示 sys_dump 将 row_security 设置为 on，允许用户只转储该表中它们有权访问的部分内容。注意如果当前您使用了这个选项，您可能还希望得到 INSERT 格式的转储，因为恢复期间的 COPY FROM 不支持行安全性。 --exclude-table-data=pattern 不转储匹配 pattern 模式的任何表中的数据。该模式根据-t 的相同规则被解释。可以给定多次--exclude-table-data 来排除与多个模式中的任何一个模式匹配的表。当您需要一个特定表的定义但不想要其中的数据时，这个选项就有用了。要排除数据库中所有表的数据，见--schema-only。 --extra-float-digits=ndigits 在转储浮点数据时，使用 extra_float_digits 的指定值，而不是使用最大可用精度。用于备份目的的常规转储不应使用此选项。 --if-exists 69 第 13 章 SYS_DUMP 时间条件性命令（即增加一个 IF EXISTS 子句）来清除数据库和其他对象。只有同时指定了--clean 时，这个选项才可用。 --include-all-partitions[=opt] 仅在 Oracle 模式下生效。通过配置该参数值，控制在单独备份分区表时，是否同时备份该分区表下所有分区的结构和数据。可选参数值有：1，0，t，f，on，off, 默认值为 1。当 include-all-partitions=1/t/on 时，指定 -t 参数导出分区表的主表时，自动导出所有子表；当 include-all-partitions=0/f/off 时，指定 -t 参数导出分区表的主表时，不自动导出所有子表。 --inserts 将数据转储为 INSERT 命令（而不是 COPY）。这将使恢复非常慢，这主要用于制作可以加载到非 KingbaseES 数据库的转储。在重新加载期间发生的任何错误只会导致有问题的 INSERT 的一部分的行丢失，而不是整个表的内容。注意，如果重新安排了列顺序，则还原可能完全失败。--column-inserts 选项对于列顺序的更改是安全的，但是更慢。 --load-via-partition-root 该参数在 Oracle 模式下自动启用。在为一个分区表转储数据时，使 COPY 语句或者 INSERT 语句把包含它的分区层次的根作为目标，而不是分区自身。这会导致在装载数据时，为每一行重新确定合适的分区。如果在一台服务器上重新装载数据时，出现行并不是总是落入到和原始服务器上相同的分区中的情况，这个选项就会很有用。例如，如果分区列是文本类型，并且两个系统中用于排序分区列的排序规则有着不同的定义，就会发生这种情况。从使用这个选项制作的归档恢复时，最好不要使用并行，因为sys_restore 不会确切地知道一个给定的归档数据项将把数据装载到哪个分区中。这会导致效率不高，因为在并行任务见会有锁冲突，甚至可能由于在所有的相关数据被装载前建立了外键约束而导致重新装载失败。 --lock-wait-timeout=timeout 在转储的开始从不等待共享表锁的获得。如果在指定的 timeout 内不能锁定表时，则会失败。超时时长可以用 SET statement_timeout 接受的任何格式指定（可以是一个整数表示的毫秒数）。 --no-comments 不转储注释。 --no-publications 不转储出版信息。 --no-security-labels 不转储安全标签。 --no-subscriptions 不转储订阅。 --no-sync 默认情况下，sys_dump 将等待所有文件安全地写入磁盘。 70 第 13 章 SYS_DUMP 这个选项会让 sys_dump 不等待直接返回，这样会更快，但是也意味着后续的操作系统崩溃会让该转储损坏。通常这个选项对测试有用，但是不应该在从生产安装中转储数据时使用。 --no-tablespaces 不要输出选择表空间的命令。通过这个选项，在恢复期间所有的对象都会创建在默认的表空间中。这个选项只对纯文本格式有意义。对于归档格式，您可以在调用sys_restore 时指定该选项。 --no-unlogged-table-data 不转储非日志记录表的内容。这个选项对于表定义（模式）是否被转储没有影响，它只会限制转储表数据。当从备用服务器转储时，始终排除非日志记录表中的数据。 --on-conflict-do-nothing 向 INSERT 命令插入 ON CONFLICT DO NOTHING。此选项无效，除非--inserts, --column-inserts 或 --rows-per-insert 也是指定的。 --parallel-lob-data 设置该选项，对含有 lob 对象（BLOB，BYTEA，CLOB，NCLOB）的表或者分区表数据并行转储。这个选项需要与 sys_dump -j njobs（njobs > 1）同时使用，才能并行转储。 --quote-all-identifiers 强制引用所有标识符。当从 KingbaseES 主版本与 sys_dump 不同的服务器上转储一个数据库时，或者当输出准备载入到一个具有不同主版本的服务器时，推荐使用这个选项。默认情况下，sys_dump 仅引用在其自身的主要版本中作为保留字的标识符。在转储其他版本服务器时，这种默认行为有时会导致兼容性问题，因为那些版本可能具有些许不同的被保留词集合。使用--quote-all-identifiers 能阻止这种问题，但代价是转储脚本更难阅读。 --rows-per-insert=nrows 使用 INSERT 命令转储数据 (而非 COPY)。控制 INSERT 每行的最大行数。指定的值必须是一个大于零的数字。在重新加载期间发生的任何错误只会导致有问题的 INSERT 的一部分的行丢失，而不是整个表的内容。 --section=sectionname 只转储命名的段。段的名称可以是 pre-data、data 或 post-data。这个选项可以被指定多次来选择多个段。默认是转储所有段。数据段包含真正的表数据、大对象内容和序列值。数据后项包括索引、触发器、规则和除了已验证检查约束之外的约束的定义。数据前项包括所有其他数据定义项。 --serializable-deferrable 为转储使用一个可序列化的事务，保证所使用的快照与后面的数据库状态是一致的。但是这样做是在事务流中等待一个点，在该点上不能存在异常，这样就不会有转储失败或者导致其他事务带着 serialization_failure 回滚的风险。 71 第 13 章 SYS_DUMP 对于一个只为灾难恢复存在的转储，这个选项没什么益处。如果一个转储被用来在原始数据库持续更新期间载入一份用于报表或其他只读负载的数据库拷贝时，这个选项就有所帮助。如果没有这个选项，转储可能会反映一个与最终提交事务的任何执行序列都不一致的状态。例如，如果使用了批处理技术，一个批处理在转储中可以显示为关闭，而其中的所有项都不出现。如果 sys_dump 被启动时没有读写事务在活动，则这个选项没有什么不同。如果有读写事务在活动，该转储的启动可能会被延迟一段不确定的时间。一旦开始运行，有没有这个开关的表现是相同的。 --snapshot=snapshotname 在做一个数据库的转储时指定一个同步的快照。在需要把转储和一个逻辑复制槽或者一个并发会话同步时可以用上这个选项。在并行转储的情况下，将使用这个选项指定的快照名而不是取一个新快照。 --strict-names 要求每一个模式（-n/--schema）和表（-t/--table）限定符至少匹配要转储的数据库中的一个模式/表。注意，如果没有找到有这样的模式/表限定符匹配，即便没有--strict-names，sys_dump 也将生成一个错误。这个选项对-N/--exclude-schema、-T/--exclude-table 或者--exclude-table-data 没有效果。无法匹配任何对象的排除模式不会被当作错误。 --use-set-session-authorization 输出 SQL 标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来确定对象的所有关系。这让该转储更加兼容标准，但是根据该转储中对象的历史记录，可能无法正常恢复。此外，使用 SET SESSION AUTHORIZATION 的转储肯定需要超级用户权限才能正确地恢复，而 ALTER OWNER 需要较少的权限。 -? --help 显示有关 sys_dump 命令行参数的帮助并退出。下列时命令行选项控制数据库连接参数。 -d dbname --dbname=dbname 指定要连接到的数据库名。这等效于指定 dbname 为命令行上的第一个非选项参数。如果这个参数包含一个 = 符号或者以一个合法的 URI 前缀（kingbase://或 kingbase://）开始，它将被视作一个 conninfo 字符串。 -h host --host=host 指定服务器正在运行的机器的主机名。如果该值开始于斜线，则将其用作 Unix 域套接字的目录。默认值取自 KINGBASE_HOST 环境变量（如果设置了），否则将尝次 Unix 域套接字连接。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 KINGBASE_PORT 环境变量中（如果设置了），否则使用编译在程序中的默认值。 72 第 13 章 SYS_DUMP -U username --username=username 要作为哪个用户连接。 -w --no-password 不发出密码提示。如果服务器要求密码验证，并且密码不能通过其他方式获得（例如一个.kbpass 文件），那么连接尝试将失败。这个选项对于在没有用户输入密码的批处理任务和脚本中有用。 -W --password 强制 sys_dump 在连接到一个数据库之前提示输入密码。这个选项从来不是必须的，因为如果服务器要求密码验证，sys_dump 会将自动提示输入密码。但是， sys_dump 将浪费一次连接尝试来发现服务器需要密码。在某些情况下，值得键入-W 来避免额外的连接尝试。 --role=rolename 指定用来创建转储的角色名。这个选项导致 sys_dump 在连接到数据库后发出 SET ROLE rolename 命令。当经过身份验证的用户（由-U 指定）缺少 sys_dump 所需的权限，但是能够切换到一个具有所需权限的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。 13.4 环境变量 KINGBASE_DATABASE 如果被设置，就是要创建的数据库名，默认和用户名相同，除非在命令行中覆盖。 KINGBASE_HOST 指定要连接的主机名，默认连接到 localhost。 KINGBASE_PORT 指定要连接的服务器的端口号，默认为 54321。需要根据数据库实际部署修订。 KINGBASE_USER 指定要使用哪个用户连接数据库。默认与使用数据库的操作系统用户名相同。 PGOPTIONS 指定要使用那些参数连接到数据库。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 73 第 13 章 SYS_DUMP 13.5 错误信息诊断 sys_dump 在内部执行 SELECT 语句。如果您运行 sys_dump 时出现问题，确定您能够从正在使用的数据库中选择信息，例如 ksql 。此外，libkci 前端-后端库所使用的任何默认连接设置和环境变量都将适用。 sys_dump 的数据库活动由统计收集器正常地收集。如果不想这样，您可以通过 KINGBASE_OPTIONS 或 ALTER USER 命令设置参数 track_counts 为假。 13.6 示例要把一个数据库 mydb 转储到一个 SQL 脚本文件： $ sys_dump mydb > db.sql 要把这样一个脚本重新载入到一个（新创建的）名为 newdb 的数据库中： $ ksql -d newdb -f db.sql 要转储一个数据库到一个自定义格式归档文件： $ sys_dump -Fc mydb > db.dump 要转储一个数据库到一个目录格式的归档： $ sys_dump -Fd mydb -f dumpdir 要用 5 个并行的工作者任务转储一个数据库到一个目录格式的归档： $ sys_dump -Fd mydb -j 5 -f dumpdir 要把一个归档文件重新载入到一个（新创建的）名为 newdb 的数据库： $ sys_restore -d newdb db.dump 把一个归档文件重新装载到同一个数据库（该归档正是从这个数据库中转储得来）中，丢掉那个数据库中的当前内容： $ sys_restore -d kingbase --clean --create db.dump 要转储一个名为 mytab 的表： $ sys_dump -t mytab mydb > db.sql 要并行转储一个名为 mytab 的表： 74 第 13 章 SYS_DUMP $ sys_dump -t mytab mydb -Fd --parallel-lob-data -j5 -f dumpdir 要以二进制方式转储一个名为 mytab 的表： $ sys_dump -t mytab mydb -Fd --copy-binary -f dumpdir 要转储 detroit 模式中名称以 emp 开始的所有表，排除名为 employee_log 的表： $ sys_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql 要转储名称以 east 或者 west 开始并且以 gsm 结束的所有模式，排除名称包含词 test 的任何模式： $ sys_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql 同样，用正则表达式记号法来合并开关： $ sys_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql 要转储除了名称以 ts_ 开头的表之外的所有数据库对象： $ sys_dump -T 'ts_*' mydb > db.sql 在-t 和相关开关中指定一个大写或混合大小写的名称，需要将名称用双引号引起来，否则会被折叠为小写。并且双引号对于 shell 是特殊的，所以必须依次引用。因此，要转储一个有混合大小写名称的表，您需要类似这样的东西： $ sys_dump -t "\"MixedCaseName\"" mydb > mytab.sql 设置--including-all-partiton=0 导出指定主表结构 $ sys_dump -Usystem -d db10 -p8899 -Fp -f r_p_dump.dmp -t r_p_dump --including-all-partiton=0 设置--including-all-partiton=1 排除主表和子表结构和数据 $ sys_dump -Usystem 13.7 -d db10 -p8899 -Fp -f r_p_dump.dmp -T r_p_dump --including-all-partition=1 备注如果您的数据库集簇对于 template1 数据库有任何本地添加，请注意将 sys_dump 输出恢复到一个真正的空数据库。否则，由于增加对象的重复定义，您可能会遇到错误。要创建一个不带任何本地添加的空数据库，请从 template0 而不是 template1 复制它，例如： 75 第 13 章 SYS_DUMP CREATE DATABASE foo WITH TEMPLATE template0; 当仅选择数据转储并使用--disable-triggers 时，sys_dump 在开始插入数据之前会发出命令禁用用户表上的触发器，并且接着在数据被插入之后发出命令重新启用它们。如果恢复中途被停止，系统目录可能会停留在一种错误状态。 sys_dump 产生的转储文件不包含优化器用来做出查询计划决定的统计信息。因此，在从一个转储文件恢复后运行 ANALYZE 来确保最优性能是明智的，详见 KingbaseES 数据库维护指南。因为 sys_dump 用于传输数据到更新版本的 KingbaseES ，sys_dump 的输出被认为可以载入到比 sys_dump 版本更新的 KingbaseES 服务器中。sys_dump 也能够从比其版本更旧的 KingbaseES 服务器中转储（当前支持回退到 KingbaseES V7 版本）。不过，sys_dump 无法从比起主版本号更新的 KingbaseES 服务器中转储，它甚至将拒绝冒着创建一个非法转储的风险尝试。还有，不保证 sys_dump 的输出能被载入到一个更旧主版本的服务器--即使该转储是从该版本的服务器中获取的也不行。将一个转储文件载入到一个更旧的服务器可能需要手工编辑该转储文件来移除旧服务器无法理解的语法。在跨版本的情况下，推荐使用--quote-all-identifiers 选项，因为它可以避免因为不同 KingbaseES 版本间的保留字列表变化而发生问题。在转储逻辑复制订阅时，sys_dump 将生成使用 connect = false 选项的 CREATE SUBSCRIPTION 命令，这样恢复订阅时不会建立远程连接来创建复制槽或者进行初始的表拷贝。通过这种方式，可以无需到远程服务器的网络访问就能恢复该转储。然后就需要用户以一种合适的方式重新激活订阅。如果涉及到的主机已经改变，连接信息可能也必须被改变。在开启一次新的全表拷贝之前，截断目标表也可能是合适的。 sys_dump 导出表数据时，若表内某条记录的某列的长度过大（比如接近 1GB），可能会报错”ERROR: invalid memory alloc request size XXXXXXXXXX” 并退出，此时请添加”--copy-binary” 参数后再次尝试执行导出操作，若继续报该错误则无法使用 sys_dump 导出该表数据，建议手工按列导出该表数据。 13.8 参考 sys_dumpall, sys_restore, ksql 76 第 14 章第 14.1 SYS_DUMPALL 14章 sys_dumpall 简介 sys_dumpall —将一个 KingbaseES 数据库集簇抽取到一个脚本文件中 sys_dumpall 工具可以将一个集簇中所有的 KingbaseES 数据库写出到（“转储”）一个脚本文件。该脚本文件包含可以用作 ksql 的输入 SQL 命令来恢复数据库。它会对集簇中的每个数据库调用sys_dump 来完成该工作。sys_dumpall 还转储对所有数据库公用的全局对象（sys_dump 不保存这些对象），包括数据库用户和组、表空间以及适合所有数据库的访问权限等属性。因为 sys_dumpall 从所有数据库中读取表，所以需要以数据库超级用户的身份连接以便生成完整的转储。同样，也需要超级用户特权执行保存下来的脚本，这样才能增加角色和组以及创建数据库。 SQL 脚本将被写出到标准输出。使用-f/--file 选项或者 shell 操作符可以把它重定向到一个文件。 sys_dumpall 需要多次连接到 KingbaseES 服务器（每个数据库一次）。如果你使用口令认证，可能每次都会要求口令，这种情况下使用一个 ~/.kbpass 或 ~/.encpwd 文件会比较方便。 14.2 命令行参数 sys_dumpall [ connection-option ...] [ option ...] 14.3 参数说明下列命令行选项用于控制输出的内容和格式。 -a --data-only 只转储数据，不转储模式（数据定义）。 -c --clean 77 第 14 章 SYS_DUMPALL 包含在重建数据库之前清除（移除）它们的 SQL 命令。角色和表空间的 DROP 命令也会被加入进来。 -E encoding --encoding=encoding 用指定的字符集编码创建转储。默认情况下，转储使用数据库的编码创建（另一种得到相同结果的方法是设置 KCICLIENTENCODING 环境变量为想要的转储编码）。 -f filename --file=filename 将输出指定到文件中。如果省略，将使用标准输出。 -g --globals-only 只转储全局对象（角色和表空间），而不转储数据库。 -O --no-owner 不输出用于设置符合原始数据库对象所有权的命令。默认情况下，sys_dumpall 通过 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置被创建的模式元素的所有权，除非脚本是由一个超级用户（或者是拥有脚本中所有对象的同一个用户）运行，否则这些语句在脚本运行时会失败。要使得一个脚本能被任意用户恢复，但又不想给予该用户所有对象的所有权，可以指定-O。 -r --roles-only 只转储角色，不转储数据库和表空间。 -s --schema-only 只转储对象定义（模式），不转储数据。 -S username --superuser=username 指定要在禁用触发器时使用的超级用户。只有使用--disable-triggers 时，这个选项才有效（通常，最好省去这个选项，而作为超级用户来启动结果脚本来取而代之）。 -t --tablespaces-only 只转储表空间，不转储数据库和角色。 -v --verbose 指定细节模式。这将导致 sys_dumpall 向标准错误输出详细的对象注释以及转储文件的开始/停止时间、进度消息，同时也会启用 sys_dump 中的细节输出。 -V --version 打印 sys_dumpall 版本并退出。 -x --no-privileges --no-acl 防止转储访问特权（授予/收回命令）。 --binary-upgrade 这个选项用于本地升级功能，只能由升级工具使用, 不能把它用于其他目的。这个选项在未来的发行中可能被改变而不做通知。 78 第 14 章 SYS_DUMPALL --column-inserts --attribute-inserts 将数据转储为带有显式列名的 INSERT 命令（INSERT INTO table(column, ...) VALUES ...）。这将使得恢复过程非常慢，这主要用于使转储能够被载入到非 KingbaseES 数据库中。 --disable-dollar-quoting 这个选项禁止在函数体中使用美元符号引用，并且强制它们使用 SQL 标准字符串语法被引用。 --disable-triggers 只有在创建一个仅转储数据的转储时，这个选项才相关。它指示 sys_dumpall 在转储文件中包含数据被重新载入时能够临时禁用目标表上的触发器的命令。如果表上有引用完整性检查或其他触发器，并且在数据重新载入期间不想调用它们，请使用这个选项。当前，为--disable-triggers 发出的命令必须作为超级用户来执行。因此，你还应当使用-S 指定一个超级用户名，或者使用一个超级用户启动结果脚本。 --extra-float-digits=ndigits 在转储浮点数据时使用 extra_float_digits 的指定值控制浮点数据精度，而不是使用最大可用精度。用于备份目的的常规转储不应使用此选项。 --exclude-database=pattern 不要转储名称与 pattern 匹配的数据库。通过编写多个--exclude-database 开关，可以排除多个数据库。pattern 参数的解析处理方式与 ksql 的\d 命令 pattern 参数的解析方式相同（见 ksql 模式），多个数据库也可以通过编写通配符的模式排除。在使用通配符时，如果需要防止 shell 通配符展开，请小心引用模式。 --if-exists 时间条件性命令（即增加一个 IF EXISTS 子句）来清除数据库和其他对象。只有同时指定了--clean 时，这个选项才可用。 --inserts 将数据转储为 INSERT 命令（而不是 COPY）。这将使得恢复非常慢，主要用于使转储能够被载入到非 KingbaseES 数据库中。注意如果列序被改变，该恢复可能会一起失败。--column-inserts 选项对于列序改变是安全的，但是会更慢。 --load-via-partition-root 在为一个分区表转储数据时，让 COPY 语句或者 INSERT 语句把包含它的分区层次的根作为目标，而不是以分区自身为目标。这导致在数据被装载时，会为每一个行重新确定合适的分区。如果在一台服务器上重新装载数据时出现行并不是总是落入到和原始服务器上相同的分区中的情况，这个选项就很有用。例如，如果分区列是文本类型并且两个系统中用于排序分区列的排序规则有着不同的定义，就会发生这种情况。 --lock-wait-timeout=timeout 在转储开始时指定 timeout 时间内不能锁定一个表时失败。超时时长可以用 SET statement_timeout 接受的格式声明（允许的值根据你从其转出的服务器版本变化，所有版本都接受以为单位毫秒的整数值）。 79 第 14 章 SYS_DUMPALL --no-comments 不转储注释。 --no-publications 不转储 publication。 --no-role-passwords 不为角色转储口令。在恢复完后，角色的口令将是空口令，并且在设置口令之前口令认证都不会成功。由于指定这个选项时并不需要口令值，角色信息将从目录视图 sys_roles 而不是 sys_authid 中读出。因此，如果对 sys_authid 的访问被某条安全性策略所限制，那么这个选项也会有所帮助。 --no-security-labels 不转储安全标签。 --no-subscriptions 不转储 subscription。 --no-sync 默认情况下，sys_dumpall 将等待所有文件被安全地写入到磁盘后返回。这个选项会让 sys_dumpall 不做这种等待而返回，这样会更快，但是意味着后续的操作系统崩溃可能留下被损坏的转储。通常来说，这个选项对测试有用，但不应该在生产安装环境中转储数据时使用。 --no-tablespaces 不输出选择表空间的命令。通过这个选项，在恢复期间所有的对象都会被创建在任何作为默认的表空间中。 --no-unlogged-table-data 不转储非日志记录表的内容。这个选项对于表定义（模式）是否被转储没有影响，它只会限制转储表数据。 --on-conflict-do-nothing 在 INSERT 命令上添加 ON CONFLICT DO NOTHING。当使用--inserts 或--column-inserts 时此选项有效。 --quote-all-identifiers 强制引用所有标识符。在从一个与 sys_dumpall 主版本不同的 KingbaseES 服务器转储数据库时或者要将输出载入到一个不同主版本的服务器时，推荐使用这个选项。默认情况下，sys_dumpall 只会对为其主版本中保留词的标识符加上引号。在与其他版本的具有不同保留词集合的服务器交互时，这有时会导致兼容性问题。使用--quote-all-identifiers 可以阻止这类问题，但是代价是转储脚本会更加难读。 --rows-per-insert=nrows 使用 INSERT 命令转储数据 (而非 COPY)。控制 INSERT 命令每行的最大行数。指定的值必须是一个大于零的数字。在重新加载期间发生的任何错误只会导致有问题的 INSERT 行丢失，而不是整个表的内容。 --use-set-session-authorization 80 第 14 章 SYS_DUMPALL 输出 SQL 标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来确定对象的所有关系。这让该转储更加兼容标准，但是取决于该转储中对象的历史，该转储可能无法正常恢复。 -? --help 显示有关 sys_dumpall 命令行参数的帮助并退出。下列命令行选项控制数据库连接参数。 -d connstr --dbname=connstr 以一个连接字符串的形式，指定用来连接到服务器的参数。这个选项被称为--dbname 是为了和其他客户端应用一致，但是因为 sys_dumpall 需要连接多个数据库，连接字符串中的数据库名将被忽略。使用-l 选项指定一个数据库，该数据库被用于初始连接，这将转储全局对象并且发现需要转储哪些其他数据库。 -h host --host=host 指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认是从 KINGBASE_HOST 环境变量中取得（如果被设置），否则将尝试一次 Unix 域套接字连接。 -l dbname --database=dbname 指定要连接到哪个数据库转储全局对象以及发现要转储哪些其他数据库。如果没有指定，将会使用 kingbase 数据库，如果 kingbase 不存在，就使用 template1。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 KINGBASE_PORT 环境变量中（如果被设置），否则使用编译在程序中的默认值。 -U username --username=username 指定连接数据库的用户。 -w --no-password 不发出口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 ~/.kbpass 或 ~/. encpwd 文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有用户来输入口令。 -W --password 强制 sys_dumpall 在连接到一个数据库之前提示要求一个口令。这个选项不是必须的，因为如果服务器要求口令认证，sys_dumpall 将自动提示要求一个口令。但是， sys_dumpall 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下，值得键入-W 来避免额外的连接尝试。注意对每个要被转储的数据库，口令提示都会再次出现。通常，最好设置一个 ~/.kbpass 或 ~/.encpwd 文件来减少口令手工输入。 --role=rolename 81 第 14 章 SYS_DUMPALL 指定一个用来创建该转储的角色名。这个选项导致 sys_dump 在连接到数据库后发出一个 SET ROLE rolename 命令。当已认证用户（由-U 指定）缺少 sys_dump 所需的特权但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。 14.4 环境变量 KINGBASE_HOST 指定要连接的主机名。 KINGBASE_PORT 指定要连接的服务器的端口号。 KINGBASE_USER 指定要使用哪个用户连接数据库。 PGOPTIONS 指定要使用那些参数连接到数据库。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always、auto、never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci。 14.5 错误信息诊断无 14.6 示例要转储所有数据库： $ sys_dumpall > db.out 仅转储全局对象，不转储数据库： $ sys_dumpall -g >db.out 仅转储角色，不转储表空间： 82 第 14 章 SYS_DUMPALL $ sys_dumpall -r >db.out 要从这个文件重新载入数据库，你可以使用： $ ksql -f db.out kingbase 这里你连接哪一个数据库并不重要，因为由 sys_dumpall 创建的脚本将包含合适的命令来创建和连接到被保存的数据库。一个例外是，如果指定了--clean，则开始时必须连接到 kingbase 数据库，该脚本将立即尝试删除其他数据库，并且这种动作对于已连接上的这个数据库将会失败。 14.7 备注因为 sys_dumpall 在内部调用 sys_dump，所以，一些诊断消息可以参考 sys_dump。即使当用户的目的是把转储脚本恢复到一个空的集簇中，--clean 选项也有用武之地。--clean 的使用让该脚本删除并且重建内建的 kingbase 和 template1 数据库，确保这两个数据库保持与源集簇中相同的属性（例如 locale 和编码）。如果不用这个选项，这两个数据库将保持它们现有的数据库级属性以及任何已有的内容。一旦恢复，建议在每个数据库上运行 ANALYZE，这样优化器就可以得到有用的统计信息。你也可以运行 vacuumdb -a -z 来分析所有数据库。不应该预期转储脚本运行到结束都不出错。特别是由于脚本将为源集簇中已有的每一个角色发出 CREATE ROLE 语句，对于初始的超级用户当然会得到一个“role already exists”错误，除非目标集簇用一个不同的初始超级用户名完成的初始化。这种错误是无害的并且应该被忽略。--clean 选项的使用很可能会产生额外的有关于不存在对象的无害错误消息，不过可以通过加上--if-exists 减少这类错误消息。 sys_dumpall 要求所有需要的表空间目录在进行恢复之前就必须存在；否则，数据库创建就会由于在非默认位置创建数据库而失败。 14.8 参考可能的错误情况请查看sys_dump 。 83 第 15 章 SYS_ISREADY 15章 sys_isready 第 15.1 简介 sys_isready —检查 KingbaseES 服务器的连接状态 sys_isready 是一个用于检查 KingbaseES 数据库服务器的连接状态的工具。通过退出状态展示连接检查的结果。 15.2 命令行参数 sys_isready [ connection-option ...] [ option ...] 15.3 参数说明 -d dbname --dbname=dbname 指定要连接的数据库名。如果这个参数包含一个 = 记号或者以一个合法的 URI 前缀（kingbase://或 kingbase://）开头，它会被视作一个 “conninfo“字符串。 -h hostname --host=hostname 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它会被视作 Unix 域套接字的目录。 --port=port --port=port 指定服务器监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。默认值取自 KINGBASE_PORT 环境变量。如果环境变量没有设置，则默认值使用编译时指定的端口（通常是 54321）。 -q --quiet 不显示状态消息。用于脚本编程的场景。 -t seconds --timeout=seconds 84 第 15 章 SYS_ISREADY 尝试连接时，在返回服务器未响应之前等待的最大秒数。设置为 0 则禁用。默认值是 3 秒。 -U username --username=username 作为用户 “username“连接数据库，而不是用默认用户。 -V --version 打印 sys_isready 版本并退出。 -? --help 显示有关 sys_isready 命令行参数的帮助并退出。 15.4 环境变量和大部分其他 KingbaseES 工具相似，sys_isready 也使用 libkci 支持的环境变量。环境变量 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never。 15.5 错误信息诊断无 15.6 示例标准用法： $ sys_isready /tmp:54321 - accepting connections $ echo $? 0 使用连接参数运行连接到处于启动中的 KingbaseES 集簇（该启动中状态通常只持续 1~2 秒）： $ sys_isready -h localhost -p 5433 localhost:5433 - rejecting connections $ echo $? 1 使用连接参数运行连接到无响应的 KingbaseES 集簇： 85 第 15 章 SYS_ISREADY $ sys_isready -h someremotehost someremotehost:54321 - no response $ echo $? 2 15.7 备注要获得服务器状态，不一定需要提供正确的用户名、口令或数据库名。但如果提供了不正确的值，服务器将会记录一次失败的尝试连接。 15.7.1 退出状态如果服务器正常接受连接，sys_isready 返回 0 给 shell；如果服务器拒绝连接（例如处于启动阶段）则返回 1；如果连接尝试没有被响应则返回 2；如果没有尝试（例如由于非法参数）则返回 3。 15.8 参考无 86 第 16 章 SYS_RECEIVEWAL 16章 sys_receivewal 第 16.1 简介 sys_receivewal —从 KingbaseES 服务器上以流的方式得到预写式日志 sys_receivewal 是用来从一个正在运行的 KingbaseES 集群以流的方式得到 WAL 日志，通过使用流复制协议接收 WAL 日志，将其写入到本地 WAL 文件，并存放于指定目录下。在做时间点恢复（PITR）时，这个目录作为归档位置使用。当 KingbaseES 服务器上产生 WAL 日志时，sys_receivewal 以流的方式实时接收 WAL 日志，不需要像 archive_command 那样等待段完成。因此，在使用 sys_receivewal 时不必设置 archive_timeout 。 sys_receivewal 与 KingbaseES 后备服务器上的 WAL 接收进程不同，默认情况下，仅在关闭 WAL 文件时才会将缓存中的 WAL 数据刷新到 WAL 文件中。如果需要将缓存中的 WAL 数据实时刷新到 WAL 文件中，就必须指定选项--synchronous。由于 sys_receivewal 不会重做接收的 WAL，当 synchronous_commit 设置为 remote_apply 时，不能设置它为同步备用，否则它将作为一个永远无法达到同步状态的备用服务器，主服务器为了等待它达到同步状态而阻塞所有事务提交。为了避免出现这种情况，在有 sys_receivewal 的场景下尽量不要将 synchronous_commit 设置为 remote_apply，如果必须要设置为 remote_apply，那么应该将 synchronous_standby_names 配置为一个不包含 sys_receivewal 对应 application_name 的值。建立流复制连接的用户必须是超级用户或者是具有 REPLICATION 权限（见角色属性）的用户，并且 sys_hba. conf 必须设置为允许以流复制的方式连接 KingbaseES 服务器，同时服务器也必须配置足够大的 max_wal_senders ，以便于保证至少提供一个可用的会话供流复制传输时使用。如果该连接断开，或者它一开始就由于非致命错误而没有建立连接，sys_receivewal 会不断尝试重新建立流复制连接，直到建立成功或人为中断。如果不希望无限重试下去，则可以使用-n 参数来指定重试次数，一旦达到指定次数仍然没有重连成功就会自动退出。在没有出现致命错误的情况下，sys_receivewal 会一直运行，如果有 WAL 数据则会接收，没有则一直等待。可以使用 SIGINT 信号（Control+C）终止它。 16.2 命令行参数 sys_receivewal [ option ...] 87 第 16 章 SYS_RECEIVEWAL 16.3 参数说明 -D directory --directory=directory 本地目录，接收 WAL 数据后生成的 WAL 文件会保存在该目录下。该参数为必选参数。 -E lsn --endpos=lsn 当接收到的 WAL 的 LSN 大于此参数指定的 LSN 后，会停止接收，并且以正常退出状态 0 退出。如果当前接收的 WAL 记录的 LSN 和指定的 “lsn“完全相等，会正常处理并继续接收，直到接收的 WAL 的 LSN 大于指定值。 --if-not-exists 当指定--create-slot 并且具有指定名称的槽已经存在的情况下不要抛出错误。 -n --no-loop 出现连接错误后立刻退出。如果不指定此参数，连接错误后会不断尝试重连。 --no-sync 这个选项可以使 sys_receivewal 不强制将 WAL 数据刷回磁盘。这样会更快，但是一旦此程序或者操作系统崩溃，WAL 文件会丢失没有刷回磁盘的 WAL 数据，最严重时会导致 WAL 文件损坏。通常情况下，这个选项对于测试时有用，但是在对生产部署进行 WAL 归档时不应该使用。这个选项与--synchronous 不兼容。 -s interval --status-interval=interval 该选项指定发送回服务器状态包之间的间隔秒数，这样可以让我们更方便地监控服务器的进度。当设定值为 0 时，则完全禁用定期状态更新。为了避免发生超时断开连接的情况，当服务器请求时，仍然会发送更新。默认值为 10 秒。 -S slotname --slot=slotname 要求 sys_receivewal 使用现有的复制槽。当使用这个选项时，sys_receivewal 向服务器上报刷新位置，显示每段是何时同步到磁盘的，当服务器不需要该段时，可以移除它。当 sys_receivewal 的复制客户端在服务器上配置为同步后备时，则使用复制槽将会向服务器上报刷新位置，但只有在关闭 WAL 文件时才会上报。因此，该配置将导致主服务器上的事务等待时间过长，并且实际效果也无法令人满意。为了避免这种情况，还必须指定选项--synchronous（见下文）。 --synchronous 在收到 WAL 数据后立刻刷入磁盘，同时在刷新后立即将状态包发送回服务器（不考虑--status-interval）。如果 sys_receivewal 的复制客户端在服务器上配置为同步后备，则应该指定该选项，以确保能及时向服务器发送响应。 88 第 16 章 SYS_RECEIVEWAL -v --verbose 开启详细输出模式。 -Z level --compress=level 启用 WAL 日志上的 gzip 压缩，并且指定压缩级别（共分为 0 到 9 个等级，0 是不压缩而 9 是最大压缩）。所有的文件名后面都将自动添加后缀.gz。下列命令行选项指定数据库连接参数。 -d connstr --dbname=connstr 以连接字符串的方式来指定用于连接到服务器的参数。为了和其他客户端应用程序保持一致，该选项又被称为--dbname。但是由于 sys_receivewal 并没有连接到集群中任何特定的数据库，因此将忽略掉连接字符串中的数据库名称。 -h host --host=host 指定运行服务器的主机名。如果该值以斜线开始，则用作 Unix 域套接字的目录。默认值取自 KINGBASE_HOST 环境变量的值（前提条件是已设置该环境变量），否则通过重试 Unix 域套接字连接来获得。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或者本地 Unix 域套接字文件扩展名。默认值取自 KINGBASE_PORT 环境变量中（前提条件是已设置该环境变量），否则使用在程序中编译的默认值。 -U username --username=username 指定哪个用户连接。 -w --no-password 不需要密码认证。如果服务器要求密码认证，而密码无法通过其他方式获得（例如.kbpass 文件），那么连接将会失败。这个选项一般用于无法交互（输入密码）的批处理任务或脚本。 -W --password 在连接到数据库之前，强制 sys_receivewal 提示输入密码。这个选项不是必选的。当服务器要求密码认证时，sys_receivewal 将自动提示输入密码。如果服务器需要密码认证，sys_receivewal 会先尝试连接，连接失败后再提示需要输入密码，用户输入密码后再次尝试连接。这种情况下，使用-W 参数，sys_receivewal 会直接提示输入密码，不会连接失败后再提示。为了指定物理复制槽，sys_receivewal 可以执行下列两种操作中的其中一种： --create-slot 使用--slot 中指定的名称创建新的物理复制槽，然后退出。 --drop-slot 删除--slot 中指定名称的复制槽，然后退出。 89 第 16 章 SYS_RECEIVEWAL 其他选项也可用： -V --version 打印 sys_receivewal 的版本信息，然后退出。 -? --help 显示关于 sys_receivewal 命令行参数的帮助信息，然后退出。 16.4 环境变量和大多数其他 KingbaseES 工具一样，这个工具也使用 libkci 支持的环境变量。环境变量 SYS_COLOR 指定是否在诊断消息中使用颜色。取值范围有 always, auto, never。 16.5 错误信息诊断无 16.6 示例从服务器 mydbserver 上流式接收 WAL 日志，并且将它存储在本地目录/opt/Kingbase/ES/V9/archive： $ sys_receivewal -h mydbserver -D /opt/Kingbase/ES/V9/archive 从服务器 mydbserver 上流式接收 WAL 日志，并且将它存储在本地目录/opt/Kingbase/ES/V9/archive，当出现错误时，不再循环重试，而是立刻退出： $ sys_receivewal -h mydbserver -D /opt/Kingbase/ES/V9/archive -n 从服务器 mydbserver 上流式接收 WAL 日志，并且将它存储在本地目录/opt/Kingbase/ES/V9/archive，用户名为 test，端口号为 54321，密码为 123456，并且将接收到的日志进行压缩处理，压缩级别为 6 ： $ sys_receivewal -h mydbserver -D /opt/Kingbase/ES/V9/archive -U test -p 54321 -W 123456 -Z 6 从服务器 mydbserver 上流式接收 WAL 日志，并且将它存储在本地目录/opt/Kingbase/ES/V9/archive，指定复制槽为 test，并以这个名称创建新的物理复制槽，该槽已经存在时不要抛出错误： $ sys_receivewal -h mydbserver -D /opt/Kingbase/ES/V9/archive -S test --create-slot --if-not-exists 从服务器 mydbserver 上流式接收 WAL 日志，并且将它存储在本地目录/opt/Kingbase/ES/V9/archive，指定复制槽为 test，并且在收到 WAL 数据后立即刷入磁盘，同时在刷新后立即将状态返回给服务器： 90 第 16 章 SYS_RECEIVEWAL $ sys_receivewal -h mydbserver -D /opt/Kingbase/ES/V9/archive -S test --synchronous 16.7 备注当使用 sys_receivewal 而不是 archive_command 作为主要的 WAL 备份方式时，强烈建议使用复制槽，否则在没有任何信息（不管是来自 archive_command 还是来自复制槽）能够显示 WAL 流已经归档到什么程度的情况下，服务器在备份好 WAL 日志文件之前就已经重用或者移除它们。不过需要注意的是，如果接收方没有及时获取 WAL 数据，则复制槽将会填满服务器的整个磁盘空间。如果在源集群上启用了组权限，sys_receivewal 将会在接收到的 WAL 文件上保留组权限。 16.7.1 退出状态在 SIGINT 信号终止 sys_receivewal 时，退出状态将以正常状态 0 退出（由于这是以正常的方式结束的，因此这不是一种错误）。而对于致命错误或者其他信号，退出状态将为非 0。 16.8 参见 sys_basebackup 91 第 17 章第 17.1 SYS_RESTORE 17章 sys_restore 简介 sys_restore —从一个由sys_dump 创建的归档文件恢复一个 KingbaseES 数据库 sys_restore 是一个用来从sys_dump 创建的非文本格式归档恢复 KingbaseES 数据库的工具。它将发出必要的命令把该数据库重建成它被保存时的状态。这些归档文件还允许 sys_restore 选择恢复哪些内容或者在恢复前对恢复项重排序。这些归档文件被设计为可以在不同的架构之间迁移。 sys_restore 可以在两种模式下操作。如果指定了一个数据库名称，sys_restore 会连接那个数据库并且把归档内容直接恢复到该数据库中。否则，会创建一个脚本，其中包含着重建该数据库所必要的 SQL 命令，它会被写入到一个文件或者标准输出。这个脚本输出等效于sys_dump 的纯文本输出格式。因此，一些控制输出的选项与sys_dump 的选项类似。显然，sys_restore 无法恢复不在归档文件中的信息。例如，如果归档使用“以 INSERT 命令转储数据”选项创建，sys_restore 将无法使用 COPY 语句装载数据。 17.2 命令行参数 sys_restore [ connection-option ...] [ option ...] [ filename ] 17.3 参数说明 sys_restore 接受下列命令行参数。 filename 指定要恢复的归档文件（对于一个目录格式的归档则是目录）的位置。如果没有指定，则使用标准输入。 -a --data-only 92 第 17 章 SYS_RESTORE 只恢复数据，不恢复模式（数据定义）。如果在归档中存在，将恢复表数据、大对象和序列值。这个选项类似于指定--section=data，但是由于历史原因两者不完全相同。 -c --clean 在重新创建数据库对象之前清除（丢弃）它们（除非使用了--if-exists，如果有对象在目标数据库中不存在，这可能会生成一些无害的错误消息）。 -C --create 在恢复一个数据库之前先创建它。如果还指定了--clean，在连接到目标数据库之前丢弃并且重建它。如果使用--create，sys_restore 还会恢复数据库的注释（如果有）以及与其相关的配置变量设置，也就是任何提到过这个数据库的 ALTER DATABASE ... SET ... 和 ALTER ROLE ... IN DATABASE ... SET ... 命令。不管是否指定--no-acl，都会恢复数据库本身的访问权限。在使用这个选项时，-d 提到的数据库只用于发出初始的 DROP DATABASE 和 CREATE DATABASE 命令。所有要恢复到该数据库名中的数据都出现在归档中。 -d dbname --dbname=dbname 连接到数据库 “dbname“并且直接恢复到该数据库中。 -e --exit-on-error 在发送 SQL 命令到该数据库期间如果碰到一个错误就退出。默认行为是继续并且在恢复结束时显示一个错误计数。 -E --skip-errors 使用复制时跳过错误行。 -f filename --file=filename 为生成的脚本或列表（当使用-l 时）指定输出文件。为 stdout 则使用中划线-。 -F format --format=format 指定归档的格式。并不一定要指定该格式，因为 sys_restore 将会自动决定格式。如果指定，可以是下列之一： c custom 归档采用sys_dump 的自定义格式。 d directory 归档是一个目录归档。 t tar 归档是一个 tar 归档。 -I index --index=index 只恢复命名索引的定义。可以通过写多个-I 开关指定多个索引。 93 第 17 章 SYS_RESTORE -j number-of-jobs --jobs=number-of-jobs 使用并发任务运行 sys_restore 中最耗时的部分—载入数据、创建索引或者创建约束。对于一个运行在多处理器机器上的服务器，这个选项能够大幅度减少恢复一个大型数据库的时间。每一个任务是一个进程或者一个线程，这取决于操作系统，它们都使用一个独立的服务器连接。这个选项的最佳值取决于服务器、客户端以及网络的硬件设置。因素包括 CPU 的内核数量和磁盘设置。一个好的建议是将该值设置为服务器上 CPU 的内核数量，但是在很多情况下，更大的值也能导致更快的恢复时间。当然，过高的值会由于超负荷反而导致性能降低。这个选项只支持自定义和目录归档格式。输入必须是一个常规文件或目录（例如，不能是一个管道）。当发出一个脚本而不是直接连接到数据库服务器时会忽略这个选项。还有，多任务不能和选项--single-transaction 一起用。 -K --key=encryptkey 还原数据时候指定加密秘钥。1. 密钥长度不能超过 16 字节。2. 只能用于二进制格式输出。 -l --list 列出归档的内容的表格。这个操作的输出能被用作-L 选项的输入。注意如果把-n 或-t 这样的过滤开关与-l 一起使用，它们将会限制列出的项。 -L list-file --use-list=list-file 只恢复在 “list-file“中列出的归档元素，并且按照它们出现在该文件中的顺序进行恢复。注意如果把-n 或-t 这样的过滤开关与-L 一起使用，它们将会进一步限制要恢复的项。 “list-file“通常是编辑一个-l 操作的输出来创建。行可以被移动或者移除，并且也可以通过在行首放一个（;）将其注释掉。例子见下文。 -n shcema --schema=schema 只恢复在命名模式中的对象。可以用多个-n 开关来指定多个模式。这可以与-t 选项组合在一起只恢复一个指定的表。 -N schema --exclude-schema=schema 不恢复命名方案中的对象。可以用多个-N 开关指定多个要被排除的方案。如果对同一个方案名称同时给出了-n 和-N，则-N 会胜出并且该方案会被排除。 --view-only 只恢复视图。 --recreate-view 最后重新创建视图。 -g namespace --fromSchema=schema 源模式（默认大小写不敏感），恢复源模式中的对象到-G 指定的目标模式中去，与-G 一起使用。可以用多个-g 开关来指定多个源模式。这可以与-t 选项组合在一起只恢复一个指定的表。 94 第 17 章 SYS_RESTORE --from-schema-case-sensitive 设置源模式大小写敏感。 -G namespace --targetSchema=schema 目标模式，恢复-g 指定的源模式中的对象到目标模式中，与-g 一起使用。可以用多个-G 开关来指定多个目标模式。注意: -g/-G 必须一起使用，不能和-n 同时使用。和-n 类似，-g/-G 仅恢复模式下的内容，不恢复模式定义。注意: -g 指定的源模式和-G 指定的目标模式一一对应，或者目标模式数量等于一且源模式数量大于一。 -O --no-owner 不要输出将对象的所有权设置为与原始数据库匹配的命令。默认情况下，sys_restore 会发出 ALTER OWNER 或者 SET SESSION AUTHORIZATION 语句来设置已创建的模式对象的所有权。除非到该数据库的初始连接是一个超级用户（或者拥有脚本中所有对象的同一个用户）建立的，这些语句将会失败。通过-O，任何用户名都可以用于初始连接，并且这个用户将会拥有所有创建的对象。 -P function-name(argtype [, ...]) --function=function-name(argtype [, ...]) 只恢复命名函数。要注意拼写函数的名称和参数，使它们正好就是出现在转储文件的内容表中的名称和参数。可以使用多个-P 开关指定多个函数。 -R --no-reconnect 这个选项已废弃，但是出于向后兼容的目的，系统仍然保留。 -s --schema-only 只恢复归档中的模式（数据定义）不恢复数据。这个选项与--data-only 相反。它与指定--section=pre-data --section=post-data 相似，但是由于历史原因并不完全相同。（不要把这个选项和--schema 选项弄混，后者把词“schema”用于一种不同的含义）。 -S username --superuser=username 指定在禁用触发器时要用的超级用户名。只有使用--disable-triggers 时这个选项才相关。 -t table --table=table 只恢复命名表的定义和数据。“table”可以是视图、物化视图、序列或外部表。可以写上多个-t 开关可以选择多个表。这个选项可以和-n 选项结合在一起指定一个特定模式中的表。注意: 在指定-t 时，sys_restore 不会尝试恢复所选表可能依赖的任何其他数据库对象。因此，无法确保 95 第 17 章 SYS_RESTORE 能成功地把一个特定表恢复到一个干净的数据库中。注意: 这个标志的行为和sys_dump 的-t 标志不一样。在 sys_restore 中当前没有任何通配符匹配的规定，也不能在其-t 选项中包括模式的名称。而且，虽然sys_dump 的-t 标志也会转储选中表的附属对象（例如索引），但是 sys_restore 的-t 标志不包括这些附属对象。 -T trigger --trigger=trigger 只恢复命名触发器。可以用多个-T 开关指定多个触发器。 -v --verbose 指定冗长模式。 -V --version 打印该 sys_restore 的版本并退出。 -x --no-privileges --no-acl 防止恢复访问权限（授予/收回命令）。 -1 --single-transaction 将恢复作为单一事务执行（即把发出的命令包裹在 BEGIN/COMMIT 中）。这可以确保要么所有命令完全成功，要么没有任何改变。这个选项隐含了--exit-on-error。 --disable-triggers 只有在执行只恢复数据的恢复时，这个选项才相关。它指示 sys_restore 在装载数据时，执行命令临时禁用目标表上的触发器。如果您在表上有参照完整性检查或者其他触发器，并且您不希望在数据载入期间调用它们时，请使用这个选项。目前，为--disable-triggers 发出的命令必须以超级用户身份完成。因此您还应该用-S 指定一个超级用户名，或者更好的方法是以一个 KingbaseES 超级用户的身份运行 sys_restore。 --enable-row-security 只有在恢复具有行安全性的表的内容时，这个选项才相关。默认情况下，sys_restore 将把 row_security 设置为 off 来确保将所有数据恢复到表中。如果用户没有足够绕过行安全性的权限，那么会抛出一个错误。这个参数指示 sys_restore 把 row_security 设置为 on 允许用户尝试恢复启用了行安全性的表的内容。如果用户没有从转储向表中插入行的权限，这仍将失败。注意当前这个选项还要求转储处于 INSERT 格式，因为 COPY FROM 不支持行安全性。 --if-exists 使用条件命令（即增加一个 IF EXISTS 子句）删除数据库对象。只有指定了--clean 时，这个选项才有效。 --no-comments 96 第 17 章 SYS_RESTORE 即便归档中包含注释也不输出恢复注释的命令。 --no-data-for-failed-tables 默认情况下，即便表的创建命令失败（例如因为表已经存在），也会恢复表数据。通过这个选项，将跳过此类表的数据。如果目标数据库已经包含了想要的表内容，则此行为很有用。例如，KingbaseES 扩展（如 KGIS ）的辅助表可能已经被载入到目标数据库中，指定这个选项就能阻止把重复的或者废弃的数据载入到这些表中。只有当直接恢复到一个数据库中时，这个选项才有效，在产生 SQL 脚本输出时这个选项不会产生效果。 --no-publications 即便归档中包含 publication 也不输出恢复 publication 的命令。 --no-security-labels 不要输出恢复安全标签的命令，即使归档中包含安全标签。 --no-subscriptions 即便归档中包含 subscription 也不输出恢复 subscription 的命令。 --no-tablespaces 不输出命令选择表空间。通过这个选项，所有的对象都将创建在恢复时的默认表空间中。 --section=sectionname 只恢复命名的段。段的名称可以是 pre-data、data 或者 post-data。可以多次指定这个选项来选择多个段。默认值是恢复所有段。数据段包含实际的表数据以及大对象定义。post-data 项由索引定义、触发器、规则和除已验证的检查约束之外的约束构成。pre-data 项由所有其他数据定义项构成。 --strict-names 要求每一个模式（-n/--schema）以及表（-t/--table）限定词匹配备份文件中至少一个模式/表。 --use-set-session-authorization 输出 SQL 标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来决定对象拥有权。这会让转储更加兼容标准，但是根据该转储中对象的历史记录，可能无法正确恢复。 -? --help 显示有关 sys_restore 命令行参数的帮助，并且退出。 sys_restore 也接受下列用于连接参数的命令行参数： -h host --host=host 指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认取自 KINGBASE_HOST 环境变量（如果设置了），否则将尝试 Unix 域套接字连接。 -p port --port=port 97 第 17 章 SYS_RESTORE 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 KINGBASE_PORT 环境变量中（如果设置了），否则使用编译在程序中的默认值。 -U username --username=username 要作为哪个用户连接。 -w --no-password 不发出密码提示。如果服务器要求密码验证，并且密码不能其他方式获得（例如一个.kbpass 文件），那么连接尝试将失败。这个选项对于在没有用户输入密码的批处理任务和脚本中有用。 -W --password 强制 sys_restore 在连接到一个数据库之前提示输入密码。这个选项不是必须的，因为如果服务器要求密码验证，sys_restore 将自动提示输入密码。但是， sys_restore 将浪费一次连接尝试来发现服务器需要密码。在某些情况下，值得键入-W 来避免额外的连接尝试。 --role=rolename 指定一个用来创建该转储的角色名。这个选项导致 sys_restore 在连接到数据库后发出一个 SET ROLE “rolename“命令。当已认证用户（由-U 指定）缺少 sys_restore 所需的权限，但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。 17.4 环境变量 KINGBASE_HOST 指定要连接的主机名。 KINGBASE_PORT 指定要连接的服务器的端口号。 KINGBASE_USER 指定要使用哪个用户连接数据库。 PGOPTIONS 指定要使用那些参数连接到数据库。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 98 第 17 章 17.5 SYS_RESTORE 错误信息诊断当使用-d 选项指定一个直接数据库连接时，sys_restore 在内部执行 SELECT 语句。如果您运行 sys_restore 时出现问题，确定您能够从正在使用的数据库中选择信息，例如 ksql 。此外，libkci 前端-后端库所使用的任何默认连接设置和环境变量都将适用。当还原 PL/SQL 对象（函数、存储过程、触发器、包、object type）报错对象不存在，报错信息为“ERROR: relation ”XXX” does not exist”，可尝试在新库的配置文件（kingbase.conf）打开 ora_func_style 参数后再次备份还原。 17.6 示例假设我们已经以自定义格式转储了一个叫做 mydb 的数据库： $ sys_dump -Fc mydb > db.dump 要删除该数据库并且从转储中重新创建它： $ dropdb mydb $ sys_restore -C -d kingbase db.dump -d 开关中提到的数据库可以是任何已经存在于集群中的数据库，sys_restore 只会用它来为 mydb 发出 CREATE DATABASE 命令。通过-C，数据总是会被恢复到出现在归档文件的数据库名中。要把转储重新载入到一个名为 newdb 的新数据库中： $ createdb -T template0 newdb $ sys_restore -d newdb db.dump 注意我们不使用-C，而是直接连接到要恢复到其中的数据库。还要注意我们是从 template0 而不是 template1 创建了该数据库，以保证它最初是空的。要对数据库项重排序，首先需要转储归档的表内容： $ sys_restore -l db.dump > db.list 列表文件由一个头部和一些行组成，这些行每一个都用于一个项，例如： ; ; Archive created at Mon Sep 14 13:55:39 2009 ; dbname: DBDEMOS ; TOC Entries: 81 ; Compression: 9 ; Dump Version: 1.10-0 ; Format: CUSTOM 99 第 17 章 ; Integer: 4 bytes ; Offset: 8 bytes ; Dumped from database version: 8.3.5 ; Dumped by sys_dump version: 8.3.8 SYS_RESTORE ; ; ; Selected TOC Entries: ; 3; 2615 2200 SCHEMA - public pasha 1861; 0 0 COMMENT - SCHEMA public pasha 1862; 0 0 ACL - public pasha 317; 1247 17715 TYPE public composite pasha 319; 1247 25899 DOMAIN public domain0 pasha 分号表示开始一段注释，行首的数字表明了分配给每个项的内部归档 ID。文件中的行可以被注释掉、删除以及重排序。例如： 10; 145433 TABLE map_resolutions kingbase ;2; 145344 TABLE species kingbase ;4; 145359 TABLE nt_header kingbase 6; 145402 TABLE species_records kingbase ;8; 145416 TABLE ss_old kingbase 把这样一个文件作为 sys_restore 的输入将会只恢复项 10 和 6，并且先恢复 10 再恢复 6。 $ sys_restore -L db.list db.dump 17.7 备注如果你的数据库集群对于 template1 数据库有任何本地添加，要注意将 sys_restore 的输出载入到一个真正的空数据库。否则，您可能由于增加对象的重复定义而遇到错误。要创建一个不带任何本地添加的空数据库，从 template0 而不是 template1 复制它，例如： CREATE DATABASE foo WITH TEMPLATE template0; 下面将详细介绍 sys_restore 的局限性。 • 在恢复数据到一个已经存在的表中并且使用了选项--disable-triggers 时，sys_restore 会在插入数据之前发出命令禁用用户表上的触发器，然后在完成数据插入后重新启用它们。如果恢复在中途停止，可能会让系统目录处于错误的状态。 • sys_restore 不能有选择地恢复大对象，例如只恢复特定表的大对象。如果一个归档包含大对象，那么所有的大对象都会被恢复，如果通过-L、-t 或者其他选项进行了排除，它们一个也不会被恢复。 100 第 17 章 SYS_RESTORE sys_dump 的局限性详见sys_dump 文档。一旦完成恢复，应该在每一个被恢复的表上运行 ANALYZE，这样优化器能得到有用的统计信息。更多信息请见 KingbaseES 数据库维护指南。 17.8 参考 sys_dump , sys_dumpall , ksql 101 第 18 章 KBBENCH 18章 kbbench 第 18.1 简介 kbbench —在 KingbaseES 上运行一个基准测试 kbbench 是一种在 KingbaseES 上运行基准测试的简单程序。它可能在并发的数据库会话中一遍一遍地运行相同序列的 SQL 命令，并且计算平均事务率（每秒的事务数）。默认情况下，kbbench 会测试一种基于 TPC-B 但是要更宽松的场景，其中在每个事务中涉及五个 SELECT、UPDATE 以及 INSERT 命令。但是，通过编写自己的事务脚本文件很容易用来测试其他情况。 kbbench 的典型输出像这样： transaction type: scaling factor: 10 query mode: simple number of clients: 10 number of threads: 1 number of transactions per client: 1000 number of transactions actually processed: 10000/10000 tps = 85.184871 (including connections establishing) tps = 85.296346 (excluding connections establishing) 前六行报告一些最重要的参数设置。接下来的行报告完成的事务数以及预期的事务数（后者就是客户端数量与每个客户端事务数的乘积），除非运行在完成之前失败，这些值应该是相等的（在-T 模式中，只有实际的事务数会被打印出来）。最后两行报告每秒的事务数，分别代表包括和不包括开始数据库会话所花时间的情况。默认的类 TPC-B 事务测试要求预先设置好特定的表。可以使用-i（初始化）选项调用 kbbench 来创建并且填充这些表（当你在测试一个自定义脚本时，你不需要这一步，但是需要按你自己的测试需要做一些设置工作）。初始化类似这样： kbbench -i [ other-options ] dbname 其中 “dbname“是要在其中进行测试的预先创建好的数据库的名称（你可能还需要-h、-p 或-U 选项来指定如何连接到数据库服务器）。 102 第 18 章注意: kbbench -i KBBENCH 会创建四个表 kbbench_accounts、kbbench_branches、kbbench_history 以及 kbbench_tellers，如果同名表已经存在会被先删除。如果你已经有同名表，一定注意要使用另一个数据库！在默认的情况下“比例因子”为 1，这些表初始包含的行数为： table # of rows --------------------------------kbbench_branches 1 kbbench_tellers 10 kbbench_accounts 100000 kbbench_history 0 你可以使用-s（比例因子）选项增加行的数量。-F（填充因子）选项也可以在这里使用。一旦你完成了必要的设置，你就可以用不包括-i 的命令运行基准，也就是： kbbench [ options ] dbname 在近乎所有的情况中，你将需要一些选项来做一次有用的测试。最重要的选项是-c（客户端数量）、-t（事务数量）、-T（时间限制）以及-f（指定一个自定义脚本文件）。完整的列表见下文。 18.2 命令行参数 kbbench -i [ option ...] [ dbname ] kbbench [ option ...] [ dbname ] 18.3 参数说明下面分成三个部分。数据库初始化期间使用的选项和运行基准时会使用不同的选项，但也有一些选项在两种情况下都使用。 18.3.1 初始化选项 kbbench 接受下列命令行初始化参数： -i --initialize 要求调用初始化模式。 -I init_steps --init-steps=init_steps 103 第 18 章 KBBENCH 只执行选出的一组普通初始化步骤。“init_steps“指定要被执行的初始化步骤，每一个步骤使用一个字符代表。每一个步骤都以指定的顺序被调用。默认是 dtgvp。可用的步骤是： d（删除）删除任何已有的 kbbench 表。 t（创建表）创建标准 kbbench 场景使用的表，即 kbbench_accounts、kbbench_branches、 kbbench_history 以及 kbbench_tellers。 g（生成数据）生成数据并且装入到标准的表中，替换掉已经存在的任何数据。 v（清理）在标准的表上调用 VACUUM。 p（创建主键）在标准的表上创建主键索引。 f（创建外键）在标准的表之间创建外键约束（注意这一步默认不会被执行）。 -F fillfactor --fillfactor=fillfactor 用给定的填充因子创建表 kbbench_accounts、kbbench_tellers 以及 kbbench_branches。默认是 100。 -n --no-vacuum 在初始化期间不执行清理（这个选项会抑制 v 初始化步骤，即便在-I 中指定了该步骤）。 -q --quiet 把记录切换到安静模式，只是每 5 秒产生一个进度消息。默认的记录会每 100000 行打印一个消息，这经常会在每秒钟输出很多行。 -s scale_factor --scale=scale_factor 将生成的行数乘以比例因子。例如，-s 100 将在 kbbench_accounts 表中创建 10,000,000 行。默认为 1。当比例为 20,000 或更高时，用来保存账号标识符的列（aid 列）将切换到使用更大的整数（bigint），这样才能足以保存账号标识符。 --foreign-keys 在标准的表之间创建外键约束（如果 f 在初始化步骤序列中不存在，这个选项会把它加入）。 --index-tablespace=index_tablespace 在指定的表空间而不是默认表空间中创建索引。 --tablespace=tablespace 104 第 18 章 KBBENCH 在指定的表空间而不是默认表空间中创建表。 --unlogged-tables 把所有的表创建为非日志记录表而不是永久表。 18.3.2 基准选项 kbbench 接受下列命令行基准参数： -b scriptname[@weight] --builtin=scriptname[@weight] 把指定的内建脚本加入到要执行的脚本列表中。@ 之后是一个可选的整数权重，它允许调节抽取该脚本的可能性。如果没有指定，它会被设置为 1。可用的内建脚本有：tpcb-like、simple-update 和 select-only。这里也接受内建名称无歧义的前缀缩写。如果用上特殊的名字 list，将会显示内建脚本的列表并且立刻退出。 -c clients --client=clients 模拟的客户端数量，也就是并发数据库会话数量。默认为 1。 -C --connect 为每一个事务建立一个新连接，而不是只为每个客户端会话建立一个连接。这对于度量连接开销有用。 -d --debug 打印调试输出。 -D varname=value --define=varname=value 定义一个由自定义脚本（见下文）使用的变量。允许多个-D 选项。 -f filename[@weight] --file=filename[@weight] 把一个从 “filename“读到的事务脚本加入到被执行的脚本列表中。@ 后面是一个可选的整数权重，它允许调节抽取该测试的可能性。详见下文。 -j threads --jobs=threads kbbench 中的工作者线程数量。在多 CPU 机器上使用多于一个线程会有用。客户端会尽可能均匀地分布到可用的线程上。默认为 1。 -l --log 把与每一个事务相关的信息写到一个日志文件中。详见下文。 -L limit --latency-limit=limit 对持续超过 “limit“毫秒的事务进行独立的计数和报告，这些事务被认为是迟到（late）了的事务。在使用限流措施时（--rate=...），滞后于计划超过 “limit“毫秒并且因此没有希望满足延迟限制的事务根本不会被发送给服务器。这些事务被认为是*被跳过（skipped）* 的事务，它们会被单独计数并且报告。 105 第 18 章 KBBENCH -M querymode --protocol=querymode 要用来提交查询到服务器的协议： • simple：使用简单查询协议。 • extended 使用扩展查询协议。 • prepared：使用带预备语句的扩展查询语句。在 prepared 模式中，kbbench 重用从第二个查询迭代开始的解析分析结果，因此 kbbench 运行速度快于其他模式。默认是简单查询协议。 -n --no-vacuum 在运行测试前不进行清理。如果你在运行一个不包括标准的表 kbbench_accounts、 kbbench_branches、kbbench_history 和 kbbench_tellers 的自定义测试场景时，这个选项是必需的。 -N --skip-some-updates 运行内建的简单更新脚本。这是-b simple-update 的简写。 -P sec --progress=sec 每 “sec“秒显示进度报告。该报告包括运行了多长时间、从上次报告以来的 tps 以及从上次报告以来事务延迟的平均值和标准偏差。如果低于限流值（-R），延迟会相对于事务预定的开始时间（而不是实际的事务开始时间）计算，因此其中也包括了平均调度延迟时间。 -r --report-latencies 在基准结束后，报告平均的每个命令的每语句等待时间（从客户端的角度来说是执行时间）。详见下文。 -R rate --rate=rate 按照指定的速率执行事务而不是尽可能快地执行（默认行为）。该速率以 tps（每秒事务数）形式给定。如果目标速率高于最大可能速率，则该速率限制不会影响结果。该速率的目标是按照一条泊松分布的调度时间线开始事务。期望的开始时间表会基于客户端第一次开始的时间（而不是上一个事务结束的时间）前移。这种方法意味着当事务超过它们的原定结束时间时，更迟的那些有机会再次追赶上来。当限流措施被激活时，运行结束时报告的事务延迟是从预订的开始时间计算而来的，因此它包括每一个事务不得不等待前一个事务结束所花的时间。该等待时间被称作调度延迟时间，并且它的平均值和最大值也会被单独报告。关于实际事务开始时间的事务延迟（即在数据库中执行事务所花的时间）可以用报告的延迟减去调度延迟时间计算得到。如果把--latency-limit 和--rate 一起使用，当一个事务在前一个事务结束时已经超过了延迟限制时，它可能会滞后非常多，因为延迟是从计划的开始时间计算得来。这类事务不会被发送给服务器，而是一起被跳过并且被单独计数。 106 第 18 章 KBBENCH 一个高的调度延迟时间表示系统无法用选定的客户端和线程数按照指定的速率处理事务。当平均的事务执行时间超过每个事务之间的调度间隔时，每一个后续事务将会落后更多，并且随着测试运行时间越长，调度延迟时间将持续增加。发生这种情况时，你将不得不降低指定的事务速率。 -s scale_factor --scale=scale_factor 在 kbbench 的输出中报告指定的比例因子。对于内建测试，这并非必需；正确的比例因子将通过对 kbbench_branches 表中的行计数来检测。不过，当只测试自定义基准（-f 选项）时，比例因子将被报告为 1（除非使用了这个选项）。 -S --select-only 执行内建的只有选择的脚本。是-b select-only 简写形式。 -t transactions --transactions=transactions 每个客户端运行的事务数量。默认为 10。 -T seconds --time=seconds 运行测试这么多秒，而不是为每个客户端运行固定数量的事务。-t 和-T 是互斥的。 -v --vacuum-all 在运行测试前清理所有四个标准的表。在没有用-n 以及-v 时，kbbench 将清理 kbbench_tellers 和 kbbench_branches 表，并且截断 kbbench_history。 --aggregate-interval=seconds 聚集区间的长度（单位是秒）。仅可以与-l 选项一起使用。通过这个选项，日志会包含针对每个区间的概要数据，如下文所述。 --log-prefix=prefix 设置--log 创建的日志文件的文件名前缀。默认是 kbbench_log。 --progress-timestamp 当显示进度（选项-P）时，使用一个时间戳（Unix 时间）取代从运行开始的秒数。单位是秒，在小数点后是毫秒精度。这可以有助于比较多种工具生成的日志。 --random-seed=SEED 设置随机数生成器种子。为系统的随机数生成器提供种子，然后随机数生成器会产生一个初始生成器状态序列，每一个线程一个状态。“SEED“的值可以是：time（默认值，种子基于当前时间）、rand（使用一种强随机源，如果没有可用的源则失败）或者一个无符号十进制整数值。一个 kbbench 脚本中会显式（random... 函数）地或者隐式地（如--rate 使用随机数生成器调度事务）调用随机数生成器。在被明确设置时，用作种子的值会显示在终端上。还可以通过环境变量 PGBENCH_RANDOM_SEED 提供用于 “SEED“的值。为了确保所提供的种子影响所有可能的使用，把这个选项放在第一位或者使用环境变量。明确地设置种子允许准确地再生一个 kbbench 运行，对随机数而言。因为随机状态是针对每个线程管理，这意味着如果每一个线程有一个客户端并且没有外部或者数据依赖，则对于一个相同的调用就会有完全相同的 kbbench 运行。从一种统计的角度来看，再生运行不是什么好主意，因为它能隐藏性能可变性 107 第 18 章 KBBENCH 或者不正当地改进性能，即通过命中前一次运行的相同页面来改进性能。不过，它也可以对调试起到很大帮助作用，例如重新运行一种导致错误的棘手用例。请善用。 --sampling-rate=rate 采样率，在写入数据到日志时被用来减少日志产生的数量。如果给出这个选项，只有指定比例的事务被记录。1.0 表示所有事务都将被记录，0.05 表示只有 5% 的事务会被记录。在处理日志文件时，记得要考虑这个采样率。例如，当计算 TPS 值时，你需要相应地乘以这个数字（例如，采样率是 0.01，你将只能得到实际 TPS 的 1/100）。 18.3.3 普通选项 kbbench 接受下列命令行普通参数： -h hostname --host=hostname 数据库服务器的主机名 -p port --port=port 数据库服务器的端口号 -U login --username=login 要作为哪个用户连接 -V --version 打印 kbbench 版本并退出。 -? --help 显示有关 kbbench 命令行参数的信息，并且退出。 18.4 示例 18.4.1 创建测试库 create database kbbenchdb; 18.4.2 初始化测试库 ./kbbench -i kbbenchdb -p 54321 -d test -U system 108 第 18 章 KBBENCH dropping old tables... 注意: 表 "kbbench_accounts" 不存在注意: 表 "kbbench_branches" 不存在注意: 表 "kbbench_history" 不存在注意: 表 "kbbench_tellers" 不存在 creating tables... generating data... 100000 of 100000 tuples (100%) done (elapsed 0.02 s, remaining 0.00 s) vacuuming... creating primary keys... done. 18.4.3 以 32 并发 32 线程为例，进行测试 ./kbbench -M extended -c 32 -j 32 -T 300 -d kbbenchdb transaction type: scaling factor: 1 query mode: extended number of clients: 32 number of threads: 32 duration: 300 s number of transactions actually processed: 257117 latency average = 37.339 ms tps = 857.009526 (including connections establishing) tps = 857.031634 (excluding connections establishing) 18.5 备注 18.5.1 在 kbbench 中实际执行的“事务”是什么？ kbbench 执行从指定列表中随机选中的测试脚本。它们包括带有-b 的内建脚本和带有-f 的用户提供的自定义脚本。每一个脚本可以在其后用 @ 指定一个相对权重，这样可以更改该脚本的抽取概率。默认权重是 1。权重为 0 的脚本会被忽略。默认的内建事务脚本（也会被-b tpcb-like 调用）会在每个事务上发出七个从 aid、tid、bid 和 delta 中随机选择的命令。该场景来自于 TPC-B 基准，但并不是真正的 TPC-B，只是名字像而已。 1. BEGIN; 2. UPDATE kbbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; 109 第 18 章 KBBENCH 3. SELECT abalance FROM kbbench_accounts WHERE aid = :aid; 4. UPDATE kbbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; 5. UPDATE kbbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; 6. INSERT INTO kbbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); 7. END; 如果选择 simple-update 内建脚本（还有-N），第 4 和 5 步不会被包括在事务中。这将避免更新那些表中的内容，但是它会让该测试用例更不像 TPC-B。如果选择 select-only 内建脚本（还有-S），只会发出 SELECT。 18.5.2 自定义脚本 kbbench 支持通过从一个文件中（-f 选项）读取事务脚本替换默认的事务脚本（如上文所述）来运行自定义的基准场景。在这种情况中，一个“事务”就是一个脚本文件的一次执行。脚本文件包含一个或者多个被分号终结的 SQL 命令。空行以及以--开始的行会被忽略。脚本文件也可以包含 “元命令”，它会由 kbbench 自身解释，详见下文。注意: 在 KingbaseES V8R2 之前，脚本文件中的 SQL 命令被新行终结，因此命令不能跨行。现在需要号来分隔连续的 SQL 命令（如果 SQL 命令后面跟着一个元命令则不需要一个分号）。如果需要创建一个能在新旧版本 kbbench 下工作的脚本文件，要确保把每个 SQL 命令写在一个由分号终结的行中。对脚本文件有一种简单的变量替换功能。变量名必须由字母（包括非拉丁字母）、数字以及下划线构成。如上所述，变量可以用命令行的 -D 选项设置，或者按下文所说的使用元命令设置。除了用-D 命令行选项预先设置的任何变量之外，还有一些被自动预先设置的变量，它们被列在表 1 中。一个用-D``为这些变量值指定的值会优先于自动的预设值。一旦被设置，可以在 SQL 命令中写\ ``:“variablename“ 来插入一个变量的值。当运行多于一个客户端会话时，每一个会话拥有它自己的变量集合。kbbench 支持在一条语句中使用最多 255 个变量。表 18.5.1: 自动变量变量简介 client_id 标识客户端会话的唯一编号（从零开始） default_seed 默认在哈希函数中使用的种子 random_seed 随机数生成器种子（除非用-D 重载） scale 当前的缩放因子 110 第 18 章 KBBENCH 脚本文件元命令以反斜线（\）开始并且通常延伸到行的末尾，不过它们也能够通过写一个反斜线回车继续到额外行。一个元命令和它的参数用空白分隔。支持的元命令是： \gset [prefix] 这个命令可以用来结束 SQL 查询，代替结束分号 (;). 使用此命令时，前面的 SQL 查询将返回一行，其中的列存储在以列名命名的变量中，如果提供了 “prefix“作为前缀。下面的示例将第一个查询的最终帐户余额放入变量 “abalance“，并使用第三个查询的整数填充变量 “p_two“和 “p_three“。第二个查询的结果被丢弃。 UPDATE kbbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset -- compound of two queries SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ \if expression \elif expression \else \endif 这一组命令实现了可嵌套的条件块，类似于 ksql 的`\if expression 。条件表达式与\set 的相同，非零值会被解释为真。 \set varname expression 设置变量 “varname“为一个从 “expression“计算出的值。该表达式可以包含 NULL 常量、布尔常量 TRUE 和 FALSE、54321 这样的整数常量、3.14159 这样的 double 常量、对变量的引用:“variablename“、操作符（保持它们通常的 SQL 优先级和结合性）、函数调用、SQL CASE 一般条件表达式以及括号。函数和大部分操作符在 NULL 输入上会返回 NULL。对于条件目的，非零数字值是 TRUE，数字零值以及 NULL 是 FALSE。太大或太小的整数和双常数，以及整数算术运算符 (+, -, * 和/) 在溢出时引发错误。在没有为 CASE 提供最终的 ELSE 子句时，默认值是 NULL。 \set ntellers 10 * :scale \set aid (1021 * random(1, 100000 * :scale)) % \ (100000 * :scale) + 1 \set divx CASE WHEN :x <> 0 THEN :y/:x ELSE NULL END \sleep number [ us | ms | s ] 导致脚本执行休眠指定的时间，时间的单位可以是微妙（us）、毫秒（ms）或者秒（s）。如果单位被忽略，则秒是默认值。“number“要么是一个整数常量，要么是一个引用了具有整数值的变量的: “variablename“。 111 第 18 章 KBBENCH \sleep 10 ms \setshell varname command [ argument ... ] 用给定的 “argument“设置变量 “varname“为 shell 命令 “command“的结果。该命令必须通过它的标准输出返回一个整数值。 “command“和每个 “argument“要么是一个文本常量，要么是一个引用了一个变量的:“variablename“。如果你想要使用以冒号开始的 “argument“，在 “argument“的开头写一个额外的冒号。 \setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_ colon \shell command [ argument ... ] 与\setshell 相同，但是结果被抛弃。 \shell command literal_argument :variable ::literal_starting_with_colon 18.5.3 内建操作符表” 按优先级升序排列的 kbbench 操作符” 中列举的算数、按位、比较以及逻辑操作符都被编译到了 kbbench 中并且可以被用于 set_ 中出现的表达式中。表 18.5.2: 按优先级升序排列的 kbbench 操作符操作符简介示例结果 OR 逻辑或 5 or 0 TRUE AND 逻辑与 3 and 0 FALSE NOT 逻辑非 not false TRUE IS [NOT] (NULL|TRUE|FALSE) 值测试 1 is null FALSE IS NULL | NOT NULL 空测试 1 notnull TRUE = 等于 5 = 4 FALSE <> 不等于 5 <> 4 TRUE != 不等于 5 != 5 FALSE < 小于 5 < 4 FALSE <= 小于等于 5 <= 4 FALSE 见续表 112 第 18 章 KBBENCH 表 18.5.2 – 续表操作符简介示例结果 > 大于 5 > 4 TRUE >= 大于等于 5 >= 4 TRUE | 整数按位 OR 1 | 2 3 # 整数按位 XOR 1 # 3 2 & 整数按位 AND 1 & 3 1 ~ 整数按位 NOT ~ 1 -2 << 整数按位左移 1 << 2 4 >> 整数按位右移 8 >> 2 2 + 加 5 + 4 9 - 减 3 - 2.0 1.0 * 乘 5 * 4 20 / 除（整数会截断 5 / 3 1 结果） % 取模 3 % 2 1 - 取负 - 2.0 -2.0 18.5.4 内建函数表”kbbench 函数” 中列出的函数被编译在 kbbench 中，并且可能被用在出现于 set_ 的表达式中。 random 函数使用均匀分布生成值，即所有的值都以相等的概率从指定的范围中抽出。random_exponential、 random_gaussian 以及 random_zipfian 函数要求一个额外的 double 参数，它决定分布的精确形状。 • 对于指数分布，“parameter“通过在 “parameter“处截断一个快速下降的指数分布来控制分布，然后投影到边界之间的整数上。确切地来说， f(x)=exp(-parameter*(x-min)/(max-min+1))/(1-exp(-parameter)) 然后 “min“和 “max“之间（包括两者）的值 “i“会被以概率 f(i) - f(i + 1) 抽出。直观上，“parameter“越大，接近 “min“的值会被越频繁地访问，并且接近 “max“的值会被越少访问。“parameter“越接近 0，访问分布会越平坦（更均匀）。该分布的粗近似值是范围中当时被抽取 “parameter“% 次接近 “min“的最频繁的 1% 值。“parameter“值必须严格为正。 113 第 18 章 KBBENCH • 对于高斯分布，区间被映射到一个在左边-parameter 和右边 +parameter 截断的标准正态分布（经典钟型高斯曲线）。区间中间的值更可能被抽到。准确地说，如果 PHI(x) 是标准正态分布的累计分布函数，均值 mu 定义为 (max + min) / 2.0，有 f(x)=PHI(2.0*parameter*(x-mu)/(max-min+1))/(2.0*PHI(parameter)-1) 则 “min“和 “max“（包括两者）之间的值 “i“被抽出的概率是：f(i + 0.5) - f(i - 0.5)。直观上，“parameter“越大，靠近区间终端的值会被越频繁地抽出，并且靠近上下界两端的值会被更少抽出。大约 67% 的值会被从中间 1.0 / parameter 的地方抽出，即均值周围 0.5 / parameter 的地方。并且 95% 的值会被从中间 2.0 / parameter 的地方抽出，即均值周围 1.0 / parameter 的地方。例如，如果 “parameter“是 4.0，67% 的值会被从该区间的中间四分之一（1.0 / 4.0）抽出（即从 3.0 / 8.0 到 5.0 / 8.0）。并且 95% 的值会从该区间的中间一半（2.0 / 4.0）抽出（第二和第三四分位）。允许最小的 “参数 “值为 2.0。 • random_zipfian 生成一个有界的 Zipfian 分布。 “parameter“定义该分布有多么倾斜。“parameter“越大，绘制越接近间隔开头的值越频繁。分布是这样的，假设范围从 1 开始，绘制 “k“与绘制 “k+1“的概率之比为 ((k+1)/“k“)**“parameter“。例如， random_zipfian(1, ..., 2.5) 生成值 1 大约 (2/1)**2.5 = 5.66 次，比 2 更频繁，它本身被产生 (3/2)**2.5 = 2.76 次，比 3 更频繁，依此类推。 kbbench 的实现基于”Non-Uniform Random Variate Generation”, Luc Devroye, p. 550-551，施普林格 1986。由于该算法的局限性，“parameter“值被限制在 [1.001,1000] 范围内。哈希函数 hash、hash_murmur2 以及 hash_fnv1a 接受一个输入值和一个可选的种子参数。在没有提供种子的情况下，会使用:default_seed 的值，该变量会被随机地初始化，除非用命令行的-D 选项重载。哈希函数可以被用于分散 random_zipfian 或 random_exponential 这样的随机函数的分布。例如，下列 kbbench 脚本模拟了社交媒体和博客平台上很常见的真实负载，其中少数账号产生了过量的负载： \set r random_zipfian(0, 100000000, 1.07) \set k abs(hash(:r)) % 1000000 在一些情况中需要几个不同的分布，它们彼此之间不相关并且隐式的随机数参数在此时就能派上用场： \set k1 abs(hash(:r, :default_seed + 123)) % 1000000 \set k2 abs(hash(:r, :default_seed + 321)) % 1000000 作为一个例子，内建的类 TPC-B 事务的全部定义是： \set aid random(1, 100000 * :scale) \set bid random(1, 1 * :scale) \set tid random(1, 10 * :scale) \set delta random(-5000, 5000) BEGIN; UPDATE kbbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; SELECT abalance FROM kbbench_accounts WHERE aid = :aid; UPDATE kbbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; UPDATE kbbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; 114 第 18 章 KBBENCH INSERT INTO kbbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); END; 这个脚本允许该事务的每一次迭代能够引用不同的、被随机选择的行（这个例子也展示了为什么让每一个客户端会话有其自己的变量很重要—否则它们不会独立地接触不同的行）。 18.5.5 对每个事务做日志通过-l 选项（但是没有--aggregate-interval 选项），kbbench 把关于每个事务的信息写入到一个日志文件。该日志文件将被命名为 prefix.“nnn“，其中 “prefix“默认为 kbbench_log，而 “nnn“是 kbbench 进程的 PID。前缀可以用--log-prefix 选项更改。如果-j 选项是 2 或者更高（有多个工作者线程），那么每一个工作者线程将会有它自己的日志文件。第一个工作者的日志文件的命名将和标准的单工作者情况相同。其他工作者的额外日志文件将被命名为 prefix.“nnn“.“mmm“，其中 “mmm“是每个工作者的一个序列号，这种序列号从 1 开始编。日志的格式是： client_id transaction_no time script_no time_epoch time_us [schedule_lag] 其中 “client_id“表示哪个客户端会话运行该事务，“transaction_no“是那个会话已经运行了多少个事务的计数， “time“是以微秒计的总共用掉的事务时间，“script_no“标识了要使用哪个脚本文件（当用-f 或者-b 指定多个脚本时有用），而 “time_epoch“/“time_us“是一个 Unix 纪元格式的时间戳以及一个显示事务完成时间的以微秒计的偏移量（适合于创建一个带有分数秒的 ISO 8601 时间戳）。域 “schedule_lag“是事务的预定开始时间和实际开始时间之间的差别，以微秒计。只有使用--rate 选项时它才存在。当--rate 和--latency-limit 同时被使用时，一个被跳过的事务的 “time“会被报告为 skipped。这里是在单个客户端运行中生成的一个日志文件的片段： 0 199 2241 0 1175850568 995598 0 200 2465 0 1175850568 998079 0 201 2513 0 1175850569 608 0 202 2038 0 1175850569 2663 另一个例子使用的是--rate=100 以及--latency-limit=5（注意额外的 “schedule_lag“列）： 0 81 4621 0 1412881037 912698 3005 0 82 6173 0 1412881037 914578 4304 0 83 skipped 0 1412881037 914578 5217 0 83 skipped 0 1412881037 914578 5099 0 83 4722 0 1412881037 916203 3108 0 84 4142 0 1412881037 918023 2333 0 85 2465 0 1412881037 919759 740 在这个例子中，事务 82 迟到了，因为它的延迟（6.173 ms）超过了 5ms 限制。接下来的两个事务被跳过，因为它们在开始之前就已经迟到了。 115 第 18 章 KBBENCH 在能够处理大量事务的硬件上运行一次长时间的测试时，日志文件可能变得非常大。--sampling-rate 选项能被用来只记录事务的一个随机采样。 18.5.6 聚合的日志记录通过--aggregate-interval 选项，日志文件会使用一种不同的格式： interval_start num_of_transactions latency_sum latency_2_sum min_latency max_latency [lag_sum lag_2_sum min_lag max_lag] 其中 “interval_start“是区间的开始（作为一个 Unix 纪元的时间戳）、“num_transactions“是该区间中的事务数、“sum_latency“是该区间中事务时延的总量、“sum_latency_2“是该区间中事务时延的平方和、“min_latency“是该区间中的最小时延、“max_latency“是该区间中的最大时延。接下来的字段 “sum_lag“、“sum_lag_2“、 “min_lag“以及 “max_lag“只有在使用--rate 选项时才存在。它们提供每个事务要等待前一个事务完成所花的时间的统计信息，即每个事务的计划启动时间与实际启动时间之间的差值。最后一个字段 “skipped“只有在使用--latency-limit 选项时才存在。它对因为启动过完被跳过的事务进行计数。每一个事务被计入在其提交时的区间中。这里是一些输出示例： 1345828501 5601 1542744 483552416 61 2573 1345828503 7884 1979812 565806736 60 1479 1345828505 7208 1979422 567277552 59 1391 1345828507 7685 1980268 569784714 60 1398 1345828509 7073 1979779 573489941 236 1411 注意虽然纯（非聚合）日志文件显示为每个事务使用了哪个脚本，但聚合日志却不包含索引。因此如果你需要针对每个脚本的数据，你需要自行聚合数据。 18.5.7 每语句延迟通过-r 选项，kbbench 收集每一个客户端执行的每一个语句花费的事务时间。然后在基准完成后，它会报告这些值的平均值，作为每个语句的延迟。对于默认脚本，输出看起来会像这样： starting vacuum...end. transaction type: scaling factor: 1 query mode: simple number of clients: 10 number of threads: 1 number of transactions per client: 1000 number of transactions actually processed: 10000/10000 116 第 18 章 KBBENCH latency average = 15.844 ms latency stddev = 2.715 ms tps = 618.764555 (including connections establishing) tps = 622.977698 (excluding connections establishing) statement latencies in milliseconds: 0.002 \set aid random(1, 100000 * :scale) 0.005 \set bid random(1, 1 * :scale) 0.002 \set tid random(1, 10 * :scale) 0.001 \set delta random(-5000, 5000) 0.326 BEGIN; 0.603 UPDATE kbbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; 0.454 SELECT abalance FROM kbbench_accounts WHERE aid = :aid; 5.528 UPDATE kbbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; 7.335 UPDATE kbbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; 0.371 INSERT INTO kbbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); 1.212 END; 如果指定了多个脚本文件，会为每一个脚本文件单独报告平均值。注意为每个语句的延迟计算收集额外的时间信息会增加一些负荷。这将拖慢平均执行速度并且降低计算出的 TPS。降低的总量会很显著地依赖于平台和硬件。对比使用和不适用延迟报告时的平均 TPS 值是评估时间开销是否明显的好方法。 18.5.8 良好的做法很容易使用 kbbench 产生完全没有意义的数字。这里有一些指导可以帮你得到有用的结果。排在第一位的是，永远不要相信任何只运行了几秒的测试。使用-t 或-T 选项让运行持续至少几分钟，这样可以用平均值去掉噪声。在一些情况中，你可能需要数小时来得到能重现的数字。多运行几次测试是一个好主意，这样可以看看你的数字是不是可以重现。对于默认的类 TPC-B 测试场景，初始化的比例因子（-s）应该至少和你想要测试的最大客户端数量一样大（-c），否则你将主要在度量更新争夺。在 kbbench_branches 表中只有-s 行，并且每个事务都想更新其中之一，因此-c 值超过-s 将毫无疑问地导致大量事务被阻塞来等待其他事务。默认的测试场景也对表被初始化了多久非常敏感：表中死亡行和死亡空间的累积会改变结果。要理解结果，你必须跟踪更新的总数以及何时发生清理。如果开启了自动清理，它可能会在度量的性能上产生不可预估的改变。 kbbench 的一个限制是在尝试测试大量客户端会话时，它自身可能成为瓶颈。这可以通过在数据库服务器之外的一台机器上运行 kbbench 来缓解，不过必须是具有低网络延迟的机器。甚至可以在多个客户端机器上针对同一个数据库服务器并发地运行多个 kbbench 实例。 117 第 18 章 18.5.9 KBBENCH 安全性如果不可信用户能够访问没有采用安全方案使用模式的数据库，不要在那个数据库中运行 kbbench。kbbench 使用非限定名称并且不会操纵搜索路径。 18.5.10 退出状态状态 0 表示运行成功。退出状态 1 表示静态问题，比如无效的命令行选项。运行过程中的错误，如数据库错误或脚本中的问题，将导致退出状态 2。在后一种情况下，kbbench 将打印部分结果。 18.6 参考无 118 第 19 章 VACUUMDB 19章 vacuumdb 第 19.1 简介 vacuumdb —对一个 KingbaseES 数据库进行垃圾收集和分析 vacuumdb 是用于清理一个 KingbaseES 数据库的工具。vacuumdb 也将产生由 KingbaseES 查询优化器所使用的内部统计信息。 vacuumdb 是 SQL 命令 VACUUM 的一个包装器。在通过这个工具和其他方法访问服务器来清理和分析数据库之间没有实质性的区别。 19.2 命令行参数 vacuumdb [connection-option...] [ option ...] [ --table | -t table [( column [,...] )] ] ... [ dbname ] vacuumdb [connection-option...] [ option ...] --all | -a 19.3 参数说明 vacuumdb 接受下列命令行参数： -a --all 清理所有数据库。 [-d] dbname [--dbname=]dbname 指定要被清理或分析的数据库名。如果没有被指定并且没有使用-a（或--all），数据库名将从环境变量 KINGBASE_DATABASE 中读出。如果环境变量也没有设置，指定给该连接的用户名将用作数据库名。 --disable-page-skipping 119 第 19 章 VACUUMDB 根据可见性映射的内容禁用跳过页面。注意: 此选项仅适用于在 KingbaseES V8R2 及以后版本的服务器上运行。 -e --echo 回显 vacuumdb 生成并发送给服务器的命令。 -f --full 执行“完全”清理。 -F --freeze 强有力地“冻结”元组。 -j njobs --jobs=njobs 通过同时运行 “njobs“ 个命令来并行执行清理或者分析命令。这个选项会减少处理的时间，但是它也会增加数据库服务器的负载。 vacuumdb 将开启 “njobs“个到数据库的连接，因此请确认你的 max_connections 设置足够高以容纳所有的连接。注意如果某些系统目录被并行处理，使用这种模式加上 -f（FULL）选项可能会导致死锁失败。 --min-mxid-age mxid_age 仅在具有至少 “mxid_age“的多重 ID 年龄的表上执行真空或分析命令。此设置对要处理的表进行优先排序以防止多重 ID。ID 封装非常有用 (请参阅 KingbaseES 数据库维护指南). 对于此选项，多重 ID 年龄的关系是主关系及其相关的 TOAST 表中的最大年龄 (如果存在的话)。由于由 vacuumdb 发出的命令也将处理 TOAST 表以获得必要的关系，因此不需要单独考虑。注意: 此选项仅适用于在 KingbaseES V8R2 及以后版本的服务器上运行。 --min-xid-age xid_age 仅在事务 ID 年龄至少为 “xid_age“的表上执行清除或分析命令。此设置对于为要处理的表设置优先级以防止事务 ID 包装非常有用 (请参阅 KingbaseES 数据库维护指南。) 对于此选项，事务 ID 年龄的关系是主关系及其关联的最大年龄 TOAST 表 (如果存在的话)。由于由 vacuumdb 发出的命令也将处理 TOAST 表以获得必要的关系，因此不需要单独考虑。注意: 此选项仅适用于在 KingbaseES V8R2 及以后版本的服务器上运行。 -q --quiet 不显示进度消息。 120 第 19 章 VACUUMDB --skip-locked 跳过不能立即锁定以进行处理的关系。注意: 此选项仅适用于在 KingbaseES V8R2 及以后版本的服务器上运行。 -t table [ (column [,...]) ] --table=table [ (column [,...]) ] 只清理或分析 “table“。列名只能和--analyze 或--analyze-only 选项一起被指定。通过写多个-t 开关可以清理多个表。提示: 如果你指定列，你可能必须转义来自 shell 的括号（见下面的示例）。 -v --verbose 在处理期间打印详细信息。 -V --version 打印 vacuumdb 版本并退出。 -z --analyze 也计算优化器使用的统计信息。 -Z --analyze-only 只计算优化器使用的统计信息（不清理）。 --analyze-in-stages 与--analyze-only 相似，只计算优化器使用的统计信息（不做清理）。使用不同的配置设置运行分析的几个（目前是 3 个）阶段以更快地产生可用的统计信息。这个选项对分析一个刚从转储恢复或者通过 sys_upgrade 得到的数据库有用。这个选项将尝试尽可能快地创建一些统计信息来让该数据库可用，然后在后续的阶段中产生完整的统计信息。 -? --help 显示有关 vacuumdb 命令行参数的帮助并退出。 vacuumdb 也接受下列命令行参数用于连接参数： -h host --host=host 指定运行服务器的机器的主机名。如果该值以一个斜线开始，它被用作 Unix 域套接字的目录。 -p port --port=port 指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展。 -U username --username=username 121 第 19 章 VACUUMDB 要作为哪个用户连接。 -w --no-password 从不发出一个口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个.kbpass 文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有一个用户来输入口令。 -W --password 强制 vacuumdb 在连接到一个数据库之前提示要求一个口令。这个选项不是必不可少的，因为如果服务器要求口令认证，vacuumdb 将自动提示要求一个口令。但是， vacuumdb 将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下值得用-W 来避免额外的连接尝试。 --maintenance-db=dbname 指定要连接到来发现哪些其他数据库应该被清理的数据库名。如果没有指定，将使用 kingbase 数据库。而如果它也不存在，将使用 template1。 19.4 环境变量 KINGBASE_DATABASE KINGBASE_HOST KINGBASE_PORT KCIUSER 默认连接参数 SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。 19.5 错误信息诊断在有困难时，可以在 VACUUM 和 ksql 中找潜在问题和错误消息的讨论。数据库服务器必须运行在目标主机上。同样，任何 libkci 前端库使用的默认连接设置和环境变量都将适用于此。 19.6 示例要清理数据库 test： $ vacuumdb test 要清理和为优化器分析一个名为 bigdb 的数据库： 122 第 19 章 VACUUMDB $ vacuumdb --analyze bigdb 要清理在名为 xyzzy 的数据库中的一个表 foo，并且为优化器分析该表的 bar 列： $ vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy 19.7 备注 vacuumdb 可能需要多次连接到 KingbaseES 服务器，每次都询问一个口令。在这种情况下有一个 ~/.kbpass 文件会很方便。 19.8 参考 VACUUM 123 第 20 章 VACUUMLO 20章 vacuumlo 第 20.1 简介 vacuumlo —从 KingbaseES 数据库中移除“孤儿”lo 大对象 vacuumlo 是一个从 KingbaseES 数据库中移除“孤儿”lo 大对象的独立程序。“孤儿”lo 大对象是指其 OID 不被任何 oid 或 lo 列数据引用。在命令行中指定的所有数据库都将被处理。 20.2 命令行参数 vacuumlo [ option ...] dbname ... 20.3 参数说明 vacuumlo 接受下列命令行参数： -l limit --limit=*limit* 在每一个事务中移除不超过 “limit“个大对象（默认值为 1000）。因为移除每一个 lo 大对象时服务器都将要加一个锁，所以在一个事务中移除过多的 LO 会有超过 max_locks_per_transaction 的风险。如果你想在一个事务中就完成所有的移除工作，请设置 limit 为 0。 -n --dry-run 不做实际移除，只显示将会移除哪些对象。 -v --verbose 输出一些进度消息。 -V --version 124 第 20 章 VACUUMLO 打印 vacuumlo 的版本并退出。 -? --help 显示关于 vacuumlo 的命令行参数，并且退出。 vacuumlo 也接受下列命令行参数用于连接： -h host --host=host 数据库服务器的主机名。 -p port --port=port 数据库服务器的端口。 -U username --username=username 用于连接的用户名。 -w --no-password 不要发出一个口令提示。如果服务器要求口令认证并且没有其他方式可以提供一个口令（例如一个. kbpass 文件），连接尝试将会失败。这个选项可用于批处理任务以及脚本，因为在这些情况下不会有用户输入口令。 -W --password 强制 vacuumlo 在连接到数据库之前提示要求一个口令。这个选项不是不可缺少的，因为如果服务器要求口令认证，vacuumlo 会自动提示要求一个口令。但是， vacuumlo 将会浪费一次连接尝试来了解到服务器需要口令。在某些情况，值得用-W 来避免这种额外的连接尝试。 20.4 环境变量 KINGBASE_HOST KINGBASE_PORT KCIUSER 默认连接参数。此实用程序与大多数其他 KingbaseES 实用程序一样，还使用了 libkci 支持的环境变量。 20.5 错误信息诊断无 125 第 20 章 VACUUMLO 20.6 示例无 20.7 备注 vacuumlo 按照下列方法工作：首先 vacuumlo 建立一个临时表，其中包含所选择数据库中所有大对象的 OID。然后它会扫描数据库中所有类型为 oid 或 lo 的列（注意只有这两种类型会被考虑），并且从临时表中移除在这些列中出现过的 OID。临时表中剩下的 lo 大对象会被认为是“孤儿”lo 大对象并被移除。 20.8 参考无 126 第 21 章 WRAP 21章 wrap 第 21.1 简介 wrap ——一种 sql 语句加密工具 wrap 命令行工具输入文件为含有一个或多个 PL/SQL 或者 PL/pgSQL 语句的文本文件，通过 wrap 命令行工具加密后，输出一个加密后的文本文件。可用于加密的语句： PL/SQL 语句加密： CREATE [ OR REPLACE ] FUNCTION function_name CREATE [ OR REPLACE ] PROCEDURE procedure_name CREATE [ OR REPLACE ] PACKAGE BODY package_name PL/pgSQL 语句加密： CREATE [ OR REPLACE ] FUNCTION function_name CREATE [ OR REPLACE ] PROCEDURE procedure_name 21.2 命令行参数 wrap iname=input_file [ oname=output_file ] 21.3 参数说明 input_file 输入文件名称。 output_file 127 第 21 章 WRAP 输出文件名称，当不指定 oname 属性时，默认使用输入文件名称作为输出文件的名称，并使用 plb 作为后缀名。 21.4 环境变量无 21.5 错误信息诊断（1）当输入文件不存在时存在报错： PL/SQL Wrapper error: Couldn't open input file xxx.sql。（2）当命令属性输入不正确时报错： PL/SQL Wrapper error: Couldn't process command line arguments. （3）当文件中 CREATE [ OR REPLACE ] 语句存在解析错误时会在最后统一输出报错信息，但会将该语句同样记录在指定文件中，然后继续加密语句。报错信息如下： PL/SQL Wrapper Processing xxx.sql to xxx.plb PL/SQL Wrapper error at line 3 Outputting source and continuing. 21.6 示例无 21.7 备注使用说明需要注意的是加密 plpgsql 语句，只支持 $$...$$ 的 pg 语法加密。plsql 对象同样可以使用 $$..$$ 的 pg 语法进行加密。注意事项 128 第 21 章 WRAP a. 不能对 trigger 进行加密，如果需要对 trigger 进行加密请直接加密函数，然后通过触发器去调用该函数即可。 b. 如果输入文本中的 plsql、plpgsql 语句不符合加密要求，则保留在输出文本中。 c. 如果有注释写在语句头内，则会直接显示注释内容，如：“create or replace /nihao123/ procedure pro...”。并且语句内的注释保留。 d. 通过加密工具加密的语句如果注释是‘--’则会被删除；如果是则保留在输出文本中。 e. WRAP 加密工具分隔符可以使用 set SQLTERM ，使用方式请参照 KSQL 工具。默认使用‘/’，如需要加密多个语句需要在 CREATE [ OR REPLACE ] 语句之间加上‘/’。 f. 输出文本可以复制拷贝，同时可以直接在数据库中执行，并且也可以将语句单独执行。 g. 不支持 EDITIONABLE|NONEDITIONABLE 对象加密。 h. Wrap 命令行工具不能够（也不需要）连接数据库服务器，直接在操作系统的命令行模式下执行即可。 21.8 参考 dbms_ddl 129 版权声明版权声明北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修改、传播、翻译成其他语言、将其全部或部分用于商业用途。免责声明本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通知或者提示的情况下对手册内容进行修改的权利。本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 130 服务周期承诺服务周期承诺由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。表 1: KingbaseES 产品生命周期里程碑关键里程碑点定义产品发布日期产品正式发布版本，即 GA（general availability）版本的发布日期。停止销售日期正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。停止功能升级日期在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功能维护等服务。停止功能维护日期在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务停止安全维护日期在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。产品服务终止日期停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的所有服务支持（包括服务热线和远程/现场支持）。服务周期策略金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。服务终止策略金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 131 服务周期承诺开方式宣布产品服务终止日期。 132