# 操作指导
#### 前提条件
- 环境要求：
  - 所有服务器操作系统运行状态正常。
  
  - 网络环境稳定无异常。
   
- 依赖项：已成功执行前置脚本gs_preinstall完成环境预配置。
- 权限要求：需要使用执行gs_preinstall时指定的集群用户进行升级操作。
 
#### 语法
- 显示帮助信息。
  ```
  gs_upgradectl -? | --help
  ```
  
- 显示版本号信息。
  ```
  gs_upgradectl -V | --version
  ```
  
- 选择升级策略。
  ```
  gs_upgradectl -t chose-strategy [-l LOGFILE]
  ```
  
- 升级集群。
  ```
  gs_upgradectl -t auto-upgrade -X XMLFILE  --inplace [-l LOGFILE] [--force] [--ignoreVMFaults=HOSTNAME][--auto_script]
  ```
  
- 回滚升级。
  ```
  gs_upgradectl -t auto-rollback -X XMLFILE [-l LOGFILE] [--force] [--ignoreVMFaults=HOSTNAME][--auto_script]
  ```
  
- 升级提交。
  ```
  gs_upgradectl -t commit-upgrade -X XMLFILE [-l LOGFILE] [--force_commit] [--skip_rebalance_set]
  ```
  ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  一旦提交操作完成，则不能再执行回滚操作。
  
 
#### 核心约束
1. 业务要求
   - 就地升级需要停止业务运行。
   
   - 集群需满足：
     - 主备DN数据完全同步。
     
     - 运行状态正常。
      
    
2. 操作限制
   - 禁止与节点替换/扩容/缩容操作并行执行。
   
   - 不支持虚拟IP配置。
   
   - 升级期间禁用kerberos开关。
   
   - 就地升级中不支持Roach备份。
   
   - 禁止修改安装包内version.cfg文件。
    
3. 资源要求
   - DN节点磁盘使用率必须低于85%。
   
   - 升级后原归档日志失效。
   
   - 升级后原二进制目录将被清除，请不要存放个人数据。
    
4. 参数管控
   - 升级期间禁止修改以下GUC参数：wal_level、max_connections、max_prepared_transactions、max_locks_per_transaction。
   
   
   
   - 如果就地升级过程中出现异常导致升级失败，且自动回滚失败时，需要用户自动执行回滚命令进行手动回滚。回滚成功后GUC参数配置自动失效。
    
 
#### 进程故障升级约束
- 少数派VM故障或少数派进程故障升级约束：
  - 前置条件：
    1. 下发升级命令之前，集群状态至少为Degraded。
    
    2. 需要下发增加--ignoreVMFaults参数的升级命令。
     
  
  - 异常处理：
    - 升级过程中，若主流程VM节点故障，升级报错为正常报错，重新将升级命令下发至正常节点即可。
    
    - 通过增加--ignoreVMFaults参数，被隔离的节点不会被升级。升级后需通过节点替换完成集群修复。
    
    - 被隔离的进程会忽略掉无法启动的错误。
     
   
 
- 多数派进程故障升级约束：
  - 适用范围：
    - 只支持小版本升级，不支持大版本升级。
    
    - 由于"安装目录\\bin"下的gaussdb二进制文件损坏导致的故障时支持小版本强制升级，由于VM级故障导致的故障时不支持升级。
     
  
  - 强制升级限制：
    - 升级不带有修复功能，升级后不保证集群一定可用。
    
    - 强制升级未提交或回滚前，即使集群恢复正常，也无法进行正常的升级操作。
     
   
#### 就地升级操作步骤
1. 以root身份登录节点。
2. 进入安装包解压出的script目录下。 
   ```
   cd /opt/software/gaussdb_upgrade/script
   ```
   
   
3. 执行前置脚本gs_preinstall。
   
   ```
   ./gs_preinstall -U omm -G dbgrp -X /opt/software/GaussDB_Kernel/clusterconfig.xml --alarm-type=1 --non-interactive
   ```
   上述命令中的"clusterconfig.xml"为安装配置文件。
   
   
4. 切换至omm（集群用户）用户。 
   ```
   su - omm
   ```
   
   
5. 集群状态正常时，使用如下命令进行升级。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --inplace
   ```
   
   
6. 数据库状态正常时，使用如下命令自动生成升级脚本并进行升级。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --inplace --auto_script
   ```
   
   
7. 如果少数派VM或少数派进程故障，则使用如下命令进行升级。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --inplace --ignoreVMFaults=nodeName1,nodeName2,...
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   *nodeName1,nodeName2* *,...*代表集群中需要忽略的故障的节点名列表和有进程故障的节点名列表。
   
   
8. 如果因gaussdb二进制文件损坏导致多数派进程故障，需要执行小版本强制升级，可以使用如下命令。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --inplace --force
   ```
   
   

9. 升级版本查询。 
   ```
   gs_ssh -c "gsql -V"
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   若查询结果不是目标版本，可执行回滚后重新升级。
   
   
10. 检查升级集群状态。 
    ```
    cm_ctl query -Cdvi
    ```
    查询结果的Cluster State为normal代表集群正常。
    
    
11. 升级提交。 
    ```
    gs_upgradectl -t commit-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml
    ```
    ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
    一旦提交操作完成，则不能再执行回滚操作。
    
    
 
#### 就地升级版本回滚步骤
1. 执行如下命令完成版本回滚（回滚内核代码）。回滚完成，如果需要保持内核代码和om代码的一致，可以执行旧包的前置命令，依次执行[1]\~[3]，若要重新升级，则需按照步骤[1]\~[3]，重新执行新版本包的前置。
   
   ```
   gs_upgradectl -t auto-rollback -X /opt/software/GaussDB_Kernel/clusterconfig.xml
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   - 如果准备回滚的节点或节点上的少数派进程故障，则使用如下命令进行回滚。
     ```
     gs_upgradectl -t auto-rollback -X /opt/software/GaussDB_Kernel/clusterconfig.xml --ignoreVMFaults=nodeName1,nodeName2,...
     ```
     *nodeName1,nodeName2*,...代表集群中需要忽略的故障的节点名列表或有进程故障的节点名列表。
     需要在回滚时指定需要忽略的故障的节点名列表或有进程故障的节点名列表。
     
    
   
   
2. 查看回滚之后的版本号。 
   ```
   gsql -V
   ```