KES V8R6升级数据库实例

1. sys_upgrade¶

sys_upgrade — 升级KingbaseES服务器实例

1.1. 概述¶

sys_upgrade -b oldbindir -B newbindir -d oldconfigdir -D newconfigdir [option...]

1.2. 描述¶

sys_upgrade允许将存储在KingbaseES数据文件中的数据升级到一个更高的KingbaseES主版本，而无需进行主版本升级（例如从 V8R6C4 到 V8R6C5）通常所需的数据转储/重载。

主 KingbaseES 版本通常会加入新的特性，这些新特性常常会更改系统表的布局，但是内部数据存储格式很少改变。sys_upgrade使用这一事实来通过创建新系统表并且重用旧的用户数据文件来执行快速升级。如果未来的主要版本以一种使旧数据格式不可读的方式更改数据存储格式，则sys_upgrade将无法用于此类升级。

sys_upgrade会尽最大努力确保新旧集簇是二进制兼容的，例如，通过检查兼容的编译设置，包括 32/64 位二进制。保持外部模块也是二进制兼容的也很重要，尽管 sys_upgrade无法检查这一点。

sys_upgrade 支持从 V8R6(20211031版本) 及其后版本升级到当前的KingbaseES主版本，包括快照和beta版本。

sys_upgrade 目前暂不支持 Windows 版本的KingbaseES升级。

1.3. 选项¶

sys_upgrade接受下列命令行参数：

-b bindir --old-bindir=bindir

旧的 KingbaseES 可执行文件目录； 环境变量KBBINOLD

-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 套接字的目录；默认为当前工作目录；环境变量PGSOCKETDIR

-U username --username=username

集簇的安装用户名；环境变量 KBUSER

-v --verbose

启用详细的内部日志

-V --version

显示版本信息，然后退出

--clone

使用高效的文件拷贝（在某些系统上也称为 reflinks ），而不是将文件复制到新集簇。这会导致数据文件近乎即时复制，从而在不影响旧集簇的同时提供 -k/的速度优势 --link。

文件拷贝仅在某些操作系统和文件系统上受支持。如果它被选中但不受支持，则 sys_upgrade 运行将出错。目前，它在带有 Btrfs 和 XFS（在使用 reflink 支持创建的文件系统上）的 Linux（内核 4.5 或更高版本）以及带有 APFS 的 macOS 上受支持。

-? --help

显示帮助，然后退出

1.4. 使用¶

下面是用sys_upgrade执行升级的步骤：

1. 移动旧集簇（可选）

   如果你在使用一个与版本相关的安装目录（例如 /opt/KingbaseES/V8），你就不需要移动旧的集簇。图形化的安装程序会使用版本相关的安装目录。

   如果你的安装目录不是版本相关的（例如/opt/Kingbase/ES/V8），就有必要移动当前的 KingbaseES 安装目录，以免它干扰新的 KingbaseES安装。一旦当前的 KingbaseES服务器被关闭，就可以安全地重命名 KingbaseES 安装目录。假设旧目录是 /opt/Kingbase/ES/V8，你可以这样：

   mv /opt/Kingbase/ES/V8 /opt/Kingbase/ES/V8.old
   

   来重命名该目录。

2. 对于源码安装，编译新版本

   用兼容旧集簇的configure标记编译新的 KingbaseES 源码。在开始升级之前，sys_upgrade 将检查sys_controldata来确保所有设置都是兼容的。

3. 安装新的 KingbaseES 二进制文件

   安装新服务器的二进制文件和支持文件。sys_upgrade 会被包含在默认的安装中。

   对于源码安装，如果你希望把新服务器安装在一个自定义的位置，可以使用prefix变量：

   make prefix=/opt/Kingbase/ES/V8.new install
   

4. 初始化新的 KingbaseES 集簇

   使用initdb初始化新集簇。这里也要使用与旧集簇相兼容的initdb标志。许多预编译的安装程序会自动做这个步骤。这里没有必要启动新集簇。

