Prepare for backup|V4.3.5| docs|Distributed Database

Prepare for backup

Last Updated：2025-11-13 06:13:17 Updated

Before you back up data, you must perform some preparatory operations, including configuring the backup destination and a backup key.

Configure the backup destination

When you configure the backup destination, note that the sys tenant, which is used for cluster management and does not contain user data, does not support backup and restore. Therefore, you do not need to specify the DATA_BACKUP_DEST parameter for the sys tenant.

Considerations

When you configure the backup destination, make sure that the backup path is a unique empty directory for each tenant and that the backup path of one tenant is not the same as that of another tenant.

Procedure

Log in to the database as the sys tenant or a user tenant. The tenant administrator of the sys tenant or a user tenant logs in to the database.

Note

In MySQL-compatible mode, the administrator is the root user, and in Oracle-compatible mode, the administrator is the SYS user.
Configure the backup destination.
- For the system tenant, configure the backup destination for the specified tenant.
```
ALTER SYSTEM SET DATA_BACKUP_DEST= 'data_backup_path' TENANT = mysql_tenant;
```
- For a user tenant, configure the backup destination for the current tenant.
  
  The statement is as follows:
```
ALTER SYSTEM SET DATA_BACKUP_DEST= 'data_backup_path';
```
Notice

For an upgrade scenario from OceanBase Database V4.0.x to V4.1.0, you must change the backup path after the version upgrade. For an upgrade scenario from OceanBase Database V4.1.x to V4.2.0, you do not need to change the backup path after the version upgrade.

Currently, OceanBase Database supports the following backup media: NFS, Alibaba Cloud OSS, Azure Blob Storage (For OceanBase Database V4.3.5, supported starting from V4.3.5 BP3), AWS S3, and S3-compatible object storage such as Huawei OBS, Google GCS, and Tencent Cloud COS. Some backup media may need to meet certain basic requirements before they can be used. For more information about the requirements for each backup media, see the Backup media requirements section in Overview of physical backup and restore.

The following table describes the parameters in detail.
Alibaba Cloud OSS

NFS

AWS S3

Object storage services compatible with the S3 protocol
When OSS is used as the backup media, you can also configure the backup file cleanup mode by using the delete_mode parameter. The delete_mode parameter supports the delete mode and the tagging mode. If you do not specify the delete_mode parameter, the delete mode is used by default.

In addition, OSS supports specifying the checksum algorithm by using the checksum_type parameter to verify the integrity of backup data. The supported values are md5 and no_checksum. If you do not specify the checksum_type parameter, the default value is md5.

In V4.3.5, starting from V4.3.5 BP2, OceanBase Database supports using Alibaba Cloud OSS Buckets with configured compliance retention policies as backup paths. When configuring the backup path, you can use the enable_worm parameter to specify whether OceanBase Database should perform write and delete operations on the path according to the Bucket's retention policy (WORM policy). The supported values for this parameter are true and false. If the enable_worm parameter is not explicitly configured, it defaults to false. When setting enable_worm=true, it is required to explicitly configure checksum_type=md5 at the same time. Once this parameter is set, it cannot be changed.

Notice

OceanBase Database will not replace your compliance retention policy settings. Please ensure that the OSS Bucket has been correctly configured with the retention policy (WORM policy) and locked before setting the backup path.

For detailed descriptions of each parameter, refer to SET DATA_BACKUP_DEST.

Notice

When using object storage as a backup medium, parameters in the object storage path are separated by the & symbol. Please ensure that your parameter values contain only English letters (case-sensitive), numbers, /-_$+=, and wildcards. If you enter any other characters, the configuration may fail.

Here is an example:
- To set an OSS bucket as the backup destination and configure the backup file cleanup mode for the mysql_tenant tenant as the sys tenant, execute the following statement:
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5' TENANT = mysql_tenant;
  
  If you do not want to verify the integrity of backup data, you can set the checksum_type parameter to no_checksum. Here is an example:
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com&access_id=****&access_key=****&delete_mode=delete&checksum_type=no_checksum' TENANT = mysql_tenant;
- To use OSS as the backup medium, the system tenant sets the backup path for the specified tenant mysql_tenant, configures the cleanup mode for backup files, specifies writing and deleting objects in a WORM-supported manner, and sets the checksum algorithm to md5.
  
  Notice
  
  OceanBase Database will not override the compliance retention policy you set. Before configuring the backup path, please make sure that the OSS bucket has been properly set up with a retention policy (WORM policy) and is locked.
  
  When using a bucket with a WORM policy as the backup path, it is recommended to use the tagging cleanup mode.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5&enable_worm=true' TENANT = mysql_tenant;
