logo - 跳到首页

VastbaseG100

基于openGauss内核开发的企业级关系型数据库。

Menu

使用VPatch进行版本控制

功能描述

VPatch是用于Vastbase版本控制的工具。可以实现在单机环境下的升级和回退操作，具体功能如下：

  • 升级环境检查，补丁冲突检查等。

  • PSU、PSR、OOP补丁的升级、回退、升级或回退失败时的还原。

  • 升级过程中记录相关日志和步骤文件。

  • 升级过程中管理备份文件。

  • 自vpatch V2.0.0开始，支持在检查和回退时指定--force参数，用于对特殊的可回退升级包进行升级后的强制回退。强制回退表示对修改了函数和系统表的升级过程进行回退（若不指定--force参数，则修改了函数和系统表的升级过程无法回退)。需要注意的是，强制回退可能导致数据丢失或读取错误，一般情况下不推荐使用本功能，或联系技术人员进行判断和操作。

  • PSU：月度补丁版本。

  • PSR：季度补丁版本。

  • OOP：One Off Patch，在单机环境下通过安装OOP升级包解决单个bug或增加小功能，OOP升级包的特点是升级包体量小，升级后版本号不会变化。

前提条件

使用vpatch升级需在python3.7环境下运行，即执行python3 --version，返回版本为3.7.*。

在开始升级前，请检查解压的升级包patch/VPatch/script/ 目录是否存在两个脚本文件 prepare_env.sh和clean_env.sh。

  • 如果不存在上述两个文件，表示当前升级包中不包含python3.7的安装包，需要用户手动安装python3.7；

  • 如果存在上述两个文件，表示当前升级包中已经包含了python3.7的安装包，此时使用root用户运行这两个脚本即可为当前用户安装卸载python3.7。

  • 执行以下命令安装python3.7：

    source prepare_env.sh

    检查是否安装成功，返回版本为3.7.*时表示成功：

    python3 --version

  • 执行以下命令卸载python3.7：

    sh clean_env.sh

卸载后当前连接窗口因为已经配置了python3的环境变量，执行python3 -V命令仍然返回 3.7.*，开启新的连接窗口后恢复安装前情况。

注意事项

  • 仅支持Vastbase G100 V2.2 Build 10及以上版本的升级。

  • 对于集群的升级，需还原为单机模式进行，完成升级后重新部署集群。

  • 强制回退可能导致数据丢失或读取错误，一般情况下不推荐使用本功能，或联系技术人员进行判断和操作。

  • 在升级或回退前应关闭数据库服务。

  • 升级时指定的端口号应避开日常使用的服务端口号，防止升级过程被外部干扰。

  • 不支持修改用户数据升级的场景。用户数据指使用vb_initdb命令初始化后并未包含的、由用户操作产生的表。

  • 仅支持未修改系统表且允许回退的补丁进行rollback 和rollback to回退操作。不支持修改过数据字典的场景进行rollback和rollback to回退操作。

  • 不支持多实例场景。多实例场景即为单一产品对应多个数据库集簇的场景。

  • 修改系统表的情况下不支持OOP，考虑进行PSU升级；

  • 修改三方库的情况下不支持OOP，考虑进行PSU升级；

  • 如有删除文件和新增文件的情况，目前OOP仅支持升级，无法回退，这种情况建议使用PSU升级。

  • 一次升级的目标文件数建议为1~5个，在这个范围内升级是比较安全的。由于OOP体量小，在需要频繁打补丁的情况下，一次升级的目标文件数据越多，下一次升级补丁与前面的补丁出现冲突的可能会大幅增加，因此如果需要升级的目标文件超过10个，建议使用PSU升级，或者分批次升级。

  • 升级过程中，检查和安装准备阶段会向数据库初始化用户的环境配置文件中写入环境变量，所以切换用户时若使用了不同的终端，为避免出现环境变量缺失的问题，需执行以下语句设置环境变量：

    source .bashrc

数据库参数检查

升级前请检查以下数据库参数是否配置正确，避免影响数据库升级。

