Prepare for log archiving|V4.2.0| docs|Distributed Database

Prepare for log archiving

Last Updated：2025-12-04 09:32:54 Updated

This topic describes the preparations for log archiving.

(Optional) Configure the log archive concurrency

Before you enable the archiving mode, you can configure the log archive concurrency to increase the log archiving speed of the tenant.

Log in to the database as the tenant administrator of the sys tenant or a user tenant.
Choose an appropriate statement to set the log_archive_concurrency parameter.

The log_archive_concurrency parameter at the tenant level specifies the total number of worker threads for log archiving. The parameter value takes effect immediately without the need to restart the OBServer node. The value range is [0, 100]. The default value is 0, which means that the database uses adaptive log archive concurrency. We recommend that you use the default value.

Notice

We recommend that you use the default value for small tenants (with less than or equal to four CPU cores) and do not modify the value of this parameter.

You can set the parameter in the following ways:
- Adjust the log archive concurrency for a user tenant in the sys tenant
```
ALTER SYSTEM SET log_archive_concurrency = 10 TENANT = mysql_tenant;
```
- Adjust the log archive concurrency for all user tenants in the sys tenant
```
ALTER SYSTEM SET log_archive_concurrency = 10 TENANT = ALL;
```
- Adjust the log archive concurrency for the current user tenant
```
ALTER SYSTEM SET log_archive_concurrency = 10;
```
For more information about the log_archive_concurrency parameter, see log_archive_concurrency.

Configure the archive destination

Before you start a log archiving task, you must use the ALTER SYSTEM command to configure the LOG_ARCHIVE_DEST parameter. The sys tenant is a cluster management tenant that does not contain user data and does not support backup and restore. Therefore, you do not need to configure an archive destination for the sys tenant.

The procedure mainly involves setting the LOCATION, BINDING, and PIECE_SWITCH_INTERVAL parameters.

Considerations

Procedure

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

Note

The administrator user in MySQL mode is the root user, and that in Oracle mode is the SYS user.
Configure the destination for archiving.

Currently, OceanBase Database supports NFS and Alibaba Cloud OSS as the destination for archiving.
- Configure the destination for archiving for a specified tenant from the sys tenant
```
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=archive_path [BINDING=archive_mode] [PIECE_SWITCH_INTERVAL=piece_switch_interval]' TENANT = tenant_name;
```
- Configure the destination for archiving for the current tenant
```
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=archive_path [BINDING=archive_mode] [PIECE_SWITCH_INTERVAL=piece_switch_interval]';
```
Notice

After upgrading from OceanBase Database V4.0.x to V4.1.0, you need to change the archive path. After upgrading from OceanBase Database V4.1.x to V4.2.0, you do not need to change the archive path. When upgrading from OceanBase Database V4.1.x to V4.2.0, you can archive logs during the upgrade process.

The following details are required for configuring the destination for archiving.
- Configure the LOCATION parameter (mandatory)
  
  The LOCATION parameter specifies the destination for archiving. Currently, OceanBase Database supports NFS and Alibaba Cloud OSS as the archive media.
  Alibaba Cloud OSS
  
  NFS
  When you use Alibaba Cloud OSS as the destination for archiving, you can specify the archive path, host, access_key, and access_id. Additionally, you can use the delete_mode parameter to specify the cleanup mode for archive files.
  
  Notice
  
  Do not use special characters, such as commas, in the access_key parameter when you use Alibaba Cloud OSS as the archive media.
  
  The delete_mode parameter supports two cleanup modes, delete and tagging. If you do not specify the mode, the default delete mode is used.
  
  delete: Specifies to directly delete archive files that meet the cleanup requirements.
  
  If you specify this mode, the system will directly delete the archive files that meet the cleanup requirements when you automatically clear the archive files.
  
  Notice
  
  This mode is the default cleanup mode. If you do not specify the delete_mode parameter, the delete mode is used.
  
  tagging: Specifies to set the Tag for archive files that meet the cleanup requirements. The archive files will still be retained.
  
  If you specify this mode, the system will set a tag for the archive files that meet the cleanup requirements when you automatically clear the archive files. The tag's key is set to "delete_mode" and the value is set to "tagging". This way, you can manage the lifecycle of these files on Alibaba Cloud OSS by using the tag.
  
  When you use Alibaba Cloud OSS as the destination for archiving, the tenant administrator of the mysql_tenant tenant in the sys tenant can configure the destination for archiving and specify the tagging cleanup mode as shown below:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=oss://oceanbase-test-bucket/backup/archive?host=***.aliyun-inc.com&access_id=***&access_key=***&delete_mode=tagging' TENANT = mysql_tenant;
  
  The user tenant administrator can configure the destination for archiving and specify the tagging cleanup mode as shown below:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=oss://oceanbase-test-bucket/backup/archive?host=***.aliyun-inc.com&access_id=******&access_key=******&delete_mode=tagging';
  
  In the examples above, oss:// indicates that Alibaba Cloud OSS is used as the destination for archiving. The storage bucket name is oceanbase-test-bucket, and the path within the storage bucket is /backup/archive. The parameters after the ? are other parameters in the path. host specifies the host address of the storage bucket. access_id and access_key specify the access keys of Alibaba Cloud OSS. The cleanup mode is set to tagging.
  
  After you specify the delete mode or the tagging mode, for more information about how to automatically clear archive data, see Automatically clear backed-up data.
  Notice
  
  When you use NFS as the destination for archiving, note that:
  
  The value of the LOCATION parameter cannot contain the question mark character (?).
  
  The value of the LOCATION parameter must be an absolute path, and the OBServer node must have read and write permissions for the path specified by the LOCATION parameter.
  
  Make sure that all OBServer nodes have mounted the same NFS server. Additionally, to ensure a smooth archiving process, it is recommended to use the parameters suggested in this topic to mount NFS. For more information, see Deploy an NFS client.
  
  When you use NFS as the destination for archiving, the tenant administrator of the mysql_tenant tenant in the sys tenant can configure the destination for archiving as shown below:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive' TENANT = mysql_tenant;
  
  The user tenant administrator can configure the destination for archiving as shown below:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive';
  
  In the examples above, file:// indicates that NFS is used as the destination for archiving. The path for archiving is /data/nfs/backup/archive.
