Prepare for backup

Before you back up data, you need to perform some preparatory tasks, including configuring the backup destination and backup keys.

Configure a backup destination

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

Considerations

When you configure a backup destination, you must configure a separate empty directory for each tenant as the backup path. Different tenants cannot use the same backup path.

Procedure

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

   Note

   In MySQL-compatible mode, the administrator user is root. In Oracle-compatible mode, the administrator user is SYS.

2. Configure the backup destination.

   Notice

   If you upgrade OceanBase Database V4.0.x to V4.1.0, you must change the backup path. If you upgrade OceanBase Database V4.1.x to V4.2.0, you do not need to change the backup path.

   • The sys tenant configures the backup destination for a specified tenant

     ALTER SYSTEM SET DATA_BACKUP_DEST= 'data_backup_path' TENANT = mysql_tenant;
     

   • The user tenant configures the backup destination for the current tenant

     ALTER SYSTEM SET DATA_BACKUP_DEST= 'data_backup_path';
     

   Related information about the statements is as follows:

   • This statement configures the backup path and source-side configuration. OceanBase Database supports NFS, Alibaba Cloud OSS, Azure Blob (supported starting from V4.2.5 BP6 in V4.2.5), AWS S3, and S3-compatible object storage such as Huawei OBS, Google GCS, and Tencent Cloud COS as backup media. Some backup media may need to meet basic requirements before use. For the specific requirements of each backup medium, see Backup media requirements in Overview of physical backup and restore.

   • The source side of a backup path specifies the range of nodes that can access the backup path. For more information about source-side configuration of backup paths, see SET DATA_BACKUP_DEST.

     After the source side of a backup path is configured, you can modify it.

   Detailed configuration is as follows.

   Alibaba Cloud OSS

   NFS

   AWS S3

   S3-compatible object storage

   Azure Blob

   When you use OSS as the backup medium, you can set the backup path and use the delete_mode parameter to configure the cleanup mode of backup files. The delete_mode parameter supports delete mode and tagging mode. If you do not set the delete_mode parameter, delete mode is used by default.

   OSS also supports the checksum_type parameter to specify the algorithm used to verify the integrity of backup data. Valid values are md5 and no_checksum. If you do not explicitly set the checksum_type parameter, the default value is md5.

   In OceanBase Database V4.2.5, starting from V4.2.5 BP7, you can use an Alibaba Cloud OSS bucket with a compliance retention policy configured as the backup path. When you configure a backup path, you can use the enable_worm parameter to specify whether OceanBase Database performs write and delete operations on the path according to the bucket retention policy (WORM policy). Valid values are true and false. If you do not explicitly set the enable_worm parameter, the default value is false. When you set enable_worm=true, you must also explicitly set checksum_type=md5. After this parameter is set, it cannot be changed.

   Notice

   OceanBase Database does not configure a compliance retention policy for you. Before you set the backup path, make sure that the OSS bucket retention policy (WORM policy) has been properly configured and locked.

   For more information about the parameters, see SET DATA_BACKUP_DEST.

   Notice

   When you use object storage as the backup medium, the parameters in the object storage path are separated by the & symbol. Make sure that the parameter values contain only uppercase and lowercase English letters, digits, /-_$+=, and wildcards. If you enter other characters, the setting may fail.

   Examples:

   • When you use OSS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant, configures the cleanup mode of backup files, and specifies the verification algorithm as md5.

     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, set the checksum_type parameter to no_checksum. 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;
     

   • When you use OSS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant, configures the cleanup mode of backup files, specifies WORM-compliant object write and delete operations, and sets the verification algorithm to md5.

     Notice

     • OceanBase Database does not configure a compliance retention policy for you. Before you set the backup path, make sure that the OSS bucket retention policy (WORM policy) has been properly configured and locked.
     • When you use a bucket with a WORM policy as the backup path, we recommend that you 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=tagging&checksum_type=md5&enable_worm=true' TENANT = mysql_tenant;
     

   • When you use OSS as the backup medium, the user tenant sets the backup path for the current tenant, configures the cleanup mode of backup files, and specifies the verification algorithm as md5.

     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 examples, oss:// indicates that OSS is used as the backup medium. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character separates the path from the parameters, which are separated by &. host specifies the host address of the bucket. access_id and access_key specify the access keys for OSS. delete_mode=delete indicates that the cleanup mode is delete, and the MD5 algorithm is used to verify the integrity of backup data. enable_worm=true indicates that write and delete operations are performed according to WORM rules. OceanBase Database does not configure a compliance retention policy for you. Before you set the backup path, make sure that the OSS bucket retention policy (WORM policy) has been properly configured and locked.

   Notice

   When you use NFS as the backup medium, note the following:

   • The value of data_backup_dest cannot be set to a string that contains a question mark (?).
   • The value of data_backup_dest must be an absolute path, and the OBServer server must have write permission on data_backup_dest.
   • Make sure that all OBServer servers have mounted the NFS of the same server. To ensure smooth backup, use the recommended parameters in this topic to mount NFS. For more information, see Deploy NFS clients.

   Examples:

   • When you use NFS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant.

     obclient> ALTER SYSTEM SET DATA_BACKUP_DEST= 'file:///data/nfs/backup/data' TENANT = mysql_tenant;
     

   • When you use NFS as the backup medium, the user tenant sets the backup path for the current tenant.

     obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='file:///data/nfs/backup/data';
     

   In the example, file:// indicates that NFS is used as the backup medium, and the backup path is file:///data/nfs/backup/data.

   Like OSS, AWS S3 supports the delete_mode parameter to configure the cleanup mode of backup files. The configuration method is the same as that for OSS. AWS S3 also supports the checksum_type parameter to specify the algorithm used to verify the integrity of backup data. Valid values are md5 and crc32. If you do not explicitly set 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 medium, the parameters in the object storage path are separated by the & symbol. Make sure that the parameter values contain only uppercase and lowercase English letters, digits, /-_$+=, and wildcards. If you enter other characters, the setting may fail.

   Examples for using AWS S3 as the backup medium:

   • When you use S3 as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant, sets the cleanup mode to delete, and specifies the verification algorithm as 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;
     

   • When you use AWS S3 as the backup medium, the user tenant sets the backup path for the current tenant, sets the cleanup mode to delete, and specifies the verification algorithm as 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 examples, s3:// indicates that S3 is used as the backup medium. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character separates the path from other parameters, which are separated by &. host specifies the domain name of the Amazon S3 service. access_id and access_key specify the access keys for AWS. s3_region is required when S3 is used as the backup medium and specifies the region of the S3 bucket. The cleanup mode is delete, and the CRC32 algorithm is used to verify the integrity of backup data.

   For more information about the AWS S3 path format, see Appendix: AWS S3 path format description.

   Because most object storage services are compatible with the S3 protocol, any S3-compatible object storage that meets OceanBase Database requirements (the object storage must implement the S3 API behaviors used by OceanBase system calls) can be used as a backup medium and accessed through the S3 protocol. For example, OBS, GCS, and COS are all accessed through the S3 protocol.

   For OBS, GCS, and COS object storage accessed through the S3 protocol, you can use the checksum_type parameter to specify the algorithm used to verify the integrity of backup data. Only md5 is supported. If you do not explicitly set the checksum_type parameter, the default value is md5. For more information about the checksum_type parameter, see SET DATA_BACKUP_DEST.

   Notice

   • When you use object storage as the backup medium, the parameters in the object storage path are separated by the & symbol. Make sure that the parameter values contain only uppercase and lowercase English letters, digits, /-_$+=, and wildcards. If you enter other characters, the setting may fail.
   • For some S3-compatible object storage services, the default URL encoding method of the AWS S3 SDK may not be supported. If errors such as 9129 or 9026 occur when you access object storage through the s3:// protocol, set the cluster-level parameter ob_storage_s3_url_encode_type to make the URL encoding method used by AWS S3 compatible with the RFC 3986 standard. For detailed steps, see Steps and examples for using COS as the backup medium below.

   Examples for using OBS as the backup medium:

   • When you use OBS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_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;
     

   • When you use OBS as the backup medium, the user tenant sets the backup path 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 examples, s3:// indicates that S3-compatible object storage is used as the backup medium. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character separates the path from the parameters, which are separated by &. host specifies the domain name of the OBS service. access_id and access_key specify the access keys for OBS.

   Examples for using GCS as the backup medium:

   • When you use GCS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_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;
     

   • When you use GCS as the backup medium, the user tenant sets the backup path 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 examples, s3:// indicates that S3-compatible object storage is used as the backup medium. The bucket name is oceanbase-test-bucket, and the path in the bucket is /backup/data. The ? character separates the path from the parameters, which are separated by &. host specifies the domain name of the GCS service. access_id and access_key specify the access keys for GCS.

   Steps and examples for using COS as the backup medium:

   1. Check the value of the ob_storage_s3_url_encode_type parameter at the cluster level.

      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. Set the backup path and configure the cleanup mode of backup files with the delete_mode parameter.

      When you use COS as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant and sets the cleanup mode to delete. Example:

      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;
      

      When you use COS as the backup medium, the user tenant sets the backup path for the current tenant and sets the cleanup mode to delete. Example:

      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 example, s3:// is used to access the backup path through the S3 protocol. The bucket name is oceanbase-test, and the path in the bucket is /backup/archive. The ? character separates the path from the parameters, which are separated by &. host specifies the host address of COS, which is the endpoint without the bucket name. access_id and access_key specify the access keys for COS.

   In OceanBase Database V4.2.5, Azure Blob is supported as a backup medium starting from V4.2.5 BP6.

   Like OSS, Azure Blob supports the delete_mode and checksum_type parameters. The delete_mode parameter configures the cleanup mode of backup files. If you do not explicitly set the delete_mode parameter, the default value is delete. The checksum_type parameter specifies the algorithm used to verify the integrity of backup files. Valid values are md5 and no_checksum. If you do not explicitly set the checksum_type parameter, the default value is md5.

   For more information about the parameters, see SET DATA_BACKUP_DEST.

   Examples:

   Notice

   • When you use object storage as the backup medium, the parameters in the object storage path are separated by the & symbol. Make sure that the parameter values contain only uppercase and lowercase English letters, digits, /-_$+=, and wildcards. If you enter other characters, the setting may fail.
   • When you use Azure Blob as the backup medium, the prefix of the host parameter must be http:// or https://. Because Azure Blob enables secure transfer by default, it is accessed through https:// by default. To access it through http://, you must disable the secure transfer option for Azure Blob. For more information, see Azure Blob documentation.

   • When you use Azure Blob as the backup medium, the sys tenant sets the backup path for the specified tenant mysql_tenant, sets the cleanup mode to delete, and specifies the verification algorithm as md5.

     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;
     

   • When you use Azure Blob as the backup medium, the user tenant sets the backup path for the current tenant, sets the cleanup mode to delete, and specifies the verification algorithm as md5.

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

   In the example, azblob:// indicates that Azure Blob is used as the backup medium. The bucket name is oceanbase-test-bucket, and the path in the bucket is backup/data. The ? character separates the path from the parameters, which are separated by &. host specifies the host address of the bucket, which can be obtained from the container properties or the storage account connection string. access_id specifies the storage account name. access_key specifies the access key for Azure Blob. The cleanup mode is delete, and the MD5 algorithm is used to verify the integrity of backup data.

