Upgrade guide

Applicable versions

OAT V3.2.0 and later versions can be upgraded to V4.3.2.

Considerations

• OAT of a version earlier than V3.2.0 is not supported to be upgraded; only takeover is supported.
• You can install a new high-version OAT and use it to take over the services and components managed by the old version.
• OAT V3.2.0 and later versions can be directly upgraded in place.

Procedure

The original version of OAT is V3.2.0 to V4.1.0

The MariaDB version in OAT V3.2/4.0 is earlier than that in OAT V4.1/4.2. Moreover, the containers of OAT versions earlier than V4.1 do not capture the sigterm signal. Therefore, you must manually kill the mysqld process in the OAT container before you stop the OAT container for upgrade, 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.

   Here is an example:

   docker load -i oat_4.3.2_20250605_arm.tgz
   

   The return result is as follows:

   Loaded image: xxx/oceanbase/oat:4.3.2_20250605_arm
   

   You will use this image to start the OAT container in Step 5.

2. Stop MariaDB in the container.

   1. View the container information.

      docker ps -a
      

      Here is an example:

      docker ps -a
      

      The return result is as follows:

      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. Go to the OAT container.

      docker exec -it <container name> bash
      

      Here is an example:

      docker exec -it oat bash
      

      The return result is as follows:

      [root@xxx oat]#
      

   3. Terminate the running MariaDB service process. (The actual process name may be mariadbd or mysqld depending on the MariaDB version.)

      pkill mariadbd;
      

      pkill mysqld;
      

   4. Check whether the MariaDB service is running to ensure that there is no running MariaDB process.

      pgrep 'mariadbd|mysqld'
      

      If there is no return, it indicates that there is no running MariaDB process.

   5. Go back to the host.

      Enter exit and press Enter, or press the shortcut key Ctrl + D to go back to the host.

      Here is an example:

      [root@xxx oat]# exit
      

3. View the data mount directory of the OAT V3.2 container on the host.

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

   Here is an example:

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

   The return result is as follows:

   [{bind  /data_dir /data   true rprivate}]
   

   The /data_dir directory on the host corresponds to the /data directory in the container. In Step 5, the /data_dir directory must be consistent when you start the OAT V4.3.2 container.

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

   docker stop <container name> && docker rm <container name>
   

   Here is an example:

   docker stop oat && docker rm oat
   

   The return result is as follows:

   oat
   oat
   

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

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

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

   Here is an example:

   Start the OAT V4.3.2 container 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 return result is as follows:

   12c9d898449e542718934f74a401724f6c5359206738956c7350168759a7338a
   

6. View the startup log.

   docker logs -f oat
   

   After the startup log stops refreshing, log in to OAT to check whether the upgrade is successful.

OAT was V4.1.1 or later before the upgrade

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

1. Load the new image.

   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.

   Here is an example:

   docker load -i oat_4.3.2_20250605_arm.tgz
   

   The return result is as follows:

   Loaded image: xxx/oceanbase/oat:4.3.2_20250605_arm
   

   In step 5, use this image to start the OAT container.

2. View the container information.

   docker ps -a
   

   Here is an example:

   docker ps -a
   

   The return result is as follows:

   CONTAINER ID        IMAGE                                                         COMMAND                  CREATED             STATUS              PORTS               NAMES
   09534958453a        xxx/oceanbase/oat:4.1.1_20230519_arm   "/oat/distribution/p…"   3 minutes ago       Up 3 minutes                            oat
   

3. View the data mount directory specified for OAT V4.1.1 on the host.

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

   Here is an example:

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

   The return result is as follows:

   [{bind  /data_dir /data   true rprivate}]
   

   The /data_dir directory on the host corresponds to the /data directory in the container. In step 5, ensure that the /data_dir directory is consistent.

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

   docker stop <container name> && docker rm <container name>
   

   Here is an example:

   docker stop oat && docker rm oat
   

   The return result is as follows:

   oat
   oat
   

5. Start the OAT container of the target version 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.

   Here is an example:

   Start the OAT V4.3.2 container 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 return result is as follows:

   12d0bb1685f066a83742e754c4f01a83063b6a5b14d3d5d401cb3a278cd20d3b
   

6. View the startup log.

   docker logs -f oat
   

   After the startup log stops refreshing, log in to OAT to check whether the upgrade is succeeded.