Upgrade OMS Community Edition V4.2.9-CE|V4.2.9|OceanBase Migration Service|OMS docs|Distributed Database

Upgrade OMS Community Edition V4.2.9-CE

Last Updated：2026-04-14 07:36:10 Updated

This topic describes how to upgrade OceanBase Migration Service (OMS) Community Edition from V4.2.0-CE to V4.2.9-CE.

Notice

OMS Community Edition V4.2.9-CE can only be upgraded from V4.2.0-CE to V4.2.8-CE. Upgrading from versions earlier than V4.2.0-CE to V4.2.9-CE is not supported.

Upgrade procedure

If the HA feature is enabled, disable it first.
1. Log in to the OMS Community Edition console.
2. In the left-side navigation pane, choose System Management > System Parameters.
3. On the System Parameters page, find ha.config.
4. Click the edit icon next to the parameter name Value.
5. In the Modify Value dialog box, set enable to false to disable the HA feature.
Back up the database.
1. Log in to IP1 and IP2, and stop the OMS Community Edition V4.2.8-CE service in the old container on the two servers.
```
sudo docker stop ${CONTAINER_NAME}
```
  Note
  
  CONTAINER_NAME specifies the name used to create the container.

# Configure the heartbeat database of the CM in the login configuration file.
mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -Dcm_hb_428

# Delete unnecessary records
# The heartbeat sequence is used to report heartbeats and obtain auto-increment IDs.
delete from heatbeat_sequence where id < (select max(id) from heatbeat_sequence);

Execute the following command to manually back up the rm, cm, and cm_hb databases to SQL files, and check whether the sizes of the files are not 0.

In multi-region scenarios, the cm_hb databases in all regions need to be backed up. For example, if there are two regions, four databases need to be backed up: rm, cm, cm_hb1, and cm_hb2.

  ```shell
  mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false rm_428 > /home/admin/rm_428.sql

  mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false cm_428 > /home/admin/cm_428.sql

  mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false cm_hb_428 > /home/admin/cm_hb_428.sql
  ```

  |           Parameter            |                                   Description                                   |
  |-------------------------|------------------------------------------------------------------------|
  | -h                      | The host information to be exported.                                                             |
  | -P                      | The port number for connecting to the database.                                                             |
  | -u                      | Specifies the username for the connection.                                                              |
  | -p                      | The password for connecting to the database.                                                              |
  | --triggers              | Specifies whether to export triggers. The default value is false, indicating that triggers are not exported. |
  | rm_428, cm_428, cm_hb_428 | Back up the rm, cm, and cm_hb databases as SQL files in the format of `database name > path to store the SQL file.sql`. Specify the actual values. |

Load the downloaded OMS Community Edition installation package to the local image repository of the Docker container.
```
docker load -i <installation package of OMS Community Edition>
```
Start the OMS Community Edition V4.2.9-CE container.

OMS Community Edition allows you to access the OMS Community Edition console through the HTTP and HTTPS protocols. If you want to access OMS Community Edition securely, you can configure an HTTPS self-signed certificate and mount it to the specified directory in the container. If you access OMS Community Edition using the HTTP protocol, no configuration is required.

Notice

When you start a new container of OMS Community Edition V4.2.9-CE, the mount paths of the three OMS Community Edition disks must be the same as those before the upgrade.
You can run the sudo docker inspect ${CONTAINER_NAME} | grep -A5 'Binds' command to view the mount paths of the disks in the old OMS Community Edition container.
In OMS Community Edition V3.3.1-CE and later, the parameter -e IS_UPGRADE=true is added. This parameter applies only to upgrade scenarios and must be added in upgrade scenarios.
Replace work.oceanbase-dev.com/obartifact-store/oms:${IMAGE_TAG} with the image name imported by using the docker load -i command.

OMS_HOST_IP=xxx
CONTAINER_NAME=oms_xxx
IMAGE_TAG=feature_x.x.x-ce

docker run -dit --net host \
-v /data/config.yaml:/home/admin/conf/config.yaml \
-v /data/oms/oms_logs:/home/admin/logs \
-v /data/oms/oms_store:/home/ds/store \
-v /data/oms/oms_run:/home/ds/run \
# You need to set the following two parameters only if you mount an HTTPS certificate to the OMS container.
-v /data/oms/https_crt:/etc/pki/nginx/oms_server.crt
-v /data/oms/https_key:/etc/pki/nginx/oms_server.key
-e OMS_HOST_IP=${OMS_HOST_IP} \
-e IS_UPGRADE=true \
--privileged=true \
--pids-limit -1 \
--ulimit nproc=65535:65535 \
--name ${CONTAINER_NAME} \
work.oceanbase-dev.com/obartifact-store/oms:${IMAGE_TAG}

