Prepare for the backup

Before you back up data, you must perform some preparatory tasks, such as configuring the destination of the backup and the backup key.

Configure the backup destination

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

Considerations

Procedure

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

   Note

   The administrator in MySQL mode is the root user, and that in Oracle mode is the SYS user.

2. Configure the destination for backup.

   • Configure the destination for the specified tenant in the sys tenant

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

   • Configure the destination for the current tenant in a user tenant

     The statement is as follows:

     ALTER SYSTEM SET DATA_BACKUP_DEST= 'data_backup_path';
     

   Notice

   After upgrading from OceanBase Database V4.0.x to V4.1.0, you need to change the backup path. After upgrading from OceanBase Database V4.1.x to V4.2.0, you do not need to change the backup path.

   Currently, OceanBase Database supports NFS, Alibaba Cloud OSS, Tencent Cloud COS, and Amazon S3 as the destination for backup. Some backup media may have minimum requirements. For more information, see the Requirements section in Overview of physical backup and restore.

   For more information about how to configure the destination, see the following sections.

   Alibaba Cloud OSS

   NFS

   Tencent Cloud COS

   AWS S3

   When you use OSS as the destination for backup, you can also use the delete_mode parameter to specify the cleanup mode for backup files. The delete_mode parameter supports the delete mode and the tagging mode. If you do not specify the delete_mode parameter, the delete mode will be used by default. For more information about the delete_mode parameter, see View data backup parameters.

   Notice

   When you use an object storage service as the backup medium, separate the parameters in the backup path with &. Make sure that the parameter values contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameter values contain other characters, the setting may fail.

   Here is an example:

   • When you use OSS as the backup medium, the sys tenant configures the destination for backup and specifies the cleanup mode for backup files for the mysql_tenant 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' TENANT = mysql_tenant;
     

   • When you use OSS as the backup medium, the user tenant configures the destination for backup and specifies the cleanup mode for backup files for the current 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';
     

   In the example, oss:// indicates the type of the backup medium (OSS), the bucket name (oceanbase-test-bucket), and the path within the bucket (/backup/data). The parameters in the path are separated with ?. The host parameter sets the host address of the bucket, the access_id and access_key parameters set the access key of OSS, and the delete_mode parameter specifies the delete mode.

   After you set the delete mode or the tagging mode, for more information about how to automatically clear expired backup data, see Automatically clear expired backup data.

   Notice

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

   • The value of the data_backup_dest parameter must not contain a question mark (?).
   • The value of the data_backup_dest parameter must be an absolute path. Additionally, the OBServer node must have write permissions for the path specified in the data_backup_dest parameter.
   • Make sure that all OBServer nodes have mounted the same NFS server. Additionally, to ensure smooth backup, use the recommended parameters to mount NFS. For more information, see Deploy an NFS client.

   • When you use NFS as the backup medium, the sys tenant configures the destination for backup for the mysql_tenant 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 configures the destination for backup for the current tenant.

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

   In the example, file:// indicates the type of the backup medium (NFS), and the backup path is file:///data/nfs/backup/data.

   Notice

   When you use COS as the destination for backup, note the following points:

   • Make sure that the List Cache of the bucket is disabled. Otherwise, errors may occur that compromise the consistency of backup data. To disable the List Cache, contact the COS technical support team.
   • A bucket with the Multi-AZ feature enabled does not support the APPEND Object interface. You must disable the Multi-AZ feature. Otherwise, an error will occur during backup.

   COS supports the delete_mode parameter to specify the cleanup mode for backup files. The configuration method is the same as that for OSS.

   Notice

   When you use an object storage service as the backup medium, separate the parameters in the backup path with &. Make sure that the parameter values contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameter values contain other characters, the setting may fail.

   • When you use COS as the backup medium, the sys tenant configures the destination for backup and specifies the cleanup mode for backup files for the mysql_tenant tenant.

     obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='cos://oceanbase-test-appid/backup/data?host=cos.ap-****.myqcloud.com&access_id=***&access_key=***&appid=***' TENANT = mysql_tenant;
     

   • When you use COS as the backup medium, the user tenant configures the destination for backup and specifies the cleanup mode for backup files for the current tenant.

     obclient> ALTER SYSTEM SET DATA_BACKUP_DEST='cos://oceanbase-test-appid/backup/data?host=cos.ap-****.myqcloud.com&access_id=***&access_key=***&appid=***';
     

   In the example, cos:// indicates the type of the backup medium (COS), the bucket name (oceanbase-test-appid), and the path within the bucket (/backup/data). The parameters in the path are separated with ?. The host parameter sets the host address of the bucket, which is the endpoint (without the bucket name) of the COS service. The access_id and access_key parameters set the access key of COS. The appid parameter, which is an optional parameter used for identifying a Tencent cloud account, is also provided.

   AWS S3 supports the delete_mode parameter to specify the cleanup mode for backup files. The configuration method is the same as that for OSS and COS.

   Notice

   When you use an object storage service as the backup medium, separate the parameters in the backup path with &. Make sure that the parameter values contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameter values contain other characters, the setting may fail.

   • When you use S3 as the backup medium, the sys tenant configures the destination for backup and specifies the cleanup mode for backup files for the mysql_tenant tenant.

     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' TENANT = mysql_tenant;
     

   • When you use S3 as the backup medium, the user tenant configures the destination for backup and specifies the cleanup mode for backup files for the current tenant.

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

   In the example, s3:// indicates the type of the backup medium (S3), the bucket name (oceanbase-test-bucket), and the path within the bucket (/backup/data). The parameters in the path are separated with ?. The host parameter sets the domain name of the Amazon S3 service. The access_id and access_key parameters set the access key of AWS. The s3_region parameter, which is an optional parameter used to specify the region where the S3 bucket is located, is also provided. The delete_mode parameter specifies the delete mode.

