Upgrade guide

Applicable version

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

Considerations

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

Procedure

Upgrade OAT from 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. In addition, OAT containers before V4.1 do not capture the SIGTERM signal. Therefore, you must manually kill the mysqld process in the OAT container, and then stop the OAT container for upgrade. Otherwise, an error may occur.

The following example describes how to upgrade OAT from V3.2.0 to V4.1.0:

1. Load the image of the target version.

   docker load -i oat_xxx_xxxxxxxx_xxx.tgz 
   

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

   Here is an example:

   docker load -i oat_4.3.1_20250303_arm.tgz
   

   The return result is as follows:

   Loaded image: xxx/oceanbase/oat:4.3.1_20250303_arm
   

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

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 return to the host.

      Here is an example:

      [root@xxx oat]# exit
      

3. View the data mount directory when the OAT V3.2 container is started 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, make sure that /data_dir is consistent when you start the OAT V4.3.1 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 <image of the target version>
   

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

   Here is an example:

   Start the OAT V4.3.1 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.1_20250303_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 succeeded.

OAT version before the upgrade is V4.1.1 or later

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 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.1_20250303_arm.tgz
   

   The return result is as follows:

   Loaded image: xxx/oceanbase/oat:4.3.1_20250303_arm
   

   In Step 5, you will 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, you must keep the /data_dir directory 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.1 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.1_20250303_arm
   

   The return result is as follows:

   12d0bb1685f066a83742e754c4f01a83063b6a5b14d3d5d401cb3a278cd20d3b
   

6. View the startup logs.

   docker logs -f oat
   

   When the startup logs stop refreshing, log in to OAT to check whether the upgrade is succeeded.