5. 安装扩展共享对象文件

   许多扩展和自定义模块，无论是来自contrib还是其他来源，都使用共享对象文件（或 DLL），例如kbcrypto.so，如果旧集簇使用它，则必须在新集簇中安装与新服务器二进制文件匹配的共享对象文件，通常通过操作系统命令。不要加载模式定义，例如，CREATE EXTENSION kbcrypto，因为它们将从旧集群中复制。如果扩展更新可用，sys_upgrade将报告此情况并创建一个可以稍后运行以更新它们的脚本。

6. 调整认证

   sys_upgrade将会多次连接到旧服务器和新服务器，因此你需要要在sys_hba.conf中把认证设置成 peer或者使用一个~/.encpwd文件。

7. 停止两个服务器

   确认两个数据库服务器都被停止使用，例如在 Unix 上可以：

   sys_ctl -D /opt/KingbaseES/V8R6 stop
   

   直到后面的步骤之前，流复制和日志传送备用服务器可以保持运行。

8. 准备备用服务器升级

   如果正在使用第10小节中给出的方法升级备用服务器，请对旧的主集簇和备用集簇运行sys_controldata以验证旧的备用服务器已经完全被赶上。验证所有集簇中的“Latest checkpoint location”值是否匹配。（如果旧备用服务器在旧的主服务器之前被关闭或者如果旧的备用服务器仍在运行，则将会出现失配）。此外，在新的主集簇上的kingbase.conf文件中把wal_level改为replica。

9. 运行 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将会退出并且你必须按照下文第16小节中所说的恢复旧集簇。要再次尝试sys_upgrade，你将需要修改旧集簇，这样 sys_upgrade 模式会成功恢复。如果问题是一个 contrib模块，你可能需要从旧集簇中卸载该模块并且在升级后重新把它安装在新集簇中，不过这样做的前提是该模块没有被用来存储用户数据。

10. 升级流复制和日志传送备用服务器

如果使用链接模式并且有流复制备用服务器，可以遵照下面的步骤对它们进行快速的升级。将不用在这些备用服务器上运行 sys_upgrade，而是在主服务器上运行rsync。暂时不要启动任何服务器。

如果你没有使用链接模式、没有或不想使用rsync或者想用一种更容易的解决方案，请跳过这一节中的过程并且在sys_upgrade完成并且新的主集簇开始运行后重建备用服务器。

1. 在备用服务器上安装新的 KingbaseES 二进制文件

   确保新的二进制和支持文件被安装在所有备用服务器上。

2. 确保新的备用机数据目录不存在

   确保新的备用机数据目录不存在或者为空。如果运行过initdb，请删除备用服务器的新数据目录。

3. 安装扩展共享对象文件

   在新的备用机上安装和新的主集簇中相同的自定义共享对象文件。

4. 停止备用服务器

   如果备用服务器仍在运行，现在使用上述的指令停止它们。

5. 保存配置文件

   从旧备用机的配置目录保存任何需要保留的配置文件，例如 kingbase.conf、recovery.conf，因为这些文件在下一步中会被重写或者移除。

6. 运行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的链接模式创建的链接，它们连接主服务器上新旧集簇中的文件。该命令接下来在备用服务器的旧集簇中寻找匹配的文件并且为它们在该备用的新集簇中创建链接。主服务器上没有被链接的文件会被从主服务器拷贝到备用服务器（通常都很小）。这提供了快速的备用服务器升级。不幸地是，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。

7. 配置流复制和日志传送备用服务器

   为日志传送配置服务器（不需要运行sys_start_backup() 以及sys_stop_backup()或者做文件系统备份，因为从属机仍在与主机同步）。

1. 恢复 ``sys_hba.conf``

   如果你修改了sys_hba.conf，则要将其恢复到原始的设置。也可能需要调整新集簇中的其他配置文件（例如 kingbase.conf）来匹配旧集簇。

2. 启动新服务器

   现在可以安全地启动新的服务器，并且可以接着启动任何 rsync过的备用服务器。

3. 升级后处理

   如果需要做任何升级后处理，sys_upgrade 将在完成后发出警告。它也将生成必须由管理员运行的脚本文件。这些脚本文件将连接到每一个需要做升级后处理的数据库。每一个脚本应该这样运行：

   psql --username=kingbase --file=script.sql test
   

   这些脚本可以以任何顺序运行并且在运行之后立即删除。

   Caution

   通常，在重建脚本运行完成之前访问重建脚本中引用的表是不安全的；这样做可能会产生错误的结果或性能不佳。可以正常访问重建脚本中未引用的表。

