Upgrade Guide

Applicable versions

OceanBase Admin Toolkit (OAT) V3.2.0 and later can be upgraded to V4.3.2.

Considerations

• OAT of a version earlier than V3.2.0 cannot be upgraded and can only be taken over.
• To indirectly upgrade an earlier version, you can install a later version of OAT and then take over the products and components managed in the earlier version.
• OAT V3.2.0 and later support in-place upgrade.
• Do not perform an upgrade if there are running tasks or tasks that failed but are not discarded.

Procedure

OAT V3.2.0 to V4.1.0

The version of MariaDB in OAT V3.2 and V4.0 is earlier than that in OAT V4.1 and V4.2. In addition, the containers of OAT versions earlier than V4.1 do not catch the SIGTERM signal. Therefore, before you upgrade OAT, you must manually kill the mysqld process in the container of the earlier OAT version and then stop the earlier container. Otherwise, an error may occur.

Take OAT V3.2.0 as an example. Perform the following steps to upgrade OAT:

1. Load the image of the new version.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

   Here, oat_xxx_xxxxxxxx_xxx.tgz is the name of the installation package of the new version.

   Example:

   docker load -i oat_4.3.2_20250605_arm.tgz
   

   The following result is returned:

   Loaded image: xxx/oceanbase/oat:4.3.2_20250605_arm
   

   This image will be used when you start the OAT container in Step 5.

2. Stop MariaDB in the container.

   1. Query container information.

      docker ps -a
      

      Example:

      docker ps -a
      

      The following result is returned:

      CONTAINER ID        IMAGE                                                         COMMAND                  CREATED             STATUS              PORTS               NAMES
      56204b8e2f55        xxx/oceanbase/oat:3.2.0_20220819_arm   "/oat/distribution/p…"   About an hour ago   Up About an hour                        oat
      

   2. Log in to the oat container.

      docker exec -it <Container name> bash
      

      Example:

      docker exec -it oat bash
      

      The following result is returned:

      [root@xxx oat]#
      

   3. Terminate the running MariaDB service processes. Depending on the MariaDB version, the actual process name may be mariadbd or mysqld.

      pkill mariadbd;
      

      pkill mysqld;
      

   4. Check whether MariaDB is still running and make sure that no MariaDB process is running.

      pgrep 'mariadbd|mysqld'
      

      No output indicates that no MariaDB process is running.

   5. Return to the host.

      Press Enter after you enter exit, or press the shortcut keys Ctrl + D to return to the host.

      Example:

      [root@xxx oat]# exit
      

3. Query the data mount directory on the host that is specified when you start the container of OAT V3.2.0.

   docker inspect <Container name> -f '{{.Mounts}}'
   

   Example:

   docker inspect oat -f '{{.Mounts}}'
   

   The following result is returned:

   [{bind  /data_dir /data   true rprivate}]
   

   The /data_dir directory on the host corresponds to the /data directory in the container. When you start the OAT V4.3.2 container in Step 5, you must keep /data_dir unchanged.

4. Stop and delete the OAT V3.2 container.

   docker stop <Container name> && docker rm <Container name>
   

   Example:

   docker stop oat && docker rm oat
   

   The following result is returned:

   oat
   oat
   

5. Start the container of the target OAT version by using the data mount directory.

   docker run -d --name oat --net host -v <data_dir>:/data --restart on-failure:5 <New image>
   

   Here, <data_dir> is the data mount directory of OAT.

   Example:

   To start the container of OAT V4.3.2 by using the data mount directory:

   docker run -d --name oat --net host -v /data_dir:/data --restart on-failure:5 xxx/oceanbase/oat:4.3.2_20250605_arm
   

   The following result is returned:

   12c9d898449e542718934f74a401724f6c5359206738956c7350168759a7338a
   

6. View the startup logs.

   docker logs -f oat
   

   After the startup logs stop refreshing, log in to OAT to verify whether the upgrade is successful.

The original OAT version is V4.1.1 or later

You can directly perform an in-place upgrade. Take OAT V4.1.1 as an example. Perform the following steps to upgrade OAT:

1. Load the image of the new version.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

   Here, oat_xxx_xxxxxxxx_xxx.tgz is the name of the installation package of the new version.

   Example:

   docker load -i oat_4.3.2_20250605_arm.tgz
   

   The following result is returned:

   Loaded image: xxx/oceanbase/oat:4.3.2_20250605_arm
   

   This image will be used when you start the OAT container in Step 5.

2. Query the data mount directory on the host that is specified when you start the container of OAT V4.1.1.

   docker inspect <Container name> -f '{{.Mounts}}'
   

   Example:

   docker inspect oat -f '{{.Mounts}}'
   

   The following result is returned:

   [{bind  /data_dir /data   true rprivate}]
   

   The /data_dir directory on the host corresponds to the /data directory in the container. When you start the container of the new OAT version in Step 5, you must keep /data_dir unchanged.

3. Stop and delete the OAT V4.1.1 container.

   docker stop <Container name> && docker rm <Container name>
   

   Example:

   docker stop oat && docker rm oat
   

   The following result is returned:

   oat
   oat
   

4. Start the container of the target OAT version by using the data mount directory.

   docker run -d --name oat --net host -v <data_dir>:/data --restart on-failure:5 <New image>
   

   Here, <data_dir> is the data mount directory of OAT.

   Example:

   To start the container of OAT V4.3.2 by using the data mount directory:

   docker run -d --name oat --net host -v /data_dir:/data --restart on-failure:5 xxx/oceanbase/oat:4.3.2_20250605_arm
   

   The following result is returned:

   12d0bb1685f066a83742e754c4f01a83063b6a5b14d3d5d401cb3a278cd20d3b
   

5. View the startup logs.

   docker logs -f oat
   

   After the startup logs stop refreshing, log in to OAT to verify whether the upgrade is successful.