Upgrade guide

Applicable versions

Upgrading from OAT V3.2.0 and later versions to V4.4.1.

Considerations

• Versions earlier than OAT V3.2.0 do not support upgrade; only takeover is supported.
• Indirect upgrade is only possible by newly installing a higher version of OAT and taking over products or components managed by the old version.
• OAT V3.2.0 and later can be directly upgraded in-place.
• Do not perform the upgrade if there are any tasks that are currently running or have failed but have not been abandoned.

Procedure

Original OAT version before upgrade is V3.2.0 to V4.1.0

Because the MariaDB version in OAT V3.2/4.0 is earlier than that in OAT V4.1/4.2, and containers before OAT V4.1 do not capture the SIGTERM signal, you must first manually kill the mysqld process inside the old OAT container, then stop the old OAT container to proceed with the upgrade. Otherwise, errors may occur.

Taking OAT V3.2.0 as an example, follow these steps to perform the upgrade:

1. Load the new version image.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

   where oat_xxx_xxxxxxxx_xxx.tgz is the name of the new version installation package.

   Example:

   docker load -i oat_4.3.2_20250605_arm.tgz
   

   The response is as follows:

   Loaded image: xxx/oceanbase/oat:4.3.2_20250605_arm
   

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

2. Stop MariaDB inside the container.

   1. View container information.

      docker ps -a
      

      Example:

      docker ps -a
      

      The response 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. Enter the OAT container.

      docker exec -it <container_name> bash
      

      Example:

      docker exec -it oat bash
      

      The return result is as follows:

      [root@xxx oat]#
      

   3. Stop 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 and ensure no MariaDB processes are running.

      pgrep 'mariadbd|mysqld'
      

      No output is returned, indicating no MariaDB processes are running.

   5. Return to the host.

      Type exit and press Enter, or use the shortcut key Ctrl + D to return to the host.

      Example:

      [root@xxx oat]# exit
      

3. View the data mount directory on the host specified when starting the OAT V3.2 container.

   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 starting OAT V4.3.2 in Step 5, ensure that /data_dir remains consistent.

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 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 OAT data mount directory.

   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 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 was successful.

Original OAT version before upgrade is V4.1.1 or higher

You can perform an in-place upgrade directly. Taking OAT V4.1.1 as an example, follow these steps to upgrade:

1. Load the new version image.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

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

   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
   

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

2. View container information.

   docker ps -a
   

   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 on the host specified when starting the OAT V4.1.1 container.

   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 new version of OAT in Step 5, ensure that /data_dir remains consistent.

4. 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
   

5. Use the data mount directory to start the container of the target OAT version.

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

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

   Example:

   Use the data mount directory to start the OAT V4.3.2 container.

   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 logs.

   docker logs -f oat
   

   After the startup log refresh stops, log in to OAT to verify whether the upgrade was successful.