Upgrade Guide

Supported versions

OAT supports upgrades in the following two major version ranges:

• Range 1: [3.2.0, 4.4.1]
• Range 2: [4.3.0, 4.5.0]

Upgrade rules

• Intra-range upgrade: Within the same range, direct upgrades from lower to higher versions are typically supported.

• Cross-range upgrade: If you need to upgrade from one range to another (e.g., from Range 1 to Range 2), it must be done in two steps:

  1. First, upgrade the current version to a transitional version within the [4.3.0, 4.4.1] range.
  2. Then, upgrade from the transitional version to the target version.

  For example, to upgrade from V4.2.x to V4.5.0, you would first upgrade to a version within the V4.3.0~V4.4.1 range (such as V4.3.2), and then to V4.5.0.

Considerations

• In-place upgrades are not supported for OAT versions earlier than V3.2.0. For these older versions, it is recommended to use the takeover method. This involves deploying a new version of OAT and then using the "take over component" and "take over product" features to migrate the management of the existing environment.
• Before proceeding with the upgrade, ensure that there are no ongoing or failed but not abandoned tasks in OAT.

Procedure

The upgrade process for OAT varies depending on the current version:

• Scenario 1: Upgrading from OAT [V3.2.0, V4.1.0]
• Scenario 2: Upgrading from OAT V4.1.1 and later

Scenario 1: Upgrade from OAT [V3.2.0, V4.1.0] to a later version

Because the MariaDB version in OAT V3.2/4.0 is earlier than that in OAT V4.1/4.2, and OAT containers before V4.1 do not capture the sigterm signal, you must manually kill the mysqld process in the old OAT container, stop the old OAT container, and then perform the upgrade. Otherwise, an error may occur.

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

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.

   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
   

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

2. Stop MariaDB in the container.

   1. View 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. Enter 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 process name may be mariadbd or mysqld, depending on the MariaDB version).

      pkill mariadbd;
      

      pkill mysqld;
      

   4. Check whether MariaDB is running and ensure that no MariaDB process is running.

      pgrep 'mariadbd|mysqld'
      

      If no output is returned, no MariaDB process is running.

   5. Return to the host.

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

      Here is an example:

      [root@xxx oat]# exit
      

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

   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. When you start the OAT V4.3.2 container in Step 5, ensure that the /data_dir directory is consistent.

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

   Here is an example:

   Start the OAT V4.3.2 container 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 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 verify whether the upgrade is successful.

Scenario 2: Upgrade from OAT V4.1.1 and later

You can directly upgrade OAT V4.1.1 to the latest version. The following example shows how to upgrade OAT V4.1.1 to OAT V4.3.2.

1. Load the new version image.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

   In this example, oat_xxx_xxxxxxxx_xxx.tgz is the name of the new version installation package.

   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
   

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

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 on the host where the OAT V4.1.1 container is started.

   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, make sure that the /data_dir directory remains 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 by using the data mount directory.

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

   In this example, <data_dir> is the data mount directory of OAT.

   Here is an example:

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

   12d0bb1685f066a83742e754c4f01a83063b6a5b14d3d5d401cb3a278cd20d3b
   

6. View the startup log.

   docker logs -f oat
   

   After the startup log stops updating, log in to OAT to verify whether the upgrade is successful.