3. After the configuration is successful, you can view the detailed configuration information in the views.

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

   For information about data backup parameters and how to view them, see View data backup parameters.

Considerations and notes after configuration

After the data_backup_dest parameter is set successfully, the system creates a format file in the directory of the configured destination by default. This file is used to verify the validity of the backup destination and ensure the integrity of data in the destination. Therefore, when you configure the data_backup_dest parameter for data backup, note the following:

• If the format file does not exist, the directory of the configured destination must be empty for the parameter to be set successfully. Otherwise, the system returns error -9080, indicating that the format file does not exist.

• If the format file exists, its content must pass verification for the parameter to be set successfully. Otherwise, the system returns error -9081, indicating that the format file does not match. The verification of the format file content mainly checks whether information such as the cluster, tenant, and backup destination media type matches the cluster, tenant, and backup medium type of the current operation.

• If the format file does not exist or fails verification during a backup task, the task fails.

Backup keys

Before you back up data, you must also consider the encryption settings of the source tenant. If the source tenant is configured with transparent encryption, you must also back up the keys of the source tenant.

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

2. Back up keys.

   • The sys tenant backs up keys for a specified tenant

     ALTER SYSTEM BACKUP KEY TENANT = tenant_name TO 'backup_key_path' ENCRYPTED BY 'password';
     

   • The user tenant backs up keys for the current tenant

     The statement is as follows:

     ALTER SYSTEM BACKUP KEY TO 'backup_key_path' ENCRYPTED BY 'password';
     

   In the statement:

   • backup_key_path: specifies the path where keys are to be backed up. You can customize this path. It must be different from the path used for data backup or log archiving.

   • password: specifies the encryption password for the key backup path.

   The following example shows how the sys tenant backs up the keys of tenant mysql_tenant to the file:///data_backup_dest/key path:

   obclient> ALTER SYSTEM BACKUP KEY TENANT = mysql_tenant TO 'file:///data_backup_dest/key' ENCRYPTED BY '******';
   

3. After the configuration is successful, you can view the key backup path in the views.

   • The sys tenant views the key backup path in the CDB_OB_BACKUP_STORAGE_INFO view.

     obclient> SELECT * FROM oceanbase.CDB_OB_BACKUP_STORAGE_INFO;
     

   • The user tenant views the key backup path in the DBA_OB_BACKUP_STORAGE_INFO view.

     MySQL-compatible mode

     Oracle-compatible mode

     The statement is as follows:

     obclient> SELECT * FROM oceanbase.DBA_OB_BACKUP_STORAGE_INFO;
     

     The statement is as follows:

     obclient> SELECT * FROM SYS.DBA_OB_BACKUP_STORAGE_INFO;
     

     For more information about the fields in the CDB_OB_BACKUP_STORAGE_INFO and DBA_OB_BACKUP_STORAGE_INFO views, see CDB_OB_BACKUP_STORAGE_INFO and DBA_OB_BACKUP_STORAGE_INFO.