logging_collector=on
enable_global_syscache=on
uppercase_attribute_name=off
enable_prevent_job_task_startup =on

字符集检查

升级前检查环境变量中的字符集设置，确保LC_ALL的字符集设置与LANG一致，如果不一致，修改LC_ALL，避免影响数据库升级。

echo $LANG
echo $LC_ALL

使用英文字符集升级回退

检查环境变量，如下图所示：

  • 若只有LANG，则在数据库安装用户的bashrc中设置：

    export LANG=en_US.UTF-8

  • 若存在LANGUAGE变量，则修改配置文件如下图所示：

语法格式

  • PSU升级配置文件如下(ini格式)：

    [vpatch]
userName=用户名user1
userGroup=用户组group1
appPath=产品软件目录
dataPath=数据库集簇的绝对路径
port=端口
tmpPath=升级过程临时文件目录

  • OOP升级配置文件如下（ini格式）：

    [vpatch]
userName=用户名user1
userGroup=用户组group1
appPath=产品软件目录
dataPath=数据库集簇的绝对路径
port=端口
tmpPath=升级过程临时文件目录
vpatch_upgrade_file=OOP升级依赖包路径，此包在OOP升级前基础版本的全量包中发布

  • 为VPatch工具设定参数（root用户执行），可选两种方法：

    • 命令行直接指定参数。

      ./vpatch --setparam -u 用户名 -g 用户组 -a 产品目录 -d 集簇目录 -p 端口号 -t 临时目录

    • 给定ini配置文件。

      ./vpatch --setparam -f ini 配置文件绝对路径

    指定配置文件时应指定为绝对路径，否则会出现报错。

  • 对升级或回退补丁做基本检查（root用户执行）。

    ./vpatch -C | --check [ --rollbackId=patch_record_id | --rollbacktoId=patch_record_id] [--force]

    操作记录号patch_record_id被记录在升级历史信息中，升级历史信息可参见表2。

    • 若在做回退检查时指定了--force参数，则表示进行强制回退检查。注意：--force仅限于部分特殊场景使用时有效，一般情况下不推荐使用本功能，或联系技术人员进行判断和操作。

  • 为升级或回退做准备工作（root用户执行）。

    ./vpatch -P | --prepare [ --rollbackId=patch_record_id]|--rollbackToId=patch_record_id]

    操作记录号patch_record_id被记录在升级历史信息中，升级历史信息可参见表2。

  • 执行升级。

    ./vpatch --upgrade

  • 执行回退，即回退掉升级记录中对应操作记录号patch_record_id所升级的补丁。

    ./vpatch --rollback=patch_record_id [--force]

    操作记录号被记录在升级历史信息中，升级历史信息可参见表2。

    • 若在做回退时指定了--force参数，则表示进行强制回退操作。注意：--force仅限于部分特殊场景使用时有效，一般情况下不推荐使用本功能，或联系技术人员进行判断和操作。

  • 执行连续回退。倒序遍历升级历史信息，逐个回退升级补丁，直至回退到指定操作记录号的补丁为止。

    ./vpatch --rollbackTo=patch_record_id

    • 注意此处指定的升级操作记录号patch_record_id也在回退范围内。

    • 操作记录号被记录在升级历史信息中，升级历史信息可参见表2。

  • 查看VPatch版本信息。

    ./vpatch -V | --version

  • 查看vpatch帮助信息。

    ./vpatch -? | --help

  • 显示VPatch同目录下升级补丁的信息。在rollback时显示回退的升级补丁的信息，在rollback to时显示最后一个被回退的升级补丁的信息。返回结果各参数信息参见表1：

    ./vpatch -I | --information

表1 补丁信息