- To use an OSS bucket as the backup medium, configure the backup path, set the cleanup mode for backup files, and specify the checksum algorithm as md5 as a user tenant.
obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5';
In the example, oss:// indicates that OSS is used as the backup medium type. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? is used to separate the path from the parameters, and the parameters are separated by &. The host parameter is used to set the bucket's host address, while access_id and access_key are used to set the access credentials for OSS. The cleanup mode is set to delete, and the MD5 algorithm is used to verify the integrity of the archived files. The parameter enable_worm=true specifies that the system will perform write and delete operations in compliance with the WORM policy. Note that OceanBase Database will not replace your compliance retention policy settings. Please ensure that the OSS Bucket has been correctly configured with the retention policy (WORM policy) and locked before setting the backup path.
Notice

When you use NFS as the backup media, note the following items:

The value of the data_backup_dest parameter cannot contain the question mark (?).

The value of the data_backup_dest parameter must be an absolute path, and the OBServer node must have the write permission on data_backup_dest.

All OBServer nodes must mount the same NFS server. To ensure smooth backup, we recommend that you use the parameters suggested in this topic to mount NFS. For more information, see Deploy an NFS client.
- Assume that you want to use NFS as the backup media. The system tenant configures the backup destination for the mysql_tenant tenant.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST= 'file:///data/nfs/backup/data' TENANT = mysql_tenant;
- Assume that you want to use NFS as the backup media. The user tenant configures the backup destination for the current tenant.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='file:///data/nfs/backup/data';
In the preceding examples, file:// indicates that NFS is used as the backup media, and the backup path is file:///data/nfs/backup/data.
Like OSS, an Amazon S3 bucket supports specifying the backup file cleanup mode by using the delete_mode parameter, and the configuration method is the same as that for OSS. In addition, an Amazon S3 bucket supports specifying the checksum algorithm by using the checksum_type parameter to verify the integrity of backup data. The supported values are md5 and crc32. If you do not specify the checksum_type parameter, the default value is md5.

For more information about the delete_mode and checksum_type parameters, see SET DATA_BACKUP_DEST.

Notice

When you use object storage as the backup media, separate the parameters in the object storage path with the & character. Make sure that the value of each parameter contains only uppercase and lowercase letters, numbers, and the characters in the /-_$+= set and the wildcard character. If you enter characters other than the preceding ones, the setting may fail.

Here is an example of configuring an Amazon S3 bucket as the backup media:
- Assume that you want to use an Amazon S3 bucket as the backup media. The system tenant configures the backup destination for the mysql_tenant tenant, specifies the backup file cleanup mode as delete, and sets the checksum algorithm to crc32.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com&access_id=****&access_key=****&s3_region=****&delete_mode=delete&checksum_type=crc32' TENANT = mysql_tenant;
- Assume that you want to use an Amazon S3 bucket as the backup media. The user tenant configures the backup destination for the current tenant, specifies the backup file cleanup mode as delete, and sets the checksum algorithm to crc32.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com&access_id=****&access_key=****&s3_region=****&delete_mode=delete&checksum_type=crc32';
In the example, s3:// indicates that S3 is used as the backup medium type. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? is used to separate the path from the parameters, and the parameters are separated by &. The host parameter is used to set the domain name of the Amazon S3 service, while access_id and access_key are used to configure the access credentials for AWS services. The s3_region parameter is mandatory when using S3 as the backup medium, specifying the region where the S3 bucket is located. The cleanup mode is set to delete, and the CRC32 algorithm is used to verify the integrity of the backup data.

For more information about the AWS S3 path format, see Appendix: AWS S3 backup destination format.
Most object storage services are compatible with the S3 protocol. Therefore, object storage services that are compatible with the S3 protocol and meet the requirements of OceanBase Database can be used as the backup media for OceanBase Database. You can access these object storage services in the same way as you access S3. For example, OBS, GCS, and COS can be accessed through the S3 protocol.

For object storage services that are accessed through the S3 protocol, such as OBS, GCS, and COS, you can specify the checksum algorithm by using the checksum_type parameter to verify the integrity of backup data. The supported value is md5. If you do not specify the checksum_type parameter, the default value is md5. For more information about the checksum_type parameter, see SET DATA_BACKUP_DEST.
Notice

When using object storage as the backup medium, the parameters for the object storage path are separated by the & symbol. Please ensure that the values you enter contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcards. If you enter any other characters, the configuration may fail.

