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 change the source-side configuration of the backup or archive path for the current tenant, including the zone, idc, or region configuration, I/O throttling parameters (max_iops and max_bandwidth), and key information such as access_id and access_key. The new configuration will overwrite the original configuration.

Limitations and considerations

Only user tenants can execute this statement. System tenants (sys tenants) cannot execute this statement.
Before you modify the zone, idc, or region configurations of a path, if you need to set the region 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 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 broader range of optional nodes. 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 period, 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) as well as 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 will return 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 (for example, if there are extra = signs or if access_id or access_key is missing), the system will return the error OB_OBJECT_STORAGE_PERMISSION_DENIED (error code -9116).
When accessing an object path using the Assume Role method for a backup path or an archive path:
- If you set ACCESS_INFO = 'access_id=new_access_id&access_key=new_access_key', the system will return an error.
- If you only set the I/O throttling parameters in the ATTRIBUTE section without setting the ACCESS_INFO attribute, the system may indicate that it is unsupported or that the settings will not take effect.
You can set the same ATTRIBUTE + ACCESS_INFO properties 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 types in MySQL-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 or archive path where the key information to be modified is stored. This path must be a backup or archive path that has been set for the current tenant, and it must be an object storage path that contains the `host` information. For example, the path format is `oss://oceanbase-test-bucket/backup/databackup?host=***` in the case of Alibaba Cloud OSS.
zone=zone_name \| idc=idc_name \| region=region_name	The source of the current backup or archive path. You can choose `zone`, `idc`, or `region` as the source. You can specify only one of them at a time or not specify any. If you do not explicitly specify a value, the default value is not set. When you modify the source of the archive path: Since all traffic of log archiving is written by the leader replica, the access priority of the log archive path does not vary. The only restriction is on the nodes that can access the archive path. If you want 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 of the archive path. When you modify `zone`, `idc`, or `region`, the leader replica must be in the specified `zone`, `idc`, or `region`. Otherwise, log archiving cannot proceed. When you modify the source of the backup path: If you want 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 nodes to execute the backup task. A semicolon (;) indicates that the nodes in the zone, IDC, or region on the left have 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 of the backup path. `z1` and `z2` have the same priority, and both have a higher priority than `z3`. When you modify 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, resulting in the failure of the backup task. We recommend that you set the source of the backup path 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 not explicitly set, the IOPS is not restricted, and the underlying object storage and network capabilities determine the IOPS. 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, representing KB/s, MB/s, and GB/s, respectively. If not explicitly set, the bandwidth is not restricted. Example: `max_bandwidth=1000mb`
access_id=new_access_id&access_key=new_access_key	The new `access_id` and `access_key` information after the change. Both `access_id` and `access_key` must be provided.

Examples

Change the source endpoint of an archive path

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

OSS

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

NFS

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

obclient(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'region=region1';

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

obclient(root@mysql001)[(none)]> 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 of a backup path

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

OSS

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

NFS

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

obclient(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

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

obclient(root@mysql001)[(none)]> 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` of an archive path

OSS

obclient(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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 that support the S3 protocol (OBS, GCS, and COS)

obclient(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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` of a backup path

OSS

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

obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE 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 that support the S3 protocol (OBS, GCS, and COS)

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

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

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

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

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

OSS

Set both the max_iops and max_bandwidth parameters. Example:

obclient(root@mysql001)[(none)]> 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 only the max_iops parameter. Example:

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

Set only the max_bandwidth parameter. Example:

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

Set both the max_iops and max_bandwidth parameters. Example:

obclient(root@mysql001)[(none)]> 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 that support the S3 protocol (OBS, GCS, and COS)

Set both the max_iops and max_bandwidth parameters. Example:

obclient(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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 I/O throttling parameters for backup paths (`max_iops` and `max_bandwidth`)

Note

Consider the following recommendations when you set I/O throttling parameters:

In a highly concurrent, bandwidth-sensitive multi-tenant environment, you can set different max_iops or max_bandwidth values for different backup paths to isolate the impact of backup operations 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 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 are supported 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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(root@mysql001)[(none)]> 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 of an archive path

Change the source endpoint of a backup path

Change the access_id and access_key of an archive path

Change the access_id and access_key of a backup path

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

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

Note

References

Change the `access_id` and `access_key` of an archive path

Change the `access_id` and `access_key` of a backup path

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

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