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

ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST

Last Updated：2026-03-06 07:02:42 Updated

Purpose

This statement is used to modify the source configuration (such as zone, idc, or region) of the backup or archive path, I/O throttling parameters (max_iops and max_bandwidth), and key information such as access_id and access_key for the current tenant. After the modification, the new configuration will overwrite the original configuration.

Limitations and considerations

Only user tenants can execute this statement. The sys tenant cannot execute this statement.
Before you modify the zone, idc, or region configurations of a 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 more network bandwidth resources for backup tasks, providing a wider range of optional nodes for the tasks. Additionally, you do not need to monitor changes in zones within the IDC of the cluster.
When modifying the source configuration of a backup path, if a backup task is currently running, the running task may take up to a few minutes to recognize the configuration changes. During this time, nodes outside the configured scope may still access the backup path, potentially generating cross-facility or cross-regional traffic.
Only object storage paths support changing I/O throttling parameters (max_iops and max_bandwidth) and access_id and access_key information. If you attempt to set I/O throttling parameters (max_iops and max_bandwidth) or access_id and access_key information for an NFS path, the system returns an unsupported error with the error code 1235.
When setting the ACCESS_INFO attribute (access_id and access_key information) for an object storage path, if the parameter format is incorrect (e.g., contains extra = signs or lacks access_id or access_key), the system returns the error OB_OBJECT_STORAGE_PERMISSION_DENIED (error code -9116).
When an object storage path uses Assume Role to access an object path:
- If you set ACCESS_INFO = 'access_id=new_access_id&access_key=new_access_key', the system returns an error.
- If you only set the I/O throttling parameters in ATTRIBUTE (without setting the ACCESS_INFO attribute), the system may indicate that the feature is unsupported or that the settings do not take effect.
You can set the same ATTRIBUTE + ACCESS_INFO attributes multiple times for the same path.

Privilege requirements

The user who executes this statement must have the ALTER SYSTEM privilege. For more information about the privileges of OceanBase Database, see Privilege classification in Oracle-compatible mode.

Syntax

ALTER SYSTEM {ALTER|CHANGE|MODIFY} EXTERNAL_STORAGE_DEST 
  PATH [=] 'path' 
  SET [ATTRIBUTE = '[{zone=zone_name | idc=idc_name | region=region_name}][&max_iops=iops_num][&max_bandwidth=bandwidth_num]']
  [ACCESS_INFO = 'access_id=new_access_id&access_key=new_access_key'];

Parameters

Parameter	Description
path	The backup path or archive path to be modified. If the backup or archive medium is of the object storage type, the host address, access key, and other information of the object storage are also required. For example, when the archive medium is OSS, the path is in the `oss://oceanbase-test-bucket/backup/databackup?host=xxxx` format.
zone=zone_name \| idc=idc_name \| region=region_name	The source of the current backup or archive path. You can specify `zone`, `idc`, or `region`. You can specify only one of the three parameters or none. If you do not specify any of them, the default value is not set. When you modify the source of the archive path: Since all log archive traffic is written by the leader replica, there is no access priority difference for log archive paths. The only restriction is on the nodes that can access the archive path. If you need to set multiple zones, IDCs, or 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 you modify `zone`, `idc`, or `region`, the leader replica must be in the specified `zone`, `idc`, or `region`. Otherwise, log archiving will fail. When you modify the source of the backup path: If you need to set multiple zones, IDCs, or regions, separate the zones, IDCs, and regions with commas (,) and semicolons (;). The following table describes the meanings of the two separators. A comma (,) indicates that the nodes in the zones, IDCs, or regions on both sides have the same priority when selecting the nodes to execute 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 nodes in the zone, IDC, or region on the left are prioritized for executing the backup task. For example, if you set `zone=z1,z2;z3`, it specifies `z1`, `z2`, and `z3` as the sources for backup. `z1` and `z2` have the same priority, and their priority is higher than that of `z3`. When you modify the `zone`, `idc`, or `region` 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, resulting in the failure of the backup task. We recommend that you set the backup path source to include the primary zone.
max_iops	The maximum IOPS allowed for the current backup or archive path. The value is a positive integer, indicating the number of I/O requests per second. If this parameter is not specified, the path does not limit IOPS, which is determined by the underlying object storage and network capabilities. Example: `max_iops=1000`
max_bandwidth	The maximum bandwidth allowed for the current backup or archive path. The value is a positive integer with a unit. Supported units are kb, mb, and gb, which represent KB/s, MB/s, and GB/s, respectively. If this parameter is not specified, the path does not limit bandwidth. Example: `max_bandwidth=1000mb`
access_id=new_access_id&access_key=new_access_key	The new `access_id` and `access_key` after the change. Both `access_id` and `access_key` must be specified.