For some object storage services compatible with the S3 protocol, the default URL encoding method of the AWS S3 SDK may not be supported. When accessing via the s3:// protocol, if you encounter object storage-related error codes such as 9129 or 9026, it is recommended to set the cluster-level parameter ob_storage_s3_url_encode_type to specify the URL encoding method used by AWS S3 requests to be compatible with the Rfc3986 standard. For detailed configuration steps, please refer to Operation steps and examples for using COS as the backup medium below.
Here is an example of using OBS as the backup media:
- Assume that you want to use OBS as the backup media. The system tenant configures the backup destination for the mysql_tenant tenant.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****' TENANT = mysql_tenant;
- Assume that you want to use OBS as the backup media. The user tenant configures the backup destination for the current tenant.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****';
In the preceding examples, s3:// indicates that the object storage is accessed through the S3 protocol. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character is used to separate the path and parameters, and the & character is used to separate the parameters. The host parameter specifies the endpoint of OBS, which is the domain name of the OBS service without the bucket name. The access_id and access_key parameters specify the access key of OBS.

Here is an example of using GCS as the backup media:
- Assume that you want to use GCS as the backup media. The system tenant configures the backup destination for the mysql_tenant tenant.
  
  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;
- Assume that you want to use GCS as the backup media. The user tenant configures the backup destination for the current tenant.
  
  obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com&access_id=****&access_key=****';
In the preceding examples, s3:// indicates that the object storage is accessed through the S3 protocol. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character is used to separate the path and parameters, and the & character is used to separate the parameters. The host parameter specifies the endpoint of GCS, which is the domain name of the GCS service without the bucket name. The access_id and access_key parameters specify the access key of GCS.

Here is an example of using COS as the backup media:
1. View the value of the cluster-level parameter ob_storage_s3_url_encode_type.
  
  obclient> SHOW PARAMETERS LIKE '%ob_storage_s3_url_encode_type%';
  
  The query result is as follows:
  
  +-------+----------+----------------+----------+-------------------------------+-----------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+ | zone | svr_type | svr_ip | svr_port | name | data_type | value | info | section | scope | source | edit_level | +-------+----------+----------------+----------+-------------------------------+-----------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+ | zone1 | observer | 172.xx.xxx.xxx | 2882 | ob_storage_s3_url_encode_type | NULL | default | Determines the URL encoding method for S3 requests."default": Uses the S3 standard URL encoding method."compliantRfc3986Encoding": Uses URL encoding that adheres to the RFC 3986 standard. | OBSERVER | CLUSTER | DEFAULT | DYNAMIC_EFFECTIVE | +-------+----------+----------------+----------+-------------------------------+-----------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+---------+---------+-------------------+ 1 row in set
2. If the value is default, change it to compliantRfc3986Encoding.
  
  obclient>ALTER SYSTEM SET ob_storage_s3_url_encode_type='compliantRfc3986Encoding';
  
  For more information about this parameter, see ob_storage_s3_url_encode_type.
3. Configure the backup destination and specify the backup file cleanup mode by using the delete_mode parameter.
  
  The system tenant can configure the backup destination for the mysql_tenant tenant and specify the delete mode as follows when COS is used as the backup media:
  
  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 user tenant can configure the backup destination for the current tenant and specify the delete mode as follows when COS is used as the backup media:
  
  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';
  
  In the preceding examples, s3:// indicates that the object storage is accessed through the S3 protocol. The bucket name is oceanbase-test, and the path in the bucket is /backup/archive. The ? character is used to separate the path and parameters, and the & character is used to separate the parameters. The host parameter specifies the endpoint of COS, which is the endpoint without the bucket name. The access_id and access_key parameters specify the access key of COS. The delete_mode parameter is set to delete.
tab Azure Blob Storage

In V4.3.5, Azure Blob Storage is supported as the backup media from V4.3.5 BP3.

Like Alibaba Cloud OSS, Azure Blob Storage supports the delete_mode and checksum_type parameters. The delete_mode parameter specifies the cleanup mode for the archive files. If you do not explicitly configure the delete_mode parameter, the delete mode is used by default. The checksum_type parameter specifies the verification algorithm for verifying the integrity of the archive files. The supported values are md5 and no_checksum. If you do not explicitly configure the checksum_type parameter, the default value is md5.

For more information about the parameters, see SET LOG_ARCHIVE_DEST.

Here are some examples:
Notice

When you use an object storage service as the backup media, the parameters of the object storage path are separated by &. Make sure that the parameter values contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If you enter other characters, the configuration may fail.

