ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST

Last Updated:2026-09-04 09:48:50

Purpose

This statement is used to modify the source configuration of the backup or archive path for the current tenant, such as the zone, idc, or region. After modification, the new configuration will overwrite the original one.

Limitations and considerations

Only user tenants can execute this statement. System tenants (sys tenants) cannot execute this statement.
Before modifying the zone, idc, or region configuration of the path, if you need to set the region or IDC level, you need to use the ALTER SYSTEM MODIFY ZONE zone_name SET REGION=region_name; or ALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name; statement to set the region or IDC information respectively. It is recommended to set the source configuration at the IDC level. This allows you to utilize an IDC with abundant network bandwidth resources for backup tasks, providing more optional nodes for the tasks, and you do not need to be concerned about changes in zones within the IDC of the cluster.
When modifying the source configuration of the backup path, if a backup task is currently running, the running task will take at least a few minutes to detect the configuration changes. Therefore, during the configuration modification, there may still be nodes outside the new configuration accessing the backup path, resulting in cross-data center or cross-region traffic.

Privilege requirements

The user executing this statement must have the ALTER SYSTEM privilege. For more information about OceanBase Database privileges, see Privilege types in MySQL mode.

Syntax

ALTER SYSTEM {ALTER|CHANGE|MODIFY} EXTERNAL_STORAGE_DEST PATH [=] 'path' SET ATTRIBUTE = '{zone=zone_name | idc=idc_name | region=region_name}';

Parameters

Parameter	Description
path	Specifies the backup or archive path to be modified. If the archive medium is an object storage type, it also needs to include the host address and access key of the object storage. For example, when the archive medium is OSS, the path format is as follows: V4.2.5 BP3 and later versions: `oss://oceanbase-test-bucket/backup/databackup?host=xxxx` Note For V4.2.5 BP3 and later versions, to ensure compatibility with earlier versions, if the path format contains `access_key` and `access_id` information, it can also be set successfully. V4.2.5 BP2: `oss://oceanbase-test-bucket/backup/databackup?host=xxxx&access_key=xxxx&access_id=xxxx`
zone=zone_name \| idc=idc_name \| region=region_name	Specifies the source of the current backup or archive path. You can choose configurations at the `zone`, `idc`, or `region` level. You can only select one level or not set any. If not explicitly specified, it will default to not being set. When modifying the source configuration of the archive path: Since all traffic for log archiving is written by the leader replica, there is no access priority difference for log archive paths. It only restricts the node range that can access the archive path. If you need to set multiple zones, multiple IDCs, or multiple regions, separate the multiple values with commas (,) or semicolons (;). For example, `zone=z1,z2;z3` specifies `z1`, `z2`, and `z3` as the sources of the archive path. When modifying `zone`, `idc`, or `region`, the leader replica must be located in the specified `zone`, `idc`, or `region`. Otherwise, log archiving will not proceed. When modifying the source configuration of the backup path: If you need to set multiple zones, multiple IDCs, or multiple regions, separate the zones, IDCs, and regions with commas (,) and semicolons (;). Specifically: A comma (,) indicates that the nodes in the zones, IDCs, or regions on both sides have the same priority when selecting the execution nodes for the backup task. A semicolon (;) indicates that the nodes in the zone, IDC, or region on the left have a higher priority than those on the right. That is, the backup task will prioritize selecting nodes in the zone, IDC, or region on the left. For example, if set to `zone=z1,z2;z3`, it specifies `z1`, `z2`, and `z3` as the sources of the backup task. `z1` and `z2` have the same priority, and both have a higher priority than `z3`. When modifying the `zone`, `idc`, or `region` configuration of the backup path, the leader node of the Root Service must be located in the specified `zone`, `idc`, or `region`. Otherwise, the backup task will fail to write backup metadata to the target backup path, ultimately resulting in a failed backup task. It is recommended to include the primary zone range in the backup path source configuration.

Parameter

Description

path

Specifies the backup or archive path to be modified. If the archive medium is an object storage type, it also needs to include the host address and access key of the object storage. For example, when the archive medium is OSS, the path format is as follows:

V4.2.5 BP3 and later versions: oss://oceanbase-test-bucket/backup/databackup?host=xxxx

Note

For V4.2.5 BP3 and later versions, to ensure compatibility with earlier versions, if the path format contains access_key and access_id information, it can also be set successfully.
V4.2.5 BP2: oss://oceanbase-test-bucket/backup/databackup?host=xxxx&access_key=xxxx&access_id=xxxx

zone=zone_name | idc=idc_name | region=region_name

Specifies the source of the current backup or archive path. You can choose configurations at the zone, idc, or region level. You can only select one level or not set any. If not explicitly specified, it will default to not being set.

When modifying the source configuration of the archive path:

Since all traffic for log archiving is written by the leader replica, there is no access priority difference for log archive paths. It only restricts the node range that can access the archive path. If you need to set multiple zones, multiple IDCs, or multiple regions, separate the multiple values with commas (,) or semicolons (;). For example, zone=z1,z2;z3 specifies z1, z2, and z3 as the sources of the archive path.
When modifying zone, idc, or region, the leader replica must be located in the specified zone, idc, or region. Otherwise, log archiving will not proceed.

When modifying the source configuration of the backup path:

If you need to set multiple zones, multiple IDCs, or multiple regions, separate the zones, IDCs, and regions with commas (,) and semicolons (;). Specifically:
- A comma (,) indicates that the nodes in the zones, IDCs, or regions on both sides have the same priority when selecting the execution nodes for the backup task.
- A semicolon (;) indicates that the nodes in the zone, IDC, or region on the left have a higher priority than those on the right. That is, the backup task will prioritize selecting nodes in the zone, IDC, or region on the left.
For example, if set to zone=z1,z2;z3, it specifies z1, z2, and z3 as the sources of the backup task. z1 and z2 have the same priority, and both have a higher priority than z3.
When modifying the zone, idc, or region configuration of the backup path, the leader node of the Root Service must be located in the specified zone, idc, or region. Otherwise, the backup task will fail to write backup metadata to the target backup path, ultimately resulting in a failed backup task. It is recommended to include the primary zone range in the backup path source configuration.

Examples

Modify the source configuration of the archive path.

Assume that the original source configuration of the archive path is zone=z1,z2,z3. You need to change the source configuration to region=region1. After the modification, only nodes in region1 can access the path.

OSS

obclient> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'region=region1';

NFS

obclient> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/archive' SET ATTRIBUTE = 'region=region1';

S3

obclient> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'region=region1';

Object storage services that support the S3 protocol (OBS, GCS, and COS)

obclient> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'region=region1';

obclient> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ATTRIBUTE = 'region=region1';

obclient> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'region=region1';

Modify the source configuration of the backup path.

Assume that the original source configuration of the backup path is zone=z1,z2;z3. You need to change the source configuration to idc=idc1;idc2. After the modification, nodes in idc1 and idc2 can access the path. idc1 has a higher priority than idc2.

OSS

obclient> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'idc=idc1;idc2';

NFS

obclient> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/data' SET ATTRIBUTE = 'idc=idc1;idc2';

S3

obclient> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'idc=idc1;idc2';

Object storage services that support the S3 protocol (OBS, GCS, and COS)

obclient> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

obclient> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ATTRIBUTE = 'idc=idc1;idc2';

obclient> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

Previous topic

ALTER SEQUENCE

Last

Next topic

MAJOR and MINOR