4. 统计信息

   由于sys_upgrade并未传输优化器统计信息，在升级的尾声你将被指示运行一个命令来生成这些信息。你可能需要设置连接参数来匹配你的新集簇。

5. 删除旧集簇

   一旦你对升级表示满意，你就可以通过运行 sys_upgrade完成时提到的脚本来删除旧集簇的数据目录（如果在旧数据目录中有用户定义的表空间就不可能实现自动删除）。你也可以删除旧安装目录（例如bin、share）。

6. 恢复到旧集簇

   在运行sys_upgrade之后，如果你希望恢复到旧集簇，有几个选项：

   • 如果使用--check选项，则旧集簇未修改；它可以重新启动。

   • 如果未使用--link选项，则旧集簇未修改；它可以重新启动。

   • 如果使用--link选项，数据文件可能会在新旧集簇之间共享：

     • 如果sys_upgrade在链接开始前中止，则旧集簇未修改；它可以重新启动。

     • 如果您没有启动新集簇，则旧集簇不会被修改，只是在链接开始时，将.old后缀附加到$KBDATA/global/sys_control. 要重用旧集簇，请删除.old后缀$KBDATA/global/sys_control；然后您可以重新启动旧集簇。

     • 如果您确实启动了新集簇，则它已写入共享文件，使用旧集簇是不安全的。在这种情况下，需要从备份中恢复旧集簇。

1.5. 备注¶

sys_upgrade将在当前工作目录中创建各种工作文件，例如模式转储。为了安全起见，请确保该目录不被任何其他用户读取或写入。

sys_upgrade在旧的和新的数据目录中启动短期的 kingbase 。默认情况下，用于与这些 kingbase 通信的临时 Unix 套接字文件在当前工作目录中创建。在某些情况下，当前目录的路径名可能太长而无法成为有效的套接字名称。在这种情况下，您可以使用 -s 选项将套接字文件放在具有较短路径名的某个目录中。为了安全起见，请确保该目录不能被任何其他用户读取或写入。

sys_upgrade会报告所有失败、重建和重新索引的情况，如果它们影响您的安装；将自动生成用于重建表和索引的升级后脚本。如果您尝试自动升级许多集簇，您应该会发现具有相同数据库架构的集簇对于所有集簇升级都需要相同的升级后步骤；这是因为升级后的步骤基于数据库架构，而不是用户数据。

对于部署测试，创建旧集簇的仅模式副本，插入虚拟数据，然后升级它。

sys_upgrade不支持使用以下reg*OID 引用系统数据类型升级包含表列的数据库：regproc、regprocedure、 regoper、regoperator、 regconfig、``repnamespace``以及regdictionary（ regtype、``regclass``、``regrole``可以被升级）。

如果你在升级一个KingbaseES V8R6 之前的集簇，并且它使用一个只有配置文件的目录，你必须向sys_upgrade 传递真正的数据目录位置，并且把配置目录位置传递给服务器，例如 -d /real-data-directory -o '-D /configuration-directory'。

如果正在使用的一个KingbaseES V8R6 之前的旧服务器用的是一个非默认Unix 域套接字目录或者使用的默认值不同于新集簇的默认值，请把KBHOST设置为指向旧服务器的套接字位置。

如果要使用链接模式，并且不希望在新集簇启动时修改旧集簇，可以复制一份旧集簇并且在副本上以链接模式进行升级。要创建旧集簇的一份合法拷贝，可以在服务器运行时使用rsync创建旧集簇的一份脏拷贝，然后关闭旧服务器并且再次运行rsync --checksum 把更改更新到该拷贝以让其一致（--checksum是必要的，因为 rsync在判断文件修改时间的更改时的精度只能到秒级）。你可能想要排除一些文件，例如kingbase.pid。如果你的文件系统支持文件系统快照或者 copy-on-write 文件副本，你可以使用它们来创建旧集簇和表空间的一个备份，不过快照和副本必须被同时创建或者在数据库服务器关闭期间被创建。