参数 说明
vbVpatchInfo 供vpatch使用的信息列表。
patchNum 补丁编号。
patchFixedBugList 修补bug列表。
patchType 补丁类型。
patchReleaseDate 补丁发布日期。
compatibleProductVersionNum 保留参数。
patchConflictList 保留参数。
patchIncludeList 保留参数。
trunkKernelVersion 保留参数。
isUpdateCatalog 是否修改系统表。
isUpdateOnlyFunc 修改系统表，但仅限于函数。
allowRollback 补丁是否允许回退，true可以回退，false不可回退。
base_product_version 适配的基础版本。
baseSvn 原始版本的SVN提交号。
newSvn 新版本的SVN提交号。
isFallbackPatch 用于升级还是回退的补丁，true升级，false回退。
osInfo 适用的操作系统信息。
cpuInfo 适用的cpu信息。
deleteFile 此次升级删除的文件，包括数据库和om工具。

  • 显示升级历史信息。若补丁已被回退，则相关信息不在此处显示。此信息在用户需要指定回退时尤为重要。返回结果各参数信息参见表2：

    需要回退时可以参考升级历史信息中提供的升级操作记录号patch_record_id，及升级补丁的相关信息，升级历史信息可参见表2。

    • 简略显示升级历史信息。

      ./vpatch -U [-s] | --upgradeInformation [--simple]

    • 完整显示升级历史信息。

      ./vpatch -U [-s] | --upgradeInformation --complete\

表2 升级历史信息参数说明

参数 说明
auditId 审计号。
patch_record_id 操作序列号。
patchNum 补丁编号。
date 升级操作的日期和时间。
opType 操作类型（One off patch，升级PSU，升级PSR）。
commitId svn提交号。
fixedBugs 修复的bug列表。
isUpdateCatalog 是否修改系统表。
isUpdateOnlyFunc 是否修改了函数。
isRollback 是否已被回退。
upgradeBackupPath 升级备份的目录。
patchConflictList 保留参数。
patchInlcudeList 保留参数。
vpatchVersion vpatch版本。
vpatchTmpDir vpatch临时文件目录。
vpatchLogDir vpatch日志目录。
newSVN 新版本的SVN提交号。
baseSVN 原始版本的SVN提交号。
deleteFile 此次升级删除的文件，包括数据库和om工具。
isFallbackPatch 用于升级还是回退的补丁，true表示升级，false表示回退。
allowRollback 补丁是否允许回退，true表示可以回退，false表示不可回退。
base_product_version 适配的基础版本。
osInfo 适用的操作系统信息。
cpuInfo 适用的cpu信息。
ConsumedOpSeqNum 数组的大小。

示例

前置准备

升级前请检查以下数据库参数是否配置正确，避免影响数据库升级。

logging_collector=on
enable_global_syscache=on
uppercase_attribute_name=off
enable_prevent_job_task_startup =on
vb_exclude_reserved_words = ''

示例1 升级操作。

1、关闭数据库。

vb_ctl stop

2、备份数据库目录，以vastbase_9104为例。

cp -a /home/vastbase/local/vastbase_9104 /home/vastbase/local/vastbase_9104_bak

3、切换到数据库安装用户，把补丁包解压放入/home/数据库安装用户/目录，进入patch文件夹下解压升级包。

补丁包以PSU_9104_9662_centos-7_x86-64-01-20221109.tar.gz为例。

su - vastbase
cd /home/vastbase
tar xf PSU_9104_9662_centos-7_x86-64-01-20221109.tar.gz
cd patch
tar xf 2-2.2-10-92-702-9104-centos-7-x86-64-01.tar.gz

4、创建配置文件。

  • PSU升级

    vi /home/vastbase/vpatch.ini
[vpatch]
userName=vastbase
userGroup=vastbase
appPath=/home/vastbase/local/vastbase
dataPath=/home/vastbase/data/vastbase
Port=5432
tmpPath=/home/vastbase/omTmp/tmp

  • OOP升级

    vi /home/vastbase/vpatch.ini

[vpatch]
userName=vastbase
userGroup=vastbase
appPath=/home/vastbase/local/vastbase
dataPath=/home/vastbase/data/vastbase
Port=5432
tmpPath=/home/vastbase/omTmp/tmp
vpatch_upgrade_file=home/vastbase/patch/Vastbase-G100-2,2 Build0(13998)-ubuntu aarch64-64bit-vpatch,tar.gz

5、使用root用户指定配置文件。

cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --setparam -f  /home/vastbase/vpatch.ini

返回结果如下表示成功：

6、使用root用户执行命令进行升级环境检查。

./vpatch -C

postgresql.conf配置文件中配置项port默认被注释，端口号为5432。

  • 若数据库需使用其它端口号请修改postgresql.conf配置文件。

  • 若使用5432端口则需要删除postgresql.conf中该配置项的注释符号。

返回结果如下表示成功：

7、使用root用户执行命令进行用户权限检查。

./vpatch -P

返回结果如下表示成功：

8、切换数据库初始化用户进行升级。

su - vastbase
cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --upgrade

结果返回如下表示成功：

9、升级完成后进行信息检查。

  • 简略显示升级历史信息。参数说明参考表2历史信息。

    ./vpatch -U -s

  • 完整信息升级记录信息。参数说明参考表2历史信息。

    ./vpatch -U -c

10、查看数据库升级日志。显示升级过程信息，包含停止服务、启动服务操作、执行的每个脚本文件、操作数据库的相关命令、变更的设置参数等内容。

当升级失败时，可查看vpatch日志获取错误信息。

  cat $GAUSSHOME/.update/updateLog/jq_vpatch_two/gs_upgradectlxxx.log

示例2 回退操作。

1、停止数据库服务。

vb_ctl stop

2、使用root用户指定配置文件。

cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --setparam -f  /home/vastbase/vpatch.ini

3、使用root用户执行命令进行回退环境检查。

./vpatch -C --rollbackId=0

4、使用root用户执行命令进行用户权限检查。

./vpatch -P --rollbackId=0

5、切换数据库初始化用户执行回退。

su - vastbase
cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --rollback=0

结果返回如下：

示例3 连续回退操作。

1、停止数据库服务。

vb_ctl stop

2、使用root用户指定配置文件。

cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --setparam -f  /home/vastbase/vpatch.ini

3、使用root用户执行命令进行环境检查。

./vpatch -C --rollbackToId=0

4、使用root用户执行命令进行用户权限检查。

./vpatch -P --rollbackToId=0

5、切换数据库初始化用户执行连续回退。

su - vastbase
cd /home/vastbase/patch/2-2.2-10-92-702-9104-centos-7-x86-64-01/VPatch/script
./vpatch --rollbackTo=0

结果返回如下：

示例4 显示vpatch同目录下升级补丁的信息。

./vpatch - I

结果返回如下：

参数说明参考表1补丁信息。

示例5 HAS1.2高可用集群升级操作。

1、root用户执行以下命令查看主备状态，/home/vastbase/has/bin/hasctl为hasctl工具目录。

/home/vastbase/has/bin/hasctl -c /home/vastbase/has/etc/patroni_conf.yml list

2、root用户登录备节点执行以下命令停止has：

systemctl stop has

3、root用户登录主节点执行步骤2命令停止主节点has。

4、复制postgresql.conf做配置文件备份。

cp postgresql.conf postgresql.conf.bak

5、注释所有节点postgresql.conf文件中的replconn参数，并修改port指定升级专用端口号，重启数据库。确认数据库可以正常启动后，停止所有节点的数据库服务进行升级操作。

6、升级参考示例1 升级操作分别对主备节点进行操作。

7、升级成功后，关闭数据库，恢复postgresql.conf文件主备及端口配置。可将步骤4备份的postgresql.conf.bak恢复为postgresql.conf。

8、root用户登录主节点，执行以下命令先启动主节点has：

systemctl start has

9、使用以下命令查看主节点状态，确认主节点状态正常。

/home/vastbase/has/bin/hasctl -c /home/vastbase/has/etc/patroni_conf.yml list

10、root用户登录备节点，执行以下命令启动备节点has：

systemctl start has

11、所有节点启动后执行以下命令查看集群状态是否正常。集群正常则升级成功。

/home/vastbase/has/bin/hasctl -c /home/vastbase/has/etc/patroni_conf.yml list

示例6 HAS V1.4共享存储集群升级操作。