Examples

Change the source endpoint configuration for an archive path

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

OSS

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

NFS

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/archive' SET ATTRIBUTE = 'region=region1';

obclient(SYS@oracle001)[SYS]> 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 compatible with the S3 protocol (OBS, GCS, and COS)

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'region=region1';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ATTRIBUTE = 'region=region1';

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

Change the source endpoint configuration for a backup path

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

OSS

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

NFS

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/data' SET ATTRIBUTE = 'idc=idc1;idc2';

obclient(SYS@oracle001)[SYS]> 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 compatible with the S3 protocol (OBS, GCS, and COS)

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

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ATTRIBUTE = 'idc=idc1;idc2';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

Change the `access_id` and `access_key` information for an archive path

OSS

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

Object storage services compatible with the S3 protocol (OBS, GCS, and COS)

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

Change the `access_id` and `access_key` information for a backup path

OSS

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

Object storage services compatible with the S3 protocol (OBS, GCS, and COS)

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

Set the I/O throttling parameters (`max_iops` and `max_bandwidth`) for an archive path

You can set the max_iops and max_bandwidth parameters at the same time or set one of the parameters separately. You can set the I/O throttling parameters only for object storage paths. You cannot set the I/O throttling parameters for NFS paths.

OSS

Set the max_iops and max_bandwidth parameters at the same time. Example:

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

Set the max_iops parameter separately. Example:

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000';

Set the max_bandwidth parameter separately. Example:

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_bandwidth=1000mb';

Set the max_iops and max_bandwidth parameters at the same time. Example:

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

Object storage services compatible with the S3 protocol (OBS, GCS, and COS)

Set the max_iops and max_bandwidth parameters at the same time. Example:

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

Set the I/O throttling parameters for the backup path (`max_iops` and `max_bandwidth`)

Note

Recommendations for setting I/O throttling parameters:

In a highly concurrent, bandwidth-sensitive multi-tenant environment, you can set different max_iops or max_bandwidth parameters for different backup paths to isolate the impact of backups on online business bandwidth and IOPS.
We recommend that you start with lower values and gradually adjust them based on your actual network bandwidth and object storage throttling strategy. For example, you can start by setting max_iops=500&max_bandwidth=100mb and then fine-tune the values based on the backup duration and business peak times.

You can set both the max_iops and max_bandwidth parameters, or set only one of them. I/O throttling parameters can be set only for object storage paths, not for NFS paths.

OSS

The following example shows how to set both the max_iops and max_bandwidth parameters.

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

The following example shows how to set only the max_iops parameter.

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000';

The following example shows how to set only the max_bandwidth parameter.

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_bandwidth=1000mb';

The following example shows how to set both the max_iops and max_bandwidth parameters.

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

Object storage services compatible with the S3 protocol (OBS, GCS, and COS)

The following example shows how to set both the max_iops and max_bandwidth parameters.

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

obclient(SYS@oracle001)[SYS]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST

Purpose

Limitations and considerations

Privilege requirements

Syntax

Parameters

Examples

Change the source endpoint configuration for an archive path

Change the source endpoint configuration for a backup path

Change the access_id and access_key information for an archive path

Change the access_id and access_key information for a backup path

Set the I/O throttling parameters (max_iops and max_bandwidth) for an archive path

Set the I/O throttling parameters for the backup path (max_iops and max_bandwidth)

Note

References

Change the `access_id` and `access_key` information for an archive path

Change the `access_id` and `access_key` information for a backup path

Set the I/O throttling parameters (`max_iops` and `max_bandwidth`) for an archive path

Set the I/O throttling parameters for the backup path (`max_iops` and `max_bandwidth`)