Purpose
The ALTER SYSTEM SET DATA_BACKUP_DEST statement is used to configure the backup destination for user tenants, specifying the backup path and source configuration for data backups.
Limitations and considerations
The system tenant and the Meta tenant do not support backup and restore, so you do not need to configure a backup destination.
Currently, OceanBase AI Database supports the following backup media: NFS, Azure Blob, AWS S3, and object storage compatible with the S3 protocol, such as Huawei OBS, Google GCS, and Tencent Cloud COS. Some backup media may require meeting specific basic requirements before they can be used. For details about the requirements for each backup medium, see Backup media requirements in Overview of physical backup and restore.
Privilege requirements
It must be executed by the root user of the sys tenant (root@sys) or the administrator user of a user tenant (root user).
Syntax
ALTER SYSTEM SET DATA_BACKUP_DEST = 'data_backup_path' [TENANT = tenant_name];
Parameters
Parameter |
Description |
|---|---|
| data_backup_path | Specifies the backup path for data backup. For more information about this parameter, see data_backup_path below. |
| tenant_name | The system tenant specifies the name of the tenant for which backup destination configuration is to be performed.
NoticeOnly the system tenant needs to specify the target tenant via the |
data_backup_path
It is used to specify the backup path and source configuration for data backup. The following describes the format of data_backup_path for different types of media.
NFS
ALTER SYSTEM SET DATA_BACKUP_DEST = 'file://your-nfs-server/your-backup-path[?{zone=zone_name | idc=idc_name | region=region_name}]';
Where:
file://your-nfs-server/your-backup-path: The path on the NFS server accessible to OceanBase AI Database for storing data backups.zone,idc,region: Specifies the source for the backup path, that is, the range of nodes that can access this path and their access priority. These are optional parameters, separated from the backup path by a question mark (?). You can select configurations at three different levels:zone,idc, orregion. Only one level can be selected at a time, or none at all. The default is not to set any.When specifying the
zone,idc, orregionfor the backup path, the leader node of the Root Service must reside within the specifiedzone,idc, orregion. Otherwise, the backup task will fail to write backup metadata to the target backup path, leading to task execution failure. It is recommended to set the source backup path to include the primary zone.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;orALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name;statement to configure the region or IDC information. It is recommended to set the source configuration at the IDC level. This way, the backup task can leverage an IDC with more network bandwidth resources, providing a wider range of available nodes. Additionally, users do not need to worry about changes in zones within the IDCs of the cluster.If the specified
zone,idc, orregiondoes not exist, an error will be returned indicating that the source information does not exist (error code-9133).To specify multiple zones, IDCs, or regions, separate the values with commas (,) and semicolons (;). For example:
- A comma (,) indicates that nodes within the zones, IDCs, or regions on either side have the same priority when selecting nodes to execute the backup task.
- An English semicolon (;) indicates that a node in the left Zone/IDC/Region has a higher priority than one in the right. That is, a node in the left Zone/IDC/Region is preferentially selected to perform the backup task.
For example, if you set it to
zone=z1,z2;z3, it specifiesz1,z2, andz3as the source zones for backup.z1andz2have the same priority, and their priority is higher than that ofz3.After setting the backup source at the backup path, changes to the cluster's zone, IDC, or region, such as name changes or the deletion of a zone/IDC/region, may prevent backup operations from being executed properly, ultimately causing the backup task to fail.
Object storage
# AWS S3
ALTER SYSTEM SET DATA_BACKUP_DEST = 's3://your-bucket-name/your-archive-path?host=s3.your-region.amazonaws.com&access_id=your-access-id&access_key=your-access-key&s3_region=your-s3-region[&delete_mode={delete | tagging}][&checksum_type={md5 | crc32}][&{zone=zone_name | idc=idc_name | region=region_name}]';
# Object storage compatible with the S3 protocol
ALTER SYSTEM SET DATA_BACKUP_DEST = 's3://your-bucket-name/your-archive-path?host=your-service.com&access_id=your-access-id&access_key=your-access-key[&addressing_model={virtual_hosted_style | path_style}][&checksum_type=md5][&{zone=zone_name | idc=idc_name | region=region_name}]';
# Azure Blob
ALTER SYSTEM SET DATA_BACKUP_DEST = 'azblob://your-bucket-name/your-archive-path?host=http://your-storage-account.blob.core.windows.net&access_id=your-access-id&access_key=your-access-key[&delete_mode={delete | tagging}][&checksum_type={md5 | no_checksum}][&{zone=zone_name | idc=idc_name | region=region_name}]';
The related parameters are described as follows:
Notice
When using object storage as the backup medium, the parameters for the object storage path are separated by the & symbol. Ensure that the parameter values you enter consist only of uppercase and lowercase letters, numbers, /-_$+=, and wildcard characters. Entering any other characters may cause the setup to fail.
host: The access domain name of the object storage service.For Azure Blob object storage, the value for the
hostparameter can be obtained by concatenating the container properties or the storage account connection string. The prefix of thehostparameter must be specified ashttp://orhttps://. In addition, Azure Blob has security transmission enabled by default, and access is typically throughhttps://. If you need to access throughhttp://, you must disable the security transmission option for Azure Blob. For detailed operations on disabling the security transmission option for Azure Blob, see Azure Blob official documentation.access_id=your-access-id: The access key ID for object storage.access_key=your-access-key: The access key for object storage.delete_mode: Specifies the cleanup mode for backup files after the backup path. This parameter is supported for AWS S3, COS (accessed via the S3 protocol), and Azure Blob storage services. Multiple options are separated by the&symbol. Currently, the following two values are supported:delete: Indicates that the cleanup mode is to directly delete backup files that meet the cleanup criteria.After this mode is enabled, when you automatically clean up backup files, the system will directly delete backup files that meet the cleanup criteria.
tagging: The cleanup mode sets aTagfor backup files that meet the cleanup criteria, and the backup files will still be retained.After this mode is enabled, when you automatically clean up backup files, the system will tag the backup files that meet the cleanup criteria. The tag's
keywill be"delete_mode"and itsvaluewill be"tagging". This allows users to subsequently manage the lifecycle of these files on object storage based on the set tag.
checksum_type: Specifies the checksum algorithm used to verify the integrity of backup data. If not explicitly specified, MD5 is used by default for all object storages. The supported values for this parameter vary by object storage:md5: uses the MD5 algorithm to verify the integrity of backup data.Notice
MD5 verification does not take effect for the
GetObjectAPI.no_checksum: Does not verify the integrity of backup data. This value is supported only for Azure Blob storage. For object storage accessed through the S3 protocol, including AWS S3, OBS, GCS, and COS, this value is not supported due to limitations of the S3 SDK.crc32: Uses the CRC32 algorithm to verify the integrity of backup data. This value is supported only by AWS S3.
s3_region: The region where the Amazon S3 bucket is located. This parameter is required when the backup medium is AWS S3.addressing_model: The optional parameter for setting the URL format for accessing object storage services (such as OBS, GCS, and COS) through the S3-compatible protocol. It is connected to other parameters using the&symbol. Currently, this parameter supports the following two values:virtual_hosted_style: The default value. It specifies to access object storage in virtual-hosted style.path_style: Indicates to access object storage in path-style.
For example, to configure a user tenant to use OBS as its backup medium and access OBS in virtual-hosted-style mode, you can use the following statements:
ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****&addressing_model=virtual_hosted_style';zone,idc,region: Specifies the source for the backup path, that is, the range of nodes that can access this path and their access priority. These are optional parameters, connected by the&symbol. You can select configurations at three different levels:zone,idc, orregion. Only one level can be selected at a time, or none at all. By default, no level is specified.When specifying the
zone,idc, orregionfor the backup path, the leader node of the Root Service must reside within the specifiedzone,idc, orregion. Otherwise, the backup task will fail to write backup metadata to the target backup path, leading to task execution failure. It is recommended to set the backup path source to include the Primary Zone.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;orALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name;statement to configure the region or IDC information. It is recommended to set the source configuration at the IDC level. This way, the backup task can leverage an IDC with more network bandwidth resources, providing a wider range of available nodes. Additionally, users do not need to worry about changes in zones within the IDCs of the cluster.If the specified
zone,idc, orregiondoes not exist, an error will be returned indicating that the source information does not exist (error code-9133).To specify multiple zones, IDCs, or regions, separate the values with commas (,) and semicolons (;). For example:
- A comma (,) indicates that nodes within the zones, IDCs, or regions on both sides have the same priority when selecting nodes to execute the backup task.
- An English semicolon (;) indicates that a node in the left Zone/IDC/Region has a higher priority than one in the right. That is, a node in the left Zone/IDC/Region is preferentially selected to perform the backup task.
For example, if you set it to
zone=z1,z2;z3, it specifiesz1,z2, andz3as the source zones for backup.z1andz2have the same priority, and their priority is higher than that ofz3.After setting the backup source at the backup path, changes to the cluster's zone, IDC, or region, such as name changes or the deletion of a zone/IDC/region, may prevent backup operations from being executed properly, ultimately causing the backup task to fail.
Examples
System tenant
The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being NFS.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST = 'file:///data/nfs/backup/data' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being NFS. It specifies that zones z1, z2, and z3 can access this backup path. Additionally, when selecting nodes to execute backup tasks, the Root Service prioritizes nodes within zones z1 and z2 with higher priorities.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST = 'file:///data/nfs/backup/data?zone=z1,z2;z3' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being AWS S3. The cleanup mode for backup files is set totagging, and the integrity of backup data is verified using the CRC32 algorithm.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com&access_id=xxx&access_key=xxx&s3_region=xxx&delete_mode=tagging&checksum_type=crc32' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being OBS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being GCS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com&access_id=****&access_key=****' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being COS. The cleanup mode for backup files is set todelete, and it is accessed via the S3 protocol.Note
When using COS as the backup medium, you must first set the cluster-level parameter ob_storage_s3_url_encode_type. For detailed operations, see [Prepare for backup](../../../../../600.manage/600.backup-and-recovery/400.data-backup/100.preparation-before-data-backup.md).
obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com&access_id=***&access_key=***&delete_mode=delete' TENANT = mysql_tenant;The system tenant configures a backup path for the
mysql_tenanttenant, with the backup medium being Azure Blob. The cleanup mode is set todelete, and the verification algorithm is specified asmd5.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='azblob://oceanbase-test-bucket/backup/data?host=http://****.blob.core.windows.net&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5' TENANT = mysql_tenant;
User tenant
Tenant
mysql_tenantconfigures a backup path for itself, with the backup medium being NFS.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST = 'file:///data/nfs/backup/data';Tenant
mysql_tenantconfigures a backup path for itself, with the backup medium being NFS. It specifies that theregion1region can access this backup path.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST = 'file:///data/nfs/backup/data?region=region1';Tenant
mysql_tenantconfigures a backup path for itself, with the backup medium being AWS S3. The cleanup mode for backup files is set totagging, and the integrity of backup data is verified using the CRC32 algorithm.obclient [oceanbase]> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com&access_id=xxx&access_key=xxx&s3_region=xxx&delete_mode=tagging&checksum_type=crc32';The tenant
mysql_tenantis configured with a backup path. The backup medium is OBS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****';Configure a backup path for the
mysql_tenanttenant. The backup medium is GCS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com&access_id=****&access_key=****';For the
mysql_tenanttenant, configure a backup path, set the backup medium to COS, and set the cleanup mode for backup files todelete. Access is provided through the S3 protocol.Notice
When using COS as the backup medium, you must first set the cluster-level parameter ob_storage_s3_url_encode_type. For detailed operations, see Prepare for backup.
obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com&access_id=***&access_key=***&delete_mode=delete';The user tenant
mysql_tenantis configured with a backup path for this tenant, the backup medium is set to Azure Blob, the cleanup mode is configured asdelete, and the verification algorithm is specified asmd5.obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='azblob://oceanbase-test-bucket/backup/data?host=http://****.blob.core.windows.net&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5';