When you use Azure Blob Storage as the backup media, the prefix of the host parameter must be specified as http:// or https://. By default, Azure Blob Storage enables secure transfer. Therefore, it is accessed by using https://. If you want to access it by using http://, you must disable secure transfer for Azure Blob Storage. For more information, see Azure Blob Storage documentation on the Microsoft website.
- When you use Azure Blob Storage as the backup media, set the archive path for the mysql_tenant tenant in the system tenant. The cleanup mode is delete, and the verification algorithm is md5.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=azblob://oceanbase-test-bucket/backup/archive?host=http://****.blob.core.windows.net&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5' TENANT = mysql_tenant;
- When you use Azure Blob Storage as the backup media, set the archive path for the current tenant in the user tenant. The cleanup mode is delete, and the verification algorithm is md5.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=azblob://oceanbase-test-bucket/backup/archive?host=http://****.blob.core.windows.net&access_id=****&access_key=****&delete_mode=delete&checksum_type=md5';
In the preceding examples, azblob:// indicates that Azure Blob Storage is used as the backup media. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/archive. The path and parameters are separated by ?, and the parameters are separated by &. host specifies the host address of the bucket, which can be obtained by concatenating the container attribute or connection string of the storage account. access_id specifies the name of the storage account. access_key specifies the access key of Azure Blob Storage. The cleanup mode is delete, and the integrity of the archive files is verified by using the MD5 algorithm.

:::
After the configuration is completed, you can query the view for more information.

The sys tenant can query the CDB_OB_BACKUP_PARAMETER view, and a user tenant can query the DBA_OB_BACKUP_PARAMETER view.

For more information about parameters related to data backup and how to query them, see Query parameters related to data backup.

Considerations and descriptions after configuration

After the data_backup_dest parameter is successfully configured, the system creates a format file in the directory where the configured destination is located by default. The format file is used to verify the validity of the backup destination and ensure the integrity of data in the destination. Therefore, note the following items when you configure the destination for data backup by using the data_backup_dest parameter:
- If the format file does not exist, the configuration fails if the destination directory is not empty. In this case, an error -9080 is returned, indicating that the format file does not exist.
- If the format file exists, the configuration fails unless the format file passes the verification. In this case, an error -9081 is returned, indicating that the format file does not match. The verification mainly checks whether the cluster, tenant, and type of the backup destination match those of the current cluster, tenant, and backup destination type. The verification is also used to check whether the specified directory is empty.
- If the format file does not exist or the format file fails the verification when a backup task is executed, the task fails.
After the backup destination is set, if you change the object storage keys for security reasons or other reasons, you must update the access_id and access_key values of the configured backup path. For more information, see Change access_id and access_key of the backup path or log archive path.

Back up keys

Before you back up data, you also need to consider the encryption status of the source tenant. If the source tenant uses transparent encryption, you also need to back up the keys of the source tenant.

Notice

After you back up the keys, if the encryption information of the source tenant triggers key rotation before you restore the data, you need to back up the keys of the source tenant again.

Log in to the database as the tenant administrator of the sys tenant or a user tenant.
Backup the keys.
- For the sys tenant, use the following statement to back up keys for a specified tenant:
```
ALTER SYSTEM BACKUP KEY TENANT = tenant_name TO 'backup_key_path' ENCRYPTED BY 'password';
```
- For a user tenant, use the following statement to back up keys for the tenant:
  
  The statement is as follows:
```
ALTER SYSTEM BACKUP KEY TO 'backup_key_path' ENCRYPTED BY 'password';
```
In the statement:
- backup_key_path: the path for backing up the keys. You must specify this path. It cannot be the same as the path for backing up data or archiving logs.
- password: the encryption password of the keys backup path.
Here is an example of backing up keys from the mysql_tenant tenant to the file:///data_backup_dest/key path in the sys tenant:
```
obclient [(none)]> ALTER SYSTEM BACKUP KEY TENANT = mysql_tenant TO 'file:///data_backup_dest/key' ENCRYPTED BY '******';
```
After you configure keys backup, you can query the path for keys backup through views.
- For the sys tenant, you can execute the following statement to query the path for keys backup in the CDB_OB_BACKUP_STORAGE_INFO view:
```
SELECT * FROM oceanbase.CDB_OB_BACKUP_STORAGE_INFO;
```
- For a user tenant, you can execute the following statement to query the path for keys backup in the DBA_OB_BACKUP_STORAGE_INFO view:
  MySQL-compatible mode
  
  Oracle-compatible mode
  The statement is as follows:
  
  SELECT * FROM oceanbase.DBA_OB_BACKUP_STORAGE_INFO;
  The statement is as follows:
  
  SELECT * FROM SYS.DBA_OB_BACKUP_STORAGE_INFO;
  For detailed descriptions of the fields in the views CDB_OB_BACKUP_STORAGE_INFO and DBA_OB_BACKUP_STORAGE_INFO, see CDB_OB_BACKUP_STORAGE_INFO and DBA_OB_BACKUP_STORAGE_INFO.

Prepare for backup

Configure the backup destination

Considerations

Procedure

Note

Notice

Notice

Notice

Notice

Notice

Notice

Notice

Notice

Considerations and descriptions after configuration

Back up keys

Notice