Upgrade guide|V4.4.0|OceanBase Admin Tool|docs|OceanBase Documentations

Applicable versions

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

Considerations

Versions earlier than OAT V3.2.0 do not support upgrade; only takeover is supported.
Indirect upgrade is only possible by first installing the new higher version of OAT and then 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 prior to OAT V4.1 do not catch the SIGTERM signal, you must manually kill the mysqld process inside the old OAT container before stopping the old OAT container for the upgrade. Otherwise, errors may occur.

Taking OAT V3.2.0 as an example, perform the upgrade according to the following steps:

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 return result 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.

Stop MariaDB inside the container.

View container information.

docker ps -a

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

Enter the OAT container.

docker exec -it <container_name> bash

Example:

docker exec -it oat bash

The result is as follows:

[root@xxx oat]#

Stop the running MariaDB service process (the actual process name may be mariadbd or mysqld depending on the MariaDB version).
```
pkill mariadbd;
```
```
pkill mysqld;
```
Check whether the MariaDB service is running and ensure no MariaDB processes are running.
```
pgrep 'mariadbd|mysqld'
```
No output means no MariaDB processes are running.
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
```

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.

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

Start the container of the target OAT version using the data-mounted 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-mounted directory.

Example:

Start the OAT V4.3.2 container using the data-mounted 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

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.

If the original OAT version before the upgrade is V4.1.1 or later

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

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.

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

View the data mount directory on the host specified when the OAT V4.1.1 container was started.
```
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 on the host corresponds to the /data directory inside the container. When you start the new version of OAT in Step 5, ensure that /data_dir remains consistent.

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

Use the data mount directory to start the container for 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:

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

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.