3. After the configuration is completed, the sys tenant can query the CDB_OB_BACKUP_PARAMETER view for the backup path and other information of each tenant in the current cluster. For more information, see View data backup parameters.

Considerations and notes

After the data_backup_dest parameter is configured, the system will create a format file in the specified directory as a verification file to check the validity of the backup destination and the integrity of the data in it. Therefore, when you configure the data_backup_dest parameter, keep the following considerations and notes in mind:

• If the format file does not exist, the specified destination directory must be empty. Otherwise, an error -9080 will occur, indicating that the format file does not exist.

• If the format file already exists, its content must pass the verification. Otherwise, an error -9081 will occur, indicating that the format file is mismatched. The verification of the format file mainly checks whether the cluster, tenant, and backup destination type specified in the file are consistent with those of the current operation.

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

Back up keys

Before you back up data, check the encryption status of the source tenant. If transparent encryption is configured for the source tenant, you also need to back up the encryption keys of the source tenant.

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

2. Back up the keys.

   • Back up the keys of a specified tenant from the system tenant

     Use the ```sql ALTER SYSTEM BACKUP KEY TENANT = tenant_name TO 'backup_key_path' ENCRYPTED BY 'password';

   • Back up the keys of the current tenant from a user tenant

     The statement is as follows:

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

   In the statements:

   • backup_key_path: the path where the keys are to be backed up. You need to specify this parameter. It cannot be the same as the path for backing up data or archiving logs. You can customize this path.

   • password: the password for encrypting the key backup path.

   Here is an example of backing up the keys of the mysql_tenant tenant to the file:///data_backup_dest/key path from the system tenant:

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

3. After the configuration is successful, you can query the path where the keys are backed up from the view.

   • Query the CDB_OB_BACKUP_STORAGE_INFO view for the system tenant to obtain the path where the keys are backed up.

     SELECT * FROM oceanbase.CDB_OB_BACKUP_STORAGE_INFO;
     

   • Query the DBA_OB_BACKUP_STORAGE_INFO view for a user tenant to obtain the path where the keys are backed up.

     MySQL mode

     Oracle 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 more information about the columns 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.