KingbaseES服务器应用参考手册.pdf

KingbaseES 服务器应用参考手册金仓数据库管理系统 KingbaseES 文档版本：V9（V009R001C001B0024）发布日期：2023 年 10 月 12 日北京人大金仓信息技术股份有限公司目目录录第 1 章前言 1 1.1 适用读者 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 相关文档 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.3 术语 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.4 手册约定 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 第 2 章 initdb 4 2.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 第 3 章 kingbase 10 3.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.3.1 通用选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.3.2 开发人员选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.7 缺陷 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.8 单用户模式 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 3.9 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.10 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 第 4 章 sys_archivecleanup 18 4.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 I 目录 4.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.7 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 第 5 章 sys_checksums 21 5.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 5.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 第 6 章 sys_controldata 24 6.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 第 7 章 sys_ctl 26 7.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 7.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 7.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 用于 Windows 的选项 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.3.1 7.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 7.5 文件 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.6 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.7 示例 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.7.1 启动服务器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.7.2 停止服务器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 7.7.3 重启服务器 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.7.4 显示服务器状态 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.8 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 7.9 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 第 8 章 sys_resetwal 8.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 32 II 目录 8.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 8.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 8.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 8.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 8.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 8.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 第 9 章 sys_rewind 36 9.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 9.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 9.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 9.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 9.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 9.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 如何工作 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 9.6.1 9.7 第 10 章 sys_test_fsync 40 10.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 10.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 10.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 10.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 10.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 10.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 10.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 第 11 章 sys_test_timing 42 11.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 11.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 11.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 11.4 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 11.4.1 结果解读 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 11.4.2 度量执行器计时开销 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 11.4.3 改变时间来源 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 11.4.4 时钟硬件和计时准确性 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 11.5 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 11.6 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 11.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 11.8 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 第 12 章 sys_upgrade 47 12.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 12.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 III 目录 12.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 12.4 使用方法 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 12.5 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 12.6 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 12.7 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 12.8 参见 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 第 13 章 sys_waldump 55 13.1 简介 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 13.2 命令行参数 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 13.3 参数说明 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 13.4 环境变量 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 13.5 错误信息诊断 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 13.6 备注 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 13.7 参考 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 版权声明 58 服务周期承诺 59 IV 第 1 章前言 1 第章前言本文档描述了 KingbaseES 服务器应用和支持工具的参考信息。这些工具命令仅作用于数据库服务器所在的主机。前言部分包含以下主题： • 适用读者 • 相关文档 • 术语 • 手册约定 1.1 适用读者 KingbaseES 服务器应用参考手册面向所有使用 KingbaseES 的用户，主要是数据库管理员和应用程序开发人员。 1.2 相关文档无。 1 第 1 章前言术语 1.3 术语定义字符字符（Character）是各种文字和符号的总称，包括各个国家使用的文字、标点符号、图形符号、数字等。字符集字符集（Character set）是多个字符的集合，字符集种类较多，每种字符集包含的字符个数不同，常见的字符集有：ASCII、GB2312、BIG5、GB18030、Unicode 等。计算机要准确的处理各种字符集文字，需要字符编码，以便计算机能够识别和存储各种文字。数据库集簇 1.4 数据库集簇（database cluster）是指由单个 KingbaseES 服务器实例管理的数据库集合。手册约定本文档中可能出现“注意、提示、警告、另请参阅”等标志，它们所代表的含义如下：注意: 用于突出重要/关键信息、最佳实践等。提示: 用于突出小窍门、捷径等。警告: 用于传递设备或环境安全警示信息，若不避免，可能会导致设备损坏、数据丢失、设备性能降低或其它不可预知的结果。另请参阅: 用于突出参考、参阅等。以下程序代码书写约定适用于本文档：符号说明 [] 表示包含一个或多个可选项。不需要输入中括号本身。 {} 表示包含两个以上（含两个）的候选，必须在其中选取一个。不需要输入花括号本身。 | 分割中括号或者花括号中的两个或两个以上选项。不需要输入“|”本身。见续表 2 第 1 章前言表 1.4.1 – 续表符号说明 ... 表示其之前的元素可以被重复。斜体表示占位符或者需要提供特定值的变量。大写表示系统提供的元素，以便与用户定义的元素相互区分。除出现在方括号中的元素外，应当按照顺序逐字输入。当然，部分元素在系统中是大小写不敏感的，因此用户可以根据系统说明以小写形式输入。小写表示由用户提供的元素。 3 第 2 章 INITDB 2 第章 initdb 2.1 简介 initdb—创建一个新的 KingbaseES 数据库集簇。 initdb 创建一个新的 KingbaseES 数据库集簇。一个数据库集簇是由一个单一服务器实例管理的数据库的集合。一个数据库集簇的创建包括创建存放数据库数据的目录、生成共享目录表（属于整个集簇而不是任何特定数据库的表）并且创建 template0、template1、security 和 test 数据库。当后来创建一个新的数据库时，任何在 template1 数据库中的东西都会被复制（因此，任何已安装在 template1 中的东西都会被自动地复制到后来创建的每一个数据库中）。test 数据库是便于用户、工具和第三方应用使用的默认数据库。尽管 initdb 将尝试创建指定的数据目录，它可能没有权限（如果想要的数据目录的父目录被根用户拥有）。要在这样一种设置中初始化，作为 root 创建一个空数据目录，然后使用 chown 将该目录赋予给数据库用户账户，再然后 su 成为该数据库用户并运行 initdb。 initdb 必须以将拥有该服务器进程的用户运行，因为该服务器需要访问 initdb 创建的文件和目录。因为该服务器不能作为 root 运行，你不能以 root 运行 initdb（事实上它会拒绝这样做）。由于安全原因，由 initdb 创建的新集簇默认将只能由集簇拥有者访问。--allow-group-access 选项允许与集簇拥有者同组的任何用户读取集簇中的文件。这对非特权用户执行备份很有用。 initdb 初始化该数据库集簇的默认区域和字符集编码。当一个数据库被创建时，其字符集编码、排序顺序（LC_COLLATE）和字符集类（LC_CTYPE，例如大写、小写、数字）可以被独立设置。initdb 为 template1 数据库确定那些设置，它们将作为所有其他数据库的默认值。要修改默认排序顺序或字符集类，使用--lc-collate 和--lc-ctype 选项。除 C 或 POSIX 之外的排序顺序会有性能损失。由于这些原因，在运行 initdb 时选择正确的区域很重要。余下的区域分类可以在服务器启动之后改变。你也可以使用--locale 来为所有区域分类设置默认值，包括排序顺序和字符集类。所有服务器区域值（lc_*）可以通过 SHOW ALL 显示。详见区域支持。要修改默认编码，使用--encoding。详见字符集支持。 4 第 2 章 INITDB 2.2 命令行参数 initdb [option ...] [ --kingbase_data | -D ] directory 2.3 参数说明 -A authmethod --auth=authmethod 这个选项为本地用户指定在 sys_hba.conf 中使用的默认认证方法（host 和 local 行）。initdb 将使用指定的认证方法为非复制连接以及复制连接填充 sys_hba.conf 项。为了安装方便，scram-sha-256 是默认值。支持的加密认证算法 scram-sha-256 、md5 、sm3 、 scram-sm3 、sm4 。 --auth-host=authmethod 这个选项为通过 TCP/IP 连接的本地用户指定在 sys_hba.conf 中使用的认证方法（host 行）。支持的加密认证算法 scram-sha-256 、md5 、sm3 、scram-sm3 、sm4 。 --auth-local=authmethod 这个选项为通过 Unix 域套接字连接的本地用户指定在 sys_hba.conf 中使用的认证方法（local 行）。支持的加密认证算法 scram-sha-256 、md5 、sm3 、scram-sm3 、sm4 。 -D directory --kingbase_data=directory 这个选项指定数据库集簇应该存放的目录。这是 initdb 要求的唯一信息，但是你可以通过设定 KINGBASE_DATA 环境变量来避免书写它，这很方便因为之后数据库服务器（kingbase）可以使用同一个变量来找到数据库目录。 -E encoding --encoding=encoding 选择模板数据库的编码。这也将是后来创建的任何数据库的默认编码，除非你覆盖它。默认值来自于区域，或者如果该值不起作用则为 SQL_ASCII。KingbaseES 服务器所支持的字符集在字符集支持中描述。 -e algorithm --encrypt-algorithm=algorithm 这个选项指定数据库集簇使用的透明加密算法，默认为 SM4（可选 RC4） -g --allow-group-access 允许与集簇拥有者同组的用户读取 initdb 创建的所有集簇文件。Windows 会忽略此选项，因为它不支持 POSIX 样式的组权限。 -k --data-checksums 在数据页面上使用校验码来帮助检测 I/O 系统造成的损坏。启用校验码将会引起显著的性能损失。如果被设置，在所有数据库中会为所有对象计算校验码。所有的检验故障均会在 sys_stat_database 视图中被报告。 5 第 2 章 INITDB --locale=locale 为数据库集簇设置默认区域。如果这个选项没有被指定，该区域将从 initdb 所运行的环境中继承。区域支持在区域支持中描述。 --lc-collate=locale --lc-ctype=locale --lc-messages=locale --lc-monetary=locale --lc-numeric=locale --lc-time=locale 和--locale 相似，但是只在指定的分类中设置区域。 -m 设置 KingbaseES 初始化时的兼容模式。默认情况下 (初始化时不设置此参数) 为兼容 Oracle 模式。支持四种参数值：pg , oracle ,“mysql“ , 0 , 1 , 2；其中 pg 和 0 表示兼容 PostgreSQL 模式，oracle 和 1 表示兼容 Oracle 模式，mysql 和 2 表示兼容 MySQL 模式。注意：参数值 pg 、oracle``和``mysql 不区分大小写。 --no-locale 等效于--locale=C。 -N --no-sync 默认情况下，initdb 将等待所有文件被安全地写到磁盘之后再返回。这个选项会导致 initdb 不等待就返回，后续操作系统如果崩溃可能损坏数据目录。这个选项不适用于生产环境。 --pwfile=filename 让 initdb 从一个文件读取数据库超级用户的口令。该文件的第一行被当作口令。 -S --sync-only 安全地把所有数据库文件写入到磁盘并退出。这个指令不会执行任何数据库初始化操作。 -T config --text-search-config=config 设置默认的文本搜索配置。详见参数 default_text_search_config。 -U username --username=username 选择数据库超级用户的用户名。这个的默认值是实际运行 initdb 的用户的名称。超级用户的名字是什么真的不重要，但是你可以选择保留常用的名字 kingbase，即使操作系统的用户名不同。 --pwprompt 让 initdb 提示要求为数据库超级用户给予一个口令。如果你没有计划使用口令认证，这就不重要。否则在你设置一个口令之前你就无法使用口令认证。 -X directory --waldir=directory 这个选项指定预写式日志会被存储在哪个目录中。 --wal-segsize=size 6 第 2 章 INITDB 设置 WAL 段尺寸，以兆字节为单位。这是 WAL 日志中每个文件的尺寸。默认的尺寸为 16 兆字节。该值必须位于 2 的 1 次幂和 1024 次幂（兆字节）之间。这个选项只能在初始化期间设置，并且之后不能更改。调整这个值来控制 WAL 日志传送或者归档可能会有用。此外，在有大量 WAL 的数据库中，每个目录中数量巨大的 WAL 文件可能会成为性能和管理问题。增加 WAL 文件尺寸将会降低 WAL 文件的数量。 --enable-ci 启用字符串大小写不敏感比较。设置此参数则以大小写不敏感的方式进行字符串比较。 -t --aud-tblspc-enc 允许审计表空间加密 -K KEY --enckey=KEY 设置审计表空间加密密钥 -M --passwordcheck 允许开启密码复杂度检查 -I --identity-pwdexp 允许开启用户密码过期检查 --saoname=newsaoname 对数据库审计员重命名，未设置时默认为 sao 。 --ssoname=newssoname 对数据库安全员重命名，未设置时默认为 sso 。 --block-size=size 设置表块大小，以千字节为单位。默认的尺寸为 8 千字节。该值必须是 2 的整数次幂，并且在 1 到 32 之间。这个选项只能在初始化期间设置，并且之后不能更改。其他较少使用的选项： -d --debug 打印来自引导后端的调试输出以及详细消息。引导后端被程序 initdb 用来创建目录表。这个选项会生成大量详细流程输出。 -L directory 指定 initdb 应从哪里寻找输入文件来初始化数据库集簇。通常无需设置。需要显式地指定它们的位置时，会进行告知。 -n --no-clean 默认情况下，当 initdb 确定已发生错误阻止它完整地创建数据库集簇时，会移除本次执行创建的任何文件。这个选项会禁止这种移除，用于调试场景。 7 第 2 章 INITDB -a “ --checksum-algorithm=ALOGRITHM“ 参数开启数据页校验并指定校验算法，取值可为 crc、sm3、sm3_hmac。 -h --hmac-key = KEY 当开启-a 参数并指定页校验算法为 sm3_hmac 时可用，用来设置 sm3_hmac 的秘钥。参数格式是长度为 64 字节的 ASCII 码可见字符。 -c –-config-protect 指定参数后，生成的配置文件为加密配置。默认情况下生成明文配置文件。 --encrypt-device-lib --encrypt-driver-lib --encrypt-maxkey-len --encrypt-align-num 以上四个参数分别代表加密设备库、加密驱动程序库、加密最大密钥长度、加密算法对齐数。在-e 参数指定为非本地算法（sm4/rc4）时生效，且-e 参数指定为非本地算法时必须指定这四个参数。当-e 参数指定为本地算法时，如果指定了这四个参数，将提示忽略参数输入。其他选项： -V --version 打印 initdb 版本并退出。 -? --help 显示有关 initdb 命令行参数的帮助并退出。 -s --show 显示内部参数。 2.4 环境变量 KINGBASE_DATA 指定数据库集簇应该被存放的目录，可以使用-D 选项覆盖。 SYS_COLOR 指定是否在诊断消息中使用颜色。可能取值为 always、auto 和 never。 TZ 指定创建的数据集簇的默认时区。值应该是一个完整的时区名称（见时区）。和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci。 8 第 2 章 INITDB 2.5 错误信息诊断无 2.6 备注 initdb 可以通过 sys_ctl initdb 被调用。 2.7 参考 sys_ctl , kingbase 9 第 3 章 KINGBASE 3 第章 kingbase 3.1 简介 kingbase—KingbaseES 数据库服务器 kingbase 是 KingbaseES 数据库服务器。一个客户端应用为了能访问一个数据库，它会（通过一个网络或者本地）连接到一个运行着的 kingbase 实例。该 kingbase 实例接着会开始一个独立的服务器进程来处理该连接。一个 kingbase 实例总是管理正好一个数据库集簇的数据。一个数据库集簇是一个数据库的集合，它们被存储在一个共同的文件系统位置（“数据区”）上。一个系统上可以同时运行多个 kingbase 实例，只要它们使用不同的数据区和不同的通信端口（见下文）。 kingbase 启动时需要知道数据区的位置，该位置必须通过-D 选项或 KINGBASE_DATA 环境变量指定，对此是没有默认值的。通常，-D 或 KINGBASE_DATA 会直接指向由initdb 创建的数据区目录。其他可能的文件布局在配置文件中讨论。默认情况下，kingbase 会在前台启动并将日志消息打印到标准错误流。但在实际应用中，kingbase 应当作为一个后台进程启动，而且多数是在系统启动时自动启动。 kingbase 还能在单用户模式中被调用。这种模式的主要用途是在启动过程中由initdb 使用。有时候它也被用于调试或者灾难性恢复。注意，运行一个单用户模式服务器并不真地适合调试服务器，因为不会发生实际的进程间通信和锁定。当从 shell 中调用单用户模式时，用户可以输入查询并且结果会被以一种更适合开发者阅读（不适合普通用户）的形式打印在屏幕上。在单用户模式中，会话用户将被设置为 ID 为 1 的用户，并且这个用户会被隐式地赋予超级用户权限。该用户不必实际存在，因此单用户模式运行可以被用来对某些意外损坏的系统目录进行手工恢复。 3.2 命令行参数 kingbase [option...] 10 第 3 章 KINGBASE 3.3 参数说明 kingbase 接受的命令行参数的详细讨论请参考服务器配置参数参考手册。你也可以通过设置一个配置文件来减少大部分选项的键入。有些（安全）选项还可以从连接的客户端基于应用进行设置，并只应用于当前会话。例如，如果设置了 KINGBASE_OPTIONS 环境变量，那么基于 libkci 的客户端将把相应字符串传递给服务器，并作为 kingbase 的命令行选项。 3.3.1 通用选项 -B nbuffers 设置被服务器进程使用的共享内存缓冲区数量。这个参数的默认值是 initdb 自动选择的。指定这个选项等效于设置 shared_buffers 配置参数。 -c name=value --name=value 设置一个命名的运行时参数。KingbaseES 支持的配置参数在服务器配置参数参考手册中描述。大多数其它命令行选项实际上都是这种参数赋值的短形式。-c 可以出现多次用于设置多个参数。 -C name 打印命名运行时参数的值，并且退出（详见上面的-c 选项）。这可以被用在一个运行服务器上，并且从 kingbase.conf 中返回值，这些值可能被在这次调用中的任何参数修改过。它并不反映集簇启动时提供的参数。这个选项用于与一个服务器实例交互的其他程序来查询配置参数值，例如sys_ctl 。面向用户的应用应该使用 SHOW 或者 sys_settings 视图。 -d debug-level 设置调试级别。数值设置得越高，写到服务器日志的调试输出就越多。取值范围是从 1 到 5。还可以针对某个特定会话使用-d 0 来阻止父 kingbase 进程的服务器日志级别被传播到这个会话。 -D datadir 指定数据库配置文件的文件系统位置。详见配置文件。 -e 把默认日期风格设置为“European”，也就是输入日期域的顺序是 DMY。这也导致在一些日期输出格式中把日打印在月之前。详见日期时间类型。 -F 禁用 fsync 调用以提高性能，但是要冒系统崩溃时数据损坏的风险。指定这个选项等效于禁用 fsync 配置参数。在使用之前阅读详细文档！ -h hostname 11 第 3 章 KINGBASE 指定 kingbase 监听来自客户端应用 TCP/IP 连接的 IP 主机名或地址。该值也可以是一个用逗号分隔的地址列表，或者 * 表示监听所有可用的地址。一个空值表示不监听任何 IP 地址，在这种情况下可以使用 Unix 域套接字连接到服务器。缺省只监听 localhost。声明这个选项等效于设置 listen_addresses 配置参数。默认只监听 localhost。指定这个选项等效于设置 listen_addresses 配置参数。 -i 允许远程客户端使用 TCP/IP （互联网域）连接。没有这个选项，将只接受本地连接。这个选项等效于在 kingbase.conf 中或者通过-h 选项将 listen_addresses 设为 *。这个选项已经被废弃，因为它不允许访问 listen_addresses 的完整功能。所以最好直接设置 listen_addresses。 -k directory 指定 kingbase 用来监听来自客户端应用连接的 Unix 域套接字的目录。这个值也可以是一个逗号分隔的目录列表。一个空值指定不监听任何 Unix 域套接字，在这种情况下只能用 TCP/IP 套接字来连接到服务器。默认值通常是/tmp，但是可以在编译的时候修改。指定这个选项等效于设置 unix_socket_directories 配置参数。 -l 启用使用 SSL 的安全连接。要使这个选项可用，编译 KingbaseES 时必须打开 SSL 支持。有关使用 SSL 的更多信息，请参考用 SSL 进行安全的 TCPIP 连接。 -N max-connections 设置该服务器将接受的最大客户端连接数。该参数的默认值由 initdb 自动选择。指定这个选项等效于设置 max_connections 配置参数。 -o extra-options 在 extra-options 中指定的命令行风格的参数会被传递给所有由这个 kingbase 进程派生的服务进程。 extra-options 中的空格被视作参数分隔符，除非用反斜线（\）转义。要表示一个字面意义上的反斜线，可以写成\\。通过多次使用-o 也可以指定多个参数。这个选项的使用已经被废弃。用于服务器进程的所有命令行选项可以在 kingbase 命令行上直接指定。 -p port 指定 kingbase 用于监听客户端应用连接的 TCP/ IP 端口或本地 Unix 域套接字文件扩展。默认为 KINGBASE_PORT 环境变量的值。如果 KINGBASE_PORT 没有设置，那么默认值是编译期间设立的值（通常是 54321）。如果你指定了一个非默认端口，那么所有客户端应用都必须用命令行选项或者 KINGBASE_PORT 指定同一个端口。 -s 在每条命令结束时打印时间信息和其它统计信息。这个选项对测试基准和调节缓冲区数量有用处。 -S work-mem 指定内部排序和散列在使用临时磁盘文件之前能使用的内存数量。见内存中对 work_mem 配置参数的描述。 12 第 3 章 KINGBASE -V --version 打印 kingbase 版本并退出。 --describe-config 这个选项会用制表符分隔的 COPY 格式导出服务器的内部配置变量、描述以及默认值。设计它的目的是用于管理工具。 --catalog 打印 catalog 版本并退出。 -? --help 显示有关 kingbase 的命令行参数，并且退出。 3.3.2 开发人员选项这里描述的选项主要被用于调试目的，并且在某些情况下可以协助恢复严重受损的数据库。在生产数据库环境中应该不会去使用它们。在这里列举它们只是为了让 KingbaseES 系统开发者使用。此外，这些选项可能在将来的版本中更改或删除而不另行通知。 -f { s | i | o | b | t | n | m | h } 禁止某种扫描和连接方法的使用：s 和 i 分别禁用顺序和索引扫描，o、b 和 t 分别禁用只用索引扫描、位图索引扫描以及 TID 扫描，而 n、m 和 h 则分别禁用嵌套循环、归并和哈希连接。顺序扫描和嵌套循环连接都不可能完全被禁用。-fs 和-fn 选项仅仅是在有其他选择时不鼓励优化器使用这些计划类型。 -n 该选项主要用于调试导致服务器进程异常崩溃的问题。对付这种情况的一般策略是通知所有其它服务器进程，让它们终止并且接着重新初始化共享内存和信号量。这是因为一个错误的服务器进程可能在终止之前就已经对共享状态造成了破坏。该选项指定 kingbase 将不会重新初始化共享数据结构。一个有经验的系统程序员这时就可以使用调试器检查共享内存和信号量状态。 -O 允许修改系统表的结构。这个选项用于 initdb。 -P 读取系统表时忽略系统索引（但在更改系统表时仍然更新索引）。这在从损坏的系统索引中恢复时有用。 -t pa[rser] | pl[anner] | e[xecutor] 打印与每个主要系统模块相关的查询的时间统计。这个选项不能和-s 选项一起使用。 -T 13 第 3 章 KINGBASE 该选项主要用于调试导致服务器进程异常崩溃的问题。对付这种情况的一般策略是通知所有其它服务器进程，让它们终止并且接着重新初始化共享内存和信号量。这是因为一个错误的服务器进程可能在终止之前就已经对共享状态造成了破坏。该选项指定 kingbase 将通过发送 SIGSTOP 信号停止其他所有服务器进程，但是并不让它们终止。这样就允许系统程序员手动从所有服务器进程收集内核转储。 -v protocol 声明这次会话使用的前/后服务器协议的版本数。该选项仅在内部使用。 -W seconds 在一个新服务器进程被启动时，它实施认证过程之后会延迟这个选项所设置的秒数。这就留出了机会来用一个调试器附着在服务器进程上。 3.4 环境变量 KCICLIENTENCODING 客户端使用的默认字符编码（客户端可以独立地覆盖它）。这个值也可以在配置文件中设置。 KINGBASE_DATA 默认的数据目录位置。 KINGBASE_DATESTYLE DateStyle 运行时参数的默认值（这个环境变量的使用已被废弃）。 KINGBASE_PORT 默认端口号（在配置文件中设置更好） 3.5 错误信息诊断一个提到了 semget 或 shmget 的错误消息可能意味着你需要配置内核来提供足够的共享内存和信号量。更多讨论请见管理内核资源。你也可以通过降低 shared_buffers 值减少 KingbaseES 的共享内存消耗，或者降低 max_connections 值减少信号量消耗，这样可以推迟对内核的重新配置。如果一个消息说另外一个服务器已经在运行，应该仔细地检查，例如根据你的系统可以用命令 $ ps ax | grep kingbase 或 $ ps -ef | grep kingbase 14 第 3 章 KINGBASE 如果你确信没有冲突的服务器正在运行，那么你可以删除消息中提到的锁文件然后再次尝试。如果一个失败消息指示它无法绑定到一个端口，可能意味着该端口已经被某些非 KingbaseES 进程所使用。如果终止 kingbase 并且立即使用相同的端口重启它，也可能会得到这种错误。在这种情况下，你必须等待几秒直到操作系统关闭该端口，然后再重试。最后，如果指定了一个操作系统认为需要保留的端口号，可能也会得到这个错误。例如，很多版本的 Unix 认为低于 1024 的端口号是“可信的”并且只允许 Unix 超级用户访问它们。 3.6 备注实用命令sys_ctl 可以用来安全方便地启动和关闭 kingbase 服务器。只要有可能，就不要使用 SIGKILL 杀死主 kingbase 服务器。这样会阻止 kingbase 在终止前释放它持有的系统资源（例如共享内存和信号量）。这样可能会导致启动新的 kingbase 进程时出现问题。要正常地终止 kingbase 服务器，可以使用 SIGTERM、SIGINT 或者 SIGQUIT 信号。第一个在退出前将等待所有客户端终止，第二个将强行断开所有客户端的连接，第三个会不做正确的关闭立即退出并且会导致重启时的恢复。 SIGHUP 信号会重新加载服务器配置文件。也可以向一个单独的服务器进程发送 SIGHUP 信号，但是这样做通常没什么意义。要取消一个正在运行的查询，可以向运行该查询的进程发送 SIGINT 信号。要干净地终止一个后端进程，可向它发送 SIGTERM。在 SQL 中可调用的与这两种动作等效的命令可参考服务器信号函数中的 sys_cancel_backend 和 sys_terminate_backend。 kingbase 服务器使用 SIGQUIT 来告诉子服务器进程终止但不做正常的清理。用户不应该使用该信号。向一个服务器进程发送 SIGKILL 时，主 kingbase 进程会理解为程序崩溃，并且作为标准崩溃恢复过程的一部分，它将强制程序所有的其他进程退出。 3.7 缺陷 --选项在 FreeBSD 或 OpenBSD 上无法运行，应该使用-c。这在受影响的系统里是个缺陷；如果这个缺陷没有被修复，将来的 KingbaseES 版本将提供一种解决方案。 3.8 单用户模式要启动一个单用户模式的服务器，使用这样的命令 kingbase --single -D /opt/Kingbase/ES/V9/data other-options my_database 用-D 给服务器提供正确的数据库目录的路径，或者确保环境变量 KINGBASE_DATA 被设置。同时还要指定你想在其中工作的特定数据库的名字。 15 第 3 章 KINGBASE 通常，单用户模式的服务器会把换行符当做命令输入的终止符，也无法解析分号。要想把一个命令分成多行，必须在最后一个换行符以外的每个换行符前面敲一个反斜线。这个反斜线和旁边的新行都会被从输入命令中去掉。注意即使在字符串或者注释中也会这样做。但是如果使用了-j 命令行选项，那么单个新行将不会终止命令输入。相反，分号-新行-新行的序列才会终止命令输入。也就是说，输入一个紧跟着空行的分号。在这种模式下，反斜线-新行不会被特殊对待。此外，在字符串或者注释内的这类序列也不会被特殊对待。不管在哪一种输入模式中，如果输入的一个分号不是正好在命令终止符之前或者不是命令终止符的一部分，它会被认为是一个命令分隔符。当真正输入一个命令终止符时，已经输入的多个语句将被作为一个单个事务执行。要退出会话，输入 EOF（通常是 Control+D）。如果从上一个命令终止符以来已经输入了任何文本，那么 EOF 将被当作命令终止符，并且如果要退出则需要另一个 EOF。请注意单用户模式的服务器不会提供复杂的行编辑特性（例如没有命令历史）。但用户模式也不会做任何后台处理，例如自动检查点或者复制。 3.9 示例要用默认值在后台启动 kingbase： $ nohup kingbase >logfile 2>&190%）的单个计时调用用时都小于 1 微秒。每次循环的平均开销将会更低，低于 100 纳秒。下面的例子来自于一台使用了一份 TSC 时钟源码的 Intel i7-860 系统，它展示了非常好的性能： Testing timing overhead for 3 seconds. Per loop time including overhead: 35.96 ns Histogram of timing durations: < us % of total count 1 96.40465 80435604 2 3.59518 2999652 4 0.00015 126 8 0.00002 13 16 0.00000 2 注意每次循环时间和柱状图用的单位是不同的。循环的解析度可以在几个纳秒（ns），而单个计时调用只能解析到一个微秒（us）。 11.4.2 度量执行器计时开销当查询执行器使用 EXPLAIN ANALYZE 运行一个语句时，单个操作会被计时，总结也会被显示。你的系统的负荷可以通过使用 ksql 程序计数行来检查： CREATE TABLE t AS SELECT * FROM generate_series(1,100000); \timing SELECT COUNT(*) FROM t; EXPLAIN ANALYZE SELECT COUNT(*) FROM t; i7-860 系统测到运行该计数查询用了 9.8 ms 而 EXPLAIN ANALYZE 版本则需要 16.6 ms，每次处理都在 100,000 行上进行。6.8 ms 的差别意味着在每行上的计时负荷是 68ns，大概是 sys_test_timing 估计的两倍。即使这样相对少量的负荷也造成了带有计时的计数语句耗时多出了 70%。在更大量的查询上，计时开销带来的问题不会有这么明显。 11.4.3 改变时间来源在一些较新的 Linux 系统上，可以在任何时候更改用来收集计时数据的时钟来源。第二个例子显示了在上述快速结果的相同系统上切换到较慢的 acpi_pm 时间源可能带来的降速： 43 第 11 章 SYS_TEST_TIMING # cat /sys/devices/system/clocksource/clocksource0/available_clocksource tsc hpet acpi_pm # echo acpi_pm > /sys/devices/system/clocksource/clocksource0/current_clocksource # sys_test_timing Per loop time including overhead: 722.92 ns Histogram of timing durations: < us % of total count 1 27.84870 1155682 2 72.05956 2990371 4 0.07810 3241 8 0.01357 563 16 0.00007 3 在这种配置中，上面的例子 EXPLAIN ANALYZE 用了 115.9 ms。其中有 1061 ns 的计时开销，还是用这个工具直接度量结果的一个小倍数。这么多的计时开销意味着实际的查询本身只占了时间的一个很小的分数，大部分的时间都耗在了计时所需的管理开销上。在这种配置中，任何涉及到很多计时操作的 EXPLAIN ANALYZE 都会受到计时开销的显著影响。 FreeBSD 也允许即时更改时间源，并且它会记录在启动期间有关计时器选择的信息： # dmesg | grep "Timecounter" Timecounter "ACPI-fast" frequency 3579545 Hz quality 900 Timecounter "i8254" frequency 1193182 Hz quality 0 Timecounters tick every 10.000 msec Timecounter "TSC" frequency 2531787134 Hz quality 800 # sysctl kern.timecounter.hardware=TSC kern.timecounter.hardware: ACPI-fast -> TSC 其他系统可能只允许在启动时设定时间源。在旧的 Linux 系统上，“clock”内核设置是做这类更改的唯一方法。并且即使在一些更近的系统上，对于一个时钟源你将只能看到唯一的选项”jiﬀies”。Jiﬀies 是老的 Linux 软件时钟实现，当有足够快的计时硬件支持时，它能够具有很好的解析度，就像在这个例子中： $ cat /sys/devices/system/clocksource/clocksource0/available_clocksource jiffies $ dmesg | grep time.c time.c: Using 3.579545 MHz WALL PM GTOD PIT/TSC timer. time.c: Detected 2400.153 MHz processor. $ sys_test_timing Testing timing overhead for 3 seconds. Per timing duration including loop overhead: 97.75 ns Histogram of timing durations: < us % of total count 1 90.23734 27694571 2 9.75277 2993204 4 0.00981 3010 44 第 11 章 8 0.00007 22 16 0.00000 1 32 0.00000 1 11.4.4 SYS_TEST_TIMING 时钟硬件和计时准确性收集准确的计时信息在计算机上通常是使用具有不同精度的时钟硬件完成的。使用一些硬件，操作系统能几乎直接把系统时钟时间传递给程序。一个系统时钟也可以得自于一块简单地提供计时中断、在某个已知时间区间内的周期性滴答的芯片。在两种情况中，操作系统内核提供一个隐藏这些细节的时钟源。但是时钟源的精确度以及能多快返回结果会根据底层硬件而变化。不精确的计时能够导致系统不稳定性。对任何时钟源的更改都要仔细地测试。操作系统默认是有时会更倾向于可靠性而不是最好的精确性。并且如果你在使用一个虚拟机器，应查看与之兼容的推荐时间源。在模拟计时器时虚拟硬件面临着额外的困难，并且提供商常常会建议每个操作系统的设置。时间戳计数器（TSC）时钟源是当前一代 CPU 上最精确的一种。当操作系统支持 TSC 并且 TSC 可靠时，它是跟踪系统时间更好的方式。有多种方式会使 TSC 无法提供准确的计时源，这会让它不可靠。旧的系统能有一种基于 CPU 温度变化的 TSC 时钟，这让它不能用于计时。尝试在一些旧的多核 CPU 上使用 TSC 可能在多个核心之间给出不一致的时间报告。这可能导致时间倒退，这个程序会检查这种问题。并且即使最新的系统，在非常激进的节能配置下也可能无法提供准确的 TSC 计时。更新的操作系统可能检查已知的 TSC 问题并且当它们被发现时切换到一种更慢、更稳定的时钟源。如果你的系统支持 TSC 时间但是并不默认使用它，很可能是由于某种充分的理由才禁用它。某些操作系统可能无法正确地检测所有可能的问题，或者即便在知道 TSC 不精确的情况下也允许使用 TSC。如果系统上有高精度事件计时器（HPET）并且 TSC 不准确，该系统将会更喜欢 HPET 计时器。计时器芯片本身是可编程的，最高允许 100 纳秒的解析度，但是在你的系统时钟中可能见不到那么高的准确度。高级配置和电源接口（ACPI）提供了一种电源管理（PM）计时器，Linux 把它称之为 acpi_pm。得自于 acpi_pm 的时钟最好时将能提供 300 纳秒的解析度。在旧的 PC 硬件上使用的计时器包括 8254 可编程区间计时器（PIT）、实时时钟（RTC）、高级可编程中断控制器（APIC）计时器以及 Cyclone 计时器。这些计时器是以毫秒解析度为目标的。 11.5 环境变量无 45 第 11 章 11.6 SYS_TEST_TIMING 错误信息诊断无 11.7 备注无 11.8 参考 EXPLAIN 46 第 12 章 SYS_UPGRADE 12章 sys_upgrade 第 12.1 简介 sys_upgrade—升级 KingbaseES 服务器实例。 sys_upgrade 允许将存储在 KingbaseES 数据文件中的数据升级到一个更高的 KingbaseES 主版本，而无需进行主版本升级，通常所需的数据转储/重载。主 KingbaseES 版本通常会加入新的特性，这些新特性常常会更改系统表的布局，但是内部数据存储格式很少改变。sys_upgrade 使用这一事实来通过创建新系统表并且重用旧的用户数据文件来执行快速升级。如果未来的主要版本以一种使旧数据格式不可读的方式更改数据存储格式，则 sys_upgrade 将无法用于此类升级。sys_upgrade 会尽最大努力确保新旧集簇是二进制兼容的，例如，通过检查编译设置是否兼容（是否以 32/64 位编译二进制文件）。保持外部模块也是二进制兼容的也很重要，尽管 sys_upgrade 无法检查这一点。sys_upgrade 支持从 V9(20211031 版本) 及其后版本升级到当前的 KingbaseES 主版本，包括快照和 beta 版本。 sys_upgrade 目前暂不支持 Windows 版本的 KingbaseES 升级。 12.2 命令行参数 sys_upgrade { -b | --old-bindir } oldbindir { -B | --new-bindir } newbindir { -d | --old-datadir } olddatadir { -D | --new-datadir } newdatadir [option...] 12.3 参数说明 sys_upgrade 接受下列命令行参数： -b bindir --old-bindir=bindir 旧的 KingbaseES 可执行文件目录；环境变量 KBBINOLD。 47 第 12 章 SYS_UPGRADE -B bindir --new-bindir=bindir 新的 KingbaseES 可执行文件目录；环境变量 KBBINNEW。 -c --check 只检查集簇，不更改任何数据。 -d datadir --old-datadir=datadir 旧的集簇数据目录；环境变量 KBDATAOLD。 -D datadir --new-datadir=datadir 新的集簇数据目录；环境变量 KBDATANEW。 -j --jobs 要同时使用的进程或线程数。 -k --link 使用硬链接来代替将文件拷贝到新集簇。 -o options --old-options options 直接传送给旧 kingbase 命令的选项，多个选项可以追加在后面。 -O options --new-options options 直接传送给新 kingbase 命令的选项，多个选项可以追加在后面。 -p port --old-port=port 旧的集簇端口号；环境变量 KBPORTOLD。 -P port --new-port=port 新的集簇端口号；环境变量 KBPORTNEW。 -r --retain 即使在成功完成后也保留 SQL 和日志文件。 -s dir --socketdir=dir 升级期间用于 kingbase 套接字的目录；默认为当前工作目录；环境变量 KINGBASE_SOCKETDIR。 -U username --username=username 集簇的安装用户名；环境变量 KBUSER。 -v --verbose 启用详细的内部日志。 -V --version 显示版本信息，然后退出。 --clone 48 第 12 章 SYS_UPGRADE 使用高效的文件拷贝（在某些系统上也称为 reflinks ），而不是将文件复制到新集簇。这会导致数据文件近乎即时复制，从而在不影响旧集簇的同时提供 -k/--link 的速度优势。文件拷贝仅在某些操作系统和文件系统上受支持。如果它被选中但不受支持，则 sys_upgrade 运行将出错。目前，它在带有 Btrfs 和 XFS（在使用 reflink 支持创建的文件系统上）的 Linux（内核 4.5 或更高版本）以及带有 APFS 的 macOS 上受支持。 -? --help 显示帮助，然后退出。 12.4 使用方法下面是用 sys_upgrade 执行升级的步骤： 1. 移动旧集簇（可选）如果你在使用一个与版本相关的安装目录（例如 /opt/KingbaseES/V9），你就不需要移动旧的集簇。图形化的安装程序会使用版本相关的安装目录。如果你的安装目录不是版本相关的（例如/opt/Kingbase/ES），就有必要移动当前的 KingbaseES 安装目录，以免它干扰新的 KingbaseES 安装。一旦当前的 KingbaseES 服务器被关闭，就可以安全地重命名 KingbaseES 安装目录。假设旧目录是 /opt/Kingbase/ES，你可以这样： mv /opt/Kingbase/ES /opt/Kingbase/ES.old 来重命名该目录。 2. 安装新的 KingbaseES 二进制文件安装新服务器的二进制文件和支持文件。sys_upgrade 会被包含在默认的安装中。 3. 初始化新的 KingbaseES 集簇使用 initdb 初始化新集簇。这里也要使用与旧集簇相兼容的 initdb 参数。这里没有必要启动新集簇。 4. 安装扩展共享对象文件许多扩展和自定义模块，无论是来自 contrib 还是其他来源，都使用共享对象文件（或 DLL），例如 kbcrypto.so，如果旧集簇使用它，则必须在新集簇中安装与新服务器二进制文件匹配的共享对象文件，通常通过操作系统命令。不要加载模式定义，例如，CREATE EXTENSION kbcrypto，因为它们将从旧集群中复制。如果扩展更新可用，sys_upgrade 将报告此情况并创建一个可以稍后运行以更新它们的脚本。 5. 调整认证 sys_upgrade 将会多次连接到旧服务器和新服务器，因此你需要要在 sys_hba.conf 中把认证设置成 peer 或者使用一个 ~/.encpwd 文件。 49 第 12 章 SYS_UPGRADE 6. 停止两个服务器确认两个数据库服务器都被停止使用，例如在 Unix 上可以： sys_ctl -D /opt/KingbaseES/V9 stop 直到后面的步骤之前，流复制和日志传送备用服务器可以保持运行。 7. 准备备用服务器升级如果正在使用第 9 小节中给出的方法升级备用服务器，请对旧的主集簇和备用集簇运行 sys_controldata 以验证旧的备用服务器已经完全被赶上。验证所有集簇中的“Latest checkpoint location”值是否匹配。（如果旧备用服务器在旧的主服务器之前被关闭或者如果旧的备用服务器仍在运行，则将会出现失配）。此外，在新的主集簇上的 kingbase.conf 文件中把 wal_level 改为 replica。 8. 运行 sys_upgrade 应该运行新服务器而不是旧服务器的 sys_upgrade 二进制文件。sys_upgrade 需要指定新旧集簇的数据和可执行文件（bin）目录。你也可以指定用户和端口值，以及你是否想要用链接来取代默认的复制行为对数据文件进行处理。如果你使用链接模式，升级将会快很多（不需要文件拷贝）并且将使用更少的磁盘空间，但是在升级后一旦启动新集簇，旧集簇就无法被访问。链接模式也要求新旧集簇数据目录位于同一个文件系统中（表空间和 sys_wal 可以在不同的文件系统中）。完整的选项列表可见 sys_upgrade --help。 --jobs 选项允许多个 CPU 核心被用来复制/链接文件以及并行地转储和重载数据库模式。这个选项一个比较好的值是 CPU 核心数和表空间数的最大值。这个选项可以显著地减少升级运行在一台多处理器机器上的多数据库服务器的时间。一旦启动，sys_upgrade 将验证两个集簇是否兼容并且执行升级。你可以使用 sys_upgrade --check 来只执行检查，这种模式即使在旧服务器还在运行时也能使用。 sys_upgrade --check 也将列出任何在更新后需要做的手工调整。如果你将要使用链接模式，你应该使用--link 选项和 --check 一起来启用链接模式相关的检查。 sys_upgrade 要求在当前目录中的写权限。显然，没有人可以在升级期间访问这些集簇。sys_upgrade 默认会在端口 50432 上运行服务器来避免意外的客户端连接。在做升级时，可以对两个集簇使用相同的端口号，因为新旧集簇不会在同时被运行。不过，在检查一个旧的运行中服务器时，新旧端口号必须不同。如果在恢复数据库模式时发生错误，sys_upgrade 将会退出并且你必须按照下文第 15 小节中所说的恢复旧集簇。要再次尝试 sys_upgrade，你将需要修改旧集簇，这样 sys_upgrade 模式会成功恢复。如果问题是一个 contrib 模块，你可能需要从旧集簇中卸载该模块并且在升级后重新把它安装在新集簇中，不过这样做的前提是该模块没有被用来存储用户数据。 9. 升级流复制和日志传送备用服务器 50 第 12 章 SYS_UPGRADE 如果使用链接模式并且有流复制备用服务器，可以遵照下面的步骤对它们进行快速的升级。将不用在这些备用服务器上运行 sys_upgrade，而是在主服务器上运行 rsync。暂时不要启动任何服务器。如果你没有使用链接模式、没有或不想使用 rsync 或者想用一种更容易的解决方案，请跳过这一节中的过程并且在 sys_upgrade 完成并且新的主集簇开始运行后重建备用服务器。 a. 在备用服务器上安装新的 KingbaseES 二进制文件确保新的二进制和支持文件被安装在所有备用服务器上。 b. 确保新的备用机数据目录不存在确保新的备用机数据目录不存在或者为空。如果运行过 initdb，请删除备用服务器的新数据目录。 c. 安装扩展共享对象文件在新的备用机上安装和新的主集簇中相同的自定义共享对象文件。 d. 停止备用服务器如果备用服务器仍在运行，现在使用上述的指令停止它们。 e. 保存配置文件从旧备用机的配置目录保存任何需要保留的配置文件，例如 kingbase.conf、recovery.conf，因为这些文件在下一步中会被重写或者移除。 f. 运行 rsync 在使用链接模式时，备用服务器可以使用 rsync 快速升级。为了实现这一点，在主服务器上一个高于新旧数据库集簇目录的目录中为每个备用服务器运行这个命令： rsync --archive --delete --hard-links --size-only --no-inc-recursive old_dir new_dir remote_dir 其中 old_dir 和 new_dir 是相对于主服务器上的当前目录的，而 remote_dir 是备用服务器上高于新旧集簇目录的一个目录。在主服务器和备用服务器上指定目录之下的目录结构必须匹配。指定远程目录的详细情况请参考 rsync 的手册，例如： rsync --archive --delete --hard-links --size-only --no-inc-recursive /opt/KingbaseES/V8R6C4 \ /opt/KingbaseES/V8R6C5 standby.example.com:/opt/KingbaseES 可以使用 rsync 的--dry-run 选项验证该命令将做的事情。虽然在主服务器上必须为至少一台备用运行 rsync，可以在一台已经升级过的备用服务器上运行 rsync 来升级其他的备用服务器，只要已升级的备用服务器还没有被启动。这个命令所做的事情是记录由 sys_upgrade 的链接模式创建的链接，它们连接主服务器上新旧集簇中的文件。该命令接下来在备用服务器的旧集簇中寻找匹配的文件并且为它们在该备用的新集簇中创建链接。 51 第 12 章 SYS_UPGRADE 主服务器上没有被链接的文件会被从主服务器拷贝到备用服务器（通常都很小）。这提供了快速的备用服务器升级。另外，rsync 不需拷贝临时表和未写入日志的表相关的文件，因为通常在备用服务器上不存在这些文件。如果有表空间，你将需要为每个表空间目录运行一个类似的 rsync 命令，例如： rsync --archive --delete --hard-links --size-only --no-inc-recursive /vol1/sys_tblsp/sys_V8R6C4_201510051 \ /vol1/sys_tblsp/sys_V8R6C5_201608131 standby.example.com: /vol1/sys_tblsp 如果你已经把 sys_wal 放在数据目录外面，也必须在那些目录上运行 rsync。 g. 配置流复制和日志传送备用服务器为日志传送配置服务器（不需要运行 sys_start_backup() 以及 sys_stop_backup() 或者做文件系统备份，因为从属机仍在与主机同步）。 10. 恢复 “sys_hba.conf“ 如果你修改了 sys_hba.conf，则要将其恢复到原始的设置。也可能需要调整新集簇中的其他配置文件（例如 kingbase.conf）来匹配旧集簇。 11. 启动新服务器现在可以安全地启动新的服务器，并且可以接着启动任何 rsync 过的备用服务器。 12. 升级后处理如果需要做任何升级后处理，sys_upgrade 将在完成后发出警告。它也将生成必须由管理员运行的脚本文件。这些脚本文件将连接到每一个需要做升级后处理的数据库。每一个脚本应该这样运行： ksql --username=kingbase --file=script.sql test 这些脚本可以以任何顺序运行并且在运行之后立即删除。警告: 通常，在重建脚本运行完成之前访问重建脚本中引用的表是不安全的；这样做可能会产生错误的结果或性能不佳。可以正常访问重建脚本中未引用的表。 13. 统计信息由于 sys_upgrade 并未传输优化器统计信息，在升级结束后系统会提示运行一个命令来生成这些信息。你可能需要设置连接参数来匹配你的新集簇。 14. 删除旧集簇一旦你对升级表示满意，你就可以通过运行 sys_upgrade 完成时提到的脚本来删除旧集簇的数据目录（如果在旧数据目录中有用户定义的表空间就不可能实现自动删除）。你也可以删除旧安装目录（例如 bin、share）。 15. 恢复到旧集簇 52 第 12 章 SYS_UPGRADE 在运行 sys_upgrade 之后，如果你希望恢复到旧集簇，有几个选项： • 如果使用--check 选项，则旧集簇未修改；它可以重新启动。 • 如果未使用--link 选项，则旧集簇未修改；它可以重新启动。 • 如果使用--link 选项，数据文件可能会在新旧集簇之间共享： • 如果 sys_upgrade 在链接开始前中止，则旧集簇未修改；它可以重新启动。 • 如果没有启动新集簇，则旧集簇不会被修改，只是在链接开始时，将.old 后缀附加到 $KBDATA/ global/sys_control. 要重用旧集簇，请删除.old 后缀 $KBDATA/global/sys_control；然后您可以重新启动旧集簇。 • 如果确实启动了新集簇，则它已写入共享文件，使用旧集簇是不安全的。在这种情况下，需要从备份中恢复旧集簇。 12.5 环境变量无 12.6 错误信息诊断无 12.7 备注 sys_upgrade 将在当前工作目录中创建各种工作文件，例如模式转储。为了安全起见，请确保该目录不被任何其他用户读取或写入。 sys_upgrade 在旧的和新的数据目录中短暂地运行 kingbase 。默认情况下，用于与这些 kingbase 通信的临时 Unix 套接字文件在当前工作目录中创建。在某些情况下，当前目录的路径名可能太长而无法成为有效的套接字名称。在这种情况下，可以使用 -s 选项将套接字文件放在具有较短路径名的某个目录中。为了安全起见，请确保该目录不能被任何其他用户读取或写入。 sys_upgrade 会报告所有会影响安装成功的失败、重建和重新索引的情况。升级后重建表和索引的脚本会自动生成。如果尝试自动升级多个集簇，会发现具有相同数据库架构的集簇对于所有集簇升级都需要相同的升级后步骤；这是因为升级后的步骤基于数据库架构，而不是用户数据。对于部署测试，创建旧集簇的仅模式副本，插入虚拟数据，然后升级它。 53 第 12 章 SYS_UPGRADE sys_upgrade 不支持升级包含有使用了以下 reg 开头的 OID 系统数据类型的表的数据库：regproc、 regprocedure、regoper、regoperator、regconfig、regnamespace 以及 regdictionary（regtype、 regclass、regrole 可以被升级）。如果你在升级一个 KingbaseES V9 之前的集簇，并且它使用一个只有配置文件的目录，你必须向 sys_upgrade 传递真正的数据目录位置，并且把配置目录位置传递给服务器，例如 -d /real-data-directory -o '-D /configuration-directory'。如果正在使用的一个 KingbaseES 之前的旧服务器用的是一个非默认 Unix 域套接字目录或者使用的默认值不同于新集簇的默认值，请把 KBHOST 设置为指向旧服务器的套接字位置。如果要使用链接模式，并且不希望在新集簇启动时修改旧集簇，可以复制一份旧集簇并且在副本上以链接模式进行升级。要创建旧集簇的一份合法拷贝，可以在服务器运行时使用 rsync 创建旧集簇的一份拷贝，然后关闭旧服务器并且再次运行 rsync --checksum。把更改更新到该拷贝以让其一致（--checksum 是必要的，因为 rsync 在判断文件修改时间的更改时的精度只能到秒级）。你可能想要排除一些文件，例如 kingbase.pid。如果你的文件系统支持文件系统快照或者 copy-on-write 文件副本，你可以使用它们来创建旧集簇和表空间的一个备份，不过快照和副本必须被同时创建或者在数据库服务器关闭期间被创建。 12.8 参见 initdb , sys_ctl , sys_dump , kingbase 54 第 13 章 SYS_WALDUMP 13章 sys_waldump 第 13.1 简介 sys_waldump—以可读的形式显示一个 KingbaseES 数据库集簇的预写式日志 sys_waldump 显示预写式日志（WAL），它主要用于调试目的。这个工具只能由安装该服务器的用户运行，因为它要求对数据目录的只读访问。 13.2 命令行参数 sys_waldump [option...] [startseg [endseg]] 13.3 参数说明下列命令行选项控制输出的位置和格式： startseg 从指定的日志段文件开始读取。这也隐含地决定了要搜索文件的路径以及要使用的时间线。 endseg 在读取指定的日志段文件后停止。 -b --bkp-details 输出有关备份块的细节。 --block-size=size 设置表块大小，以千字节为单位。默认的尺寸为 8 千字节。该值必须是 2 的整数次幂，并且在 1 到 32 之间。这个选项需要与 initdb 设置的--block-size 大小保持一致，否则会影响相关的计算结果。 -d --display-enc 55 第 13 章 SYS_WALDUMP 显示 WAL 日志是否被加密。 -e end --end=end 在指定的 WAL 位置停止读取，而不是一直读取到日志流的末尾。 -f --follow 在到达可用 WAL 的末尾之后，保持每秒轮询一次是否有新的 WAL 出现。 -k --key-path 指定主密钥文件路径，解析被加密的 WAL 日志时需从主密钥文件获取解密密钥，如果不设置此参数，当读取到被加密的 WAL 日志时，会停止。 -n limit --limit=limit 显示指定数量的记录，然后停止。 -p path --path=path 指定搜索日志段文件的目录或包含这些文件的包含 sys_wal 子目录的目录。缺省值是在当前目录中搜索，当前目录的 sys_wal 子目录和 KINGBASE_DATA 的 sys_wal 子目录。 -r rmgr --rmgr=rmgr 只显示由指定资源管理器生成的记录。如果把 list 作为资源管理器名称传递给这个选项，则打印出可用资源管理器名称的列表然后退出。 -s start --start=start 要从哪个 WAL 位置开始读取。默认是从找到的最早的文件的第一个可用日志记录开始。 -t timeline --timeline=timeline 要从哪个时间线读取日志记录。默认是使用 startseg（如果指定）中的值，否则默认为 1。 -V --version 打印 sys_waldump 版本并且退出。 -x xid --xid=xid 只显示用给定事务 ID 标记的记录。 -z --stats[=record] 显示概括统计信息（记录的数量和尺寸以及全页镜像）而不是显示每个记录。可以选择针对每个记录生成统计信息，而不是针对每个资源管理器生成。 -? --help 显示有关 sys_waldump 命令行参数的帮助并且退出。 56 第 13 章 13.4 SYS_WALDUMP 环境变量 KINGBASE_DATA 数据目录，参考-p 选项. SYS_COLOR 指定是否在诊断消息中使用颜色。可能的值是 always, auto, never. 13.5 错误信息诊断无 13.6 备注当服务器正在运行时可能会给出错误的结果。只有指定的时间线会被显示（如果没有指定，则显示默认时间线）。其他时间线上的记录会被忽略。 sys_waldump 不能读取具有后缀.partial 的 WAL 文件。如果需要读取那些文件，需要从文件名中移除 . partial 后缀。 13.7 参考无 57 版权声明版权声明北京人大金仓信息技术股份有限公司（简称：人大金仓）版权所有，并保留对本手册及本声明的一切权利。未得到人大金仓的书面许可，任何人不得以任何方式或形式对本手册内的任何部分进行复制、摘录、备份、修改、传播、翻译成其他语言、将其全部或部分用于商业用途。免责声明本手册内容依据现有信息制作，由于产品版本升级或其他原因，其内容有可能变更。人大金仓保留在没有任何通知或者提示的情况下对手册内容进行修改的权利。本手册仅作为使用指导，人大金仓在编写本手册时已尽力保证其内容准确可靠，但并不确保手册内容完全没有错误或遗漏，本手册中的所有信息也不构成任何明示或暗示的担保。技术支持 • 人大金仓官方网站：http://www.kingbase.com.cn/ • 人大金仓文档中心：http://help.kingbase.com.cn/ • 全国服务热线：400-601-1188 • 人大金仓技术支持与反馈信箱：support@kingbase.com.cn 58 服务周期承诺服务周期承诺由于市场需求在不断变化，技术创新和发展的进程不断加剧，产品的版本更迭不可避免。人大金仓对于产品版本生命周期的有效管理，有助于您提前规划项目，更好地从产品服务终止上过渡。表 1: KingbaseES 产品生命周期里程碑关键里程碑点定义产品发布日期产品正式发布版本，即 GA（general availability）版本的发布日期。停止销售日期正式停止销售的日期，版本停止接受订单日。该日之后，产品将不再销售。停止功能升级日期在该日期之后，不再提供新特性和新硬件支持。但依旧提供错误修复、安全修复、功能维护等服务。停止功能维护日期在该日期之后，不再维护功能，修复问题。但依旧提供安全修复等服务停止安全维护日期在该日期之后，不再发布补丁版本修复中高风险漏洞，仅提供有限的支持。产品服务终止日期停止提供产品服务和支持的日期。包括软件维护版本，缺陷修复，以及针对该产品的所有服务支持（包括服务热线和远程/现场支持）。服务周期策略金仓数据库管理系统 KingbaseES 产品确保以下的服务周期： 1）产品自发布之日起至产品停止功能升级（包含新特性、新硬件支持）之日不少于 5 年。 2）产品停止功能升级之日起至产品停止功能维护（主要包括问题修复）之日不少于 4 年。 3）产品功能维护停止之日起至产品停止安全维护（包括中高风险漏洞修复）之日不少于 2 年。服务终止策略金仓数据库管理系统 KingbaseES 产品确保在销售后，至少提供 6 年的服务支持。注意: 人大金仓将会综合各方因素来确定产品服务终止日期。并将在实际产品服务终止日期之前至少 90 天，通过公 59 服务周期承诺开方式宣布产品服务终止日期。 60