ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST|V4.2.5| docs|Distributed Database

ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST

Last Updated：2025-12-04 07:10:02 Updated

Purpose

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

Limitations and considerations

Only user tenants can execute this statement. The system tenant (sys tenant) cannot execute this statement.
Before modifying the zone, idc, or region configuration of the path, if you need to set the region level or IDC level, you must first 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 information or IDC information. It is recommended to set the source configuration at the IDC level. This allows you to use an IDC with abundant network bandwidth resources to execute backup tasks, while also expanding the range of optional nodes for backup tasks. Additionally, you do not need to pay attention to changes in zones within an IDC in the cluster.
When modifying the source configuration of the backup path, if there are ongoing backup tasks, the running tasks may take up to a few minutes to detect the configuration changes. Therefore, during the configuration modification, there may still be nodes outside the specified 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 classification in Oracle 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

Parameter	Description
path	Specifies the backup or archive path to be modified. If the backup or 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: `oss://oceanbase-test-bucket/backup/databackup?host=xxxx` Note For V4.2.5 BP3 and later, to maintain compatibility with older versions, if the path format includes `access_key` or `access_id` information, it can still 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. Supports selecting configurations at the `zone`, `idc`, or `region` levels. Only one level can be selected at a time, or none can be selected. If not explicitly specified, the default is to not set it. 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 nodes that can access the archive path. If you need to set multiple zones, multiple IDCs, or multiple regions, separate the values with commas (,) or semicolons (;). For example, `zone=z1,z2;z3` specifies `z1`, `z2`, and `z3` as the sources for archiving. When modifying `zone`, `idc`, or `region`, the leader replica must be 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/regions with commas (,) and semicolons (;). For example, if set to `zone=z1,z2;z3`, it specifies `z1`, `z2`, and `z3` as the backup sources. `z1` and `z2` have the same priority, and both have 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 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.

Specifies the backup or archive path to be modified. If the backup or 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: oss://oceanbase-test-bucket/backup/databackup?host=xxxx

Note

For V4.2.5 BP3 and later, to maintain compatibility with older versions, if the path format includes access_key or access_id information, it can still 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. Supports selecting configurations at the zone, idc, or region levels. Only one level can be selected at a time, or none can be selected. If not explicitly specified, the default is to not set it.

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 nodes that can access the archive path. If you need to set multiple zones, multiple IDCs, or multiple regions, separate the values with commas (,) or semicolons (;). For example, zone=z1,z2;z3 specifies z1, z2, and z3 as the sources for archiving.
When modifying zone, idc, or region, the leader replica must be 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/regions with commas (,) and semicolons (;). For example, if set to zone=z1,z2;z3, it specifies z1, z2, and z3 as the backup sources. z1 and z2 have the same priority, and both have 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 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 this 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';

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 this 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';

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