1、进入 HAS 安装目录下的 bin 目录，使用root用户执行以下命令查看主备状态。

./sd_hasctl -c /home/vastbase/has/etc/vastbase.yml list

2、root用户登录备节点执行以下命令停止has：

systemctl stop has

3、root用户登录主节点执行步骤2命令停止主节点has。

4、在主节点使用 blkid 查询数据目录所在数据盘 uuid，使用 vgs 查询逻辑卷名称，激活逻辑卷并将数据盘挂载至/data 目录。

sudo vgchange -ay ${vg_name}
sudo mount -U ${uuid} /data

5、vastbase用户进入数据目录复制postgresql.conf做配置文件备份。

cp postgresql.conf postgresql.conf.bak

6、在主节点注释postgresql.conf文件中的replconn参数，并修改port指定升级专用端口号，使用vb_ctl命令重启数据库。确认数据库可以正常启动后，停止所有节点的数据库服务进行升级操作。

7、参考示例1对主节点进行升级操作。

8、因配置了共享存储，在备节点升级时需要重新初始化一个本地数据目录进行升级，参考以下命令在备节点初始化本地数据目录。其中-D 为数据库初始化实例路径，–nodename 为节点名称，-w 为初始用户密码，可根据需求修改。

vb_initdb -D /home/vastbase/data/vastbase --nodename vastbase -w vbase@123

9、在备节点参考示例1进行升级操作，升级完成后删除步骤7中初始化的本地数据目录。

10、主备升级成功后，关闭数据库，恢复主节点postgresql.conf文件参数及端口配置。可将步骤4备份的postgresql.conf.bak恢复为postgresql.conf。

11、root用户登录主节点，执行以下命令先启动主节点has：

systemctl start has

12、进入 HAS 安装目录下的 bin 目录，使用root用户执行以下命令查看主节点状态，确认主节点状态正常。

./sd_hasctl -c /home/vastbase/has/etc/vastbase.yml list

13、root用户登录备节点，执行以下命令启动备节点has：

systemctl start has

14、所有节点启动后进入 HAS 安装目录下的 bin 目录，使用root用户执行以下命令查看集群状态是否正常。集群正常则升级成功。

./sd_hasctl -c /home/vastbase/has/etc/vastbase.yml list

示例7 HAS V2.0高可用集群升级操作。

1、使用集群安装用户（以vastbase为例）登录任意节点，执行以下命令查看主备状态。

su - vastbase
has_ctl query -Cvi

2、root用户登录备节点执行以下命令停止has。

has_ctl stop

3、root用户登录主节点，执行步骤2的命令停止主节点has服务。

4、复制postgresql.conf做配置文件备份。

cp postgresql.conf postgresql.conf.bak

5、注释掉主备节点配置文件postgresql.conf中的replconn参数，并修改port指定升级专用端口号，重启数据库。确认数据库可以正常启动后，停止所有节点的数据库服务进行升级操作。

6、升级参考示例1对主备节点分别进行升级操作。

此处注意升级配置文件中的环境变量需与数据节点的环境变量一致，如升级文件中的appPath对应环境变量GAUSSHOME，两者必须严格一致，不能多‘/’。

7、升级成功后，刷新环境变量，因为升级过程留下的环境变量最后一步需手动执行，导致此时使用的gs_om还是升级包中的版本。 具体操作：

(1)执行步骤6升级操作的会话需exit至root用户再重新切回，或执行 source ~/.bashrc

(2)检查gs_om是否已恢复，若gs_om不在升级补丁包中则环境变量重新设置成功。

which gs_om

8、生成新的静态文件。

gs_om -t generateconf -X cluster_config.xml --distribute

  • 参数说明：

    • cluster_config.xml为初始化集群的配置文件。

    • --distribute直接分发新的配置文件到各节点。

  • 此步骤必须使用正确的gs_om（集群的gs_om），可参考步骤7进行检查

9、以安装用户登录主节点，并执行以下命令启动集群：

has_ctl  start

10、所有节点启动后执行以下命令查看集群状态是否正常。集群正常则升级成功。

has_ctl query -Cvi