- Configure the BINDING parameter (optional)
  
  The BINDING parameter specifies the priority mode for archiving and business. Currently, the Optional mode and the Mandatory mode are supported. If you do not specify the parameter, the default Optional mode is used.
  - The Optional mode indicates that the business takes priority. In this mode, if the archiving process cannot keep up with the log generation speed, the system may recycle logs that have not been archived, which may cause a log gap.
  - The Mandatory mode indicates that archiving takes priority. In this mode, if the archiving process cannot keep up with the data write speed, the system will prevent data write.
  When you use NFS as the destination for archiving, the tenant administrator of the mysql_tenant tenant in the sys tenant can configure the destination for archiving and set the BINDING parameter as shown below:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional' TENANT = mysql_tenant;
```
  The user tenant administrator can configure the destination for archiving and set the BINDING parameter as shown below:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional';
```
- Configure the PIECE_SWITCH_INTERVAL parameter (optional)
  
  The PIECE_SWITCH_INTERVAL parameter specifies the interval for switching pieces of logs, which ranges from [1d, 7d]. If you do not specify the parameter, the default value 1d is used.
  
  When you use NFS as the destination for archiving, the tenant administrator of the mysql_tenant tenant in the sys tenant can configure the destination for archiving and set the interval to switch a log piece every two days as shown below:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;
```
  The user tenant administrator can configure the destination for archiving and set the interval to switch a log piece every two days as shown below:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional PIECE_SWITCH_INTERVAL=1d';
```
After the configuration, you can query the parameters' settings from views.

In the sys tenant, you can query the parameters' settings from the CDB_OB_ARCHIVE_DEST view; in a user tenant, you can query the settings from the DBA_OB_ARCHIVE_DEST view. For more information, see Query the archive parameters.

Considerations and notes

After the parameter LOG_ARCHIVE_DEST is set, the system will create a format file in the destination directory specified in the configuration to verify the validity of the backup destination and the integrity of the data in the destination. Therefore, when you configure the destination for log archiving, note the following considerations:

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 exists, the content of the file must pass the verification. Otherwise, an error -9081 will occur, indicating that the format file is mismatched. The content verification of the format file checks whether the cluster, tenant, and backup destination type are consistent with those of the current operation.
If the format file does not exist or fails the verification during backup, the task will fail.

After the destination for log archiving is configured, incremental configuration is not supported. For example, assume that the BINDING attribute of the NFS archive path /data/nfs/backup/archive is set to Mandatory, and the PIECE_SWITCH_INTERVAL attribute is set to 1d. If you want to change the value of PIECE_SWITCH_INTERVAL to 2d while retaining the setting of the BINDING attribute, you still need to specify the attribute values in the command. Otherwise, the unspecified attributes will use default values.

To modify the attribute values, execute the following statements.

Modify the parameters of a user tenant from the sys tenant

obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST = 'LOCATION=file:///data/nfs/backup/archive BINDING=Mandatory PIECE_SWITCH_INTERVAL=2d' TENANT = mysql_tenant;

Modify the parameters of a user tenant from the same tenant

obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST = 'LOCATION=file:///data/nfs/backup/archive BINDING=Mandatory PIECE_SWITCH_INTERVAL=2d';

Prepare for log archiving

(Optional) Configure the log archive concurrency

Notice

Configure the archive destination

Considerations

Procedure

Note

Notice

Notice

Notice

Notice

Considerations and notes

References