Parameter	Description
OMS_HOST_IP	The IP address of the host. Note: The `OMS_HOST_IP` value of each node is different.
CONTAINER_NAME	The name of the container created.
IMAGE_TAG	After you load the OMS Community Edition installation package using Docker, you can run the `docker images` command to obtain the [IMAGE ID] or [REPOSITORY:TAG] of the loaded image. This identifier is the unique `<OMS_IMAGE>` for the image.

/data/oms/oms_logs, /data/oms/oms_store, and /data/oms/oms_run can be replaced with the mount directories created on your OMS Community Edition deployment machine, which respectively store the log files generated during the operation of OMS Community Edition, the files generated by the log pulling component, and the files generated by the synchronization component for persistence on the local machine.
Note:
During subsequent redeployment or upgrades, the location of the mount directories must remain unchanged. /home/admin/logs, /home/ds/store, and /home/ds/run are fixed directories within the container, and their paths cannot be modified. | /data/oms/https_crt (optional)
/data/oms/https_key (optional) | The mount path of the HTTPS certificate in the OMS Community Edition container. If the HTTPS certificate is mounted, the Nginx service in the OMS Community Edition container runs in HTTPS mode. You must access the OMS Community Edition console in HTTPS mode. | | IS_UPGRADE | In an upgrade scenario, you must set IS_UPGRADE=true. Note that IS_UPGRADE must be in uppercase. | | privileged | Grants extended privileges to the container. | | pids-limit | The number of processes allowed in the container. -1 indicates no limit. | | ulimit nproc | Specifies the maximum number of user processes. |

Access the new container.
```
docker exec -it ${CONTAINER_NAME} bash  
```
Note

CONTAINER_NAME specifies the name used to create the container.
In the root directory, initialize the metadata.
```
sleep 300
bash /root/docker_init.sh
```
Note
- After you execute the preceding commands, the script automatically applies the schema changes to the three databases of OMS Community Edition.
- If the configuration files (mainly cm_nodes) of multiple nodes in the same region are the same, you need to run docker_init.sh only once for the region.
  If the configuration files (mainly cm_nodes) of multiple nodes in the same region are different, you need to run docker_init.sh on each node.
If the command returns an error like Version before 4.1.1 is not allowed to upgrade, perform the following operations.
1. Make sure that the OMS Community Edition to be upgraded is not earlier than V4.1.1-CE.
2. Execute the following SQL statement in the rm database.
```
CREATE TABLE IF NOT EXISTS `oms_version` (
```

version varchar(64) NOT NULL COMMENT 'Version', gmt_modified timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (version) CREATE TABLE version ( id int(11) NOT NULL AUTO_INCREMENT COMMENT 'Primary key', REPLACE INTO oms_version(version) VALUES('x.x.x-CE'); --Fill in the actual OMS Community Edition version number before the upgrade here.

`description` varchar(255) DEFAULT NULL COMMENT 'Description',
3. Execute the initialization command again.
`update_time` datetime NOT NULL COMMENT 'Update time',
  PRIMARY KEY (`id`)
) DEFAULT CHARSET = utf8mb4 COMMENT = 'Version Table';

      REPLACE INTO `oms_version`(`version`) VALUES('x.x.x-CE');  -- Replace x.x.x with the actual version number of OMS Community Edition before the upgrade.
      ```

3. Run the initialization command again.

7. After the `docker_init.sh` script is executed, check whether the list of machines and the status of the machines are normal. In the **<UI-TERM key="oms-community.Operation.constants.Online">Online</UI-TERM>** status is displayed for each machine.

   1. Log in to the OMS Community Edition console.

   2. In the left-side navigation pane, choose **<UI-TERM key="oms-community.Welcome.constants.OMMonitoring">OPS & Monitoring</UI-TERM>** \> **<UI-TERM key="oms-community.Operation.Machine.Machine">Server</UI-TERM>**.

   3. On the **<UI-TERM key="oms-community.Operation.Machine.MachineList">Servers</UI-TERM>** page, check whether the machine list is properly displayed. Make sure that the status of each machine is **<UI-TERM key="oms-community.Operation.constants.Online">Online</UI-TERM>**.

8. After upgrading the two nodes, enable the HA feature and set the related parameters on the **<UI-TERM key="oms-community.Audit.constants.SystemParameters">System Parameters</UI-TERM>** page.

   1. Log in to the OMS Community Edition console.

   2. In the left-side navigation pane, choose **<UI-TERM key="oms-community.utils.hooks.useLayoutMenus.SystemManagement">System Management</UI-TERM>** \> **<UI-TERM key="oms-community.layout.constants.SystemParameters">System Parameters</UI-TERM>**.

   3. On the **<UI-TERM key="oms-community.utils.hooks.useLayoutMenus.SystemParameters">System Parameters</UI-TERM>** page, find `ha.config`.

   4. Click the edit icon next to the parameter name **<UI-TERM key="oms-community.pages.SystemParam.Value">Value</UI-TERM>**.

   5. In the **<UI-TERM key="oms-community.pages.SystemParam.ModifyAValue">Modify Value</UI-TERM>** dialog box, set `enable` to `true` to enable the HA feature. Record the time as T2.

You can also set `perceiveStoreClientCheckpoint` to `true`. In this case, you do not need to record the T1 and T2 timestamps.

   6. If you set `perceiveStoreClientCheckpoint` to `false`, you must modify the value of `refetchStoreIntervalMin` (the interval for initiating a store pull request, in minutes) based on your business requirements. The modified value must be greater than the value of T2-T1.

If you set `perceiveStoreClientCheckpoint` to `true`, you can keep the default value of `refetchStoreIntervalMin`. In HA mode, the system starts a store based on the earliest timestamp of the downstream component minus the value of `refetchStoreIntervalMin`. For example, if the earliest requested timestamp of the downstream connector or JDBC connector is 12:00:00 and the value of `refetchStoreIntervalMin` is set to 30 minutes, the system starts a store with the timestamp of 11:30:00 in HA mode.

After the HA feature is enabled, HA performs corresponding processing on components, as shown in the following table.

      <table>
         <tr>
         <td><b>Task/Component status before upgrade</b></td>
         <td><b>After the upgrade (HA is disabled)</b></td>
         <td><b>After upgrade (HA enabled)</b></td>
         </tr>
         <tr>
         <td>The task is running normally. <ul>  <li>The Incr-Sync component is running normally. <li>The Store component is running normally. </ul>     </td>
         <td rowspan="2">  The task status remains unchanged<ul> <li>The Incr-Sync component fails. </li> <li>The Store component fails.   </ul> </td>
         <td  rowspan="2">The task status remains unchanged.
         <ul><li>HA will automatically start the Incr-Sync component. </li><li>HA will create store components based on the configurations. For more information, see <a href="../1000.system-management/400.system-parameters/200.modify-ha-configurations.md">Modify HA configurations</a>. </li> </ul>
         </td>
         </tr>
         <tr>
         <td>Task failure <ul> <li>Incr-Sync component exception <li> Store component exception</li>     </td>
         </tr>
         <tr>
         <td>Task suspended<ul>    <li>Incr-Sync component is suspended. <li>The store component is running normally.    </ul>    </td>
         <td>The task status remains unchanged.<ul><li>The Incr-Sync component is suspended. <li>The store component encounters an exception.   </ul> </td>
         <td>The task status remains unchanged.
         <ul>
         <li>The Incr-Sync component is paused. </li>
         <li>HA will create a store component based on the configuration. For more information, see <a href="../1000.system-management/400.system-parameters/200.modify-ha-configurations.md">Modify HA configurations</a>.</li>
         </ul>
         </td>
         </tr>
      </table>

9. (Optional) If you want to perform a rollback operation, perform the following steps.

    1. Perform the operation in Step 1 to disable the HA feature.

    2. Pause the new container after the upgrade is paused, and record the time as T3.

          ```shell
          sudo docker stop ${CONTAINER_NAME}
          ```

    3. Connect to the Meta Database and execute the following command.

          ```shell
          drop database rm_428;
          drop database cm_428;
          drop database cm_hb_428;

          create database rm_428;
          create database cm_428;
          create database cm_hb_428;
          ```

    4. Restore the database by using the SQL file that you backed up in Step 2.

          ```shell
          mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/rm_428.sql" -Drm_428

          mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/cm_428.sql" -Dcm_428

          mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/cm_hb_428.sql" -Dcm_hb_428
          ```

    5. Restart the OMS Community Edition V4.2.8-CE container.

OceanBase

Customer Stories

Documentation

Enterprise Edition

Community Edition

Upgrade OMS Community Edition V4.2.9-CE

Notice

Upgrade procedure

Note

Notice

Note

Note