Prepare for log archiving|V4.3.3|OceanBase Database| docs|Distributed Database

Prepare for log archiving

Last Updated：2026-07-25 06:58:08 Updated

This topic describes the preparations for log archiving.

Configure the log archive concurrency level (optional)

If you enable the ARCHIVE mode, you can increase the log archive concurrency level to speed up the log archiving process in 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 set at the tenant level specifies the total number of worker threads for log archiving. The setting takes effect immediately without the need to restart the OBServer node. The value range is [0, 100]. The default value is 0, which indicates that the database adopts an adaptive log archive concurrency level. We recommend that you use the default value.

Notice

If the tenant has four or fewer CPU cores, we recommend that you use the default value and do not modify the concurrency level of log archive.

You can set the parameter in the following ways:
- Adjust the log archive concurrency level for a user tenant from the sys tenant
```
ALTER SYSTEM SET log_archive_concurrency = 10 TENANT = mysql_tenant;
```
- Adjust the log archive concurrency level for all user tenants from the sys tenant
```
ALTER SYSTEM SET log_archive_concurrency = 10 TENANT = all_user;
```
  or
```
ALTER SYSTEM SET log_archive_concurrency = 10 TENANT = all;
```
  Note
  
  Starting from OceanBase Database V4.2.1, TENANT = all_user and TENANT = all express the same semantics. If you want an operation to take effect on all user tenants, we recommend that you use TENANT = all_user. TENANT = all will be deprecated.
- Adjust the log archive concurrency level 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 set 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 operation of configuring an archive destination 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 a user tenant.

Note

In MySQL mode, the administrator user is the root user. In Oracle mode, the administrator user is the SYS user.
Configure the destination for archiving logs.
- Configure the destination for archiving logs 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 logs 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.x, you do not need to change the archive path. In addition, when upgrading from OceanBase Database V4.1.x to V4.2.x, you can archive logs during the upgrade.

The following table provides more information about the configuration attributes:
- Configure the LOCATION attribute (mandatory)
  
  The LOCATION attribute specifies the archive path. Currently, OceanBase Database supports archiving logs to NFS, Alibaba Cloud OSS, Amazon S3, and object storage services compatible with the S3 protocol, such as Huawei Cloud OBS, Google Cloud GCS, and Tencent Cloud COS. Some archive media may have prerequisites. For more information, see Backup media requirements in Overview of physical backup and restore.
  Alibaba Cloud OSS
  
  NFS
  
  AWS S3
  
  Compatible object storage services
  When you use OSS as the archive destination, in addition to setting the archive path, host, access_key, and access_id, you can also set the delete_mode attribute to configure the cleanup mode for archive files. The delete_mode attribute supports the delete mode and the tagging mode. If you do not explicitly set the delete_mode attribute, the default delete mode is used.
  
  In addition, OSS supports specifying the checksum_type attribute to set a checksum algorithm to verify the integrity of archive files. The supported values are md5 and no_checksum. If you do not explicitly set the checksum_type attribute, the default value md5 is used.
  
  For more information about the delete_mode attribute and the checksum_type attribute, see SET LOG_ARCHIVE_DEST.
  
  Notice
  
  When you use an object storage service as the archive destination, separate the parameters in the object storage service path with &. Make sure that the parameters contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameters contain other characters, the setting might fail.
  
  Here is an example:
  
  When you use OSS as the archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant and configures the delete mode and md5 algorithm for verifying the integrity of archive files.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=oss://oceanbase-test-bucket/backup/archive?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 archive files, you can set the checksum_type attribute to no_checksum. Here is an example:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com&access_id=****&access_key=****&delete_mode=delete&checksum_type=no_checksum' TENANT = mysql_tenant;
  
  When you use OSS as the archive destination, the user sets the archive path for the current tenant and configures the delete mode and md5 algorithm for verifying the integrity of archive files.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=oss://oceanbase-test-bucket/backup/archive?host=***.aliyun-inc.com&access_id=***&access_key=***&delete_mode=delete&checksum_type=md5';
  
  In the preceding example, oss:// indicates that Alibaba Cloud OSS is used as the archive destination, the bucket name is oceanbase-test-bucket, the path within the bucket is /backup/archive, and the parameters after the ? are other path parameters. The host attribute sets the host address of the bucket. The access_id and access_key attributes set the access keys of OSS. The delete mode is configured, and the integrity of archive files is verified by using the MD5 algorithm.
  
  After you set 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 using NFS as the archive destination, note that:
  
  The value of the LOCATION attribute cannot contain a question mark (?).
  
  The value of the LOCATION attribute must be an absolute path, and OBServer node must have read and write permissions for the path.
  
  All OBServer nodes must mount the same NFS server. In addition, to ensure smooth archiving, 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 archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive' TENANT = mysql_tenant;
  
  When you use NFS as the archive destination, the user sets the archive path for the current tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive';
  
  In the preceding example, file:// indicates that NFS is used as the archive destination, and the archive path is /data/nfs/backup/archive.
  AWS S3 supports configuring the delete_mode attribute to configure the cleanup mode for archive files. The configuration method is the same as for Alibaba Cloud OSS. In addition, AWS S3 supports specifying the checksum_type attribute to set a checksum algorithm to verify the integrity of archive files. The supported values are md5 and crc32. If you do not explicitly set the checksum_type attribute, the default value md5 is used.
  
  For more information about the delete_mode attribute and the checksum_type attribute, see SET LOG_ARCHIVE_DEST.
  
  Notice
  
  When you use an object storage service as the archive destination, separate the parameters in the object storage service path with &. Make sure that the parameters contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameters contain other characters, the setting might fail.
  
  When you use S3 as the archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant, configures the delete mode, and sets the crc32 algorithm for verifying the integrity of archive files.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com&access_id=******&access_key=******&s3_region=******&delete_mode=delete&checksum_type=crc32' TENANT = mysql_tenant;
  
  When you use S3 as the archive destination, the user sets the archive path for the current tenant, configures the delete mode, and sets the crc32 algorithm for verifying the integrity of archive files.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com&access_id=******&access_key=******&s3_region=******&delete_mode=delete&checksum_type=crc32';
  
  In the preceding example, s3:// indicates that Amazon S3 is used as the archive destination, the bucket name is oceanbase-test-bucket, the path within the bucket is /backup/archive, and the parameters after the ? are other path parameters. The host attribute sets the domain name of the Amazon S3 service. The access_id and access_key attributes set the access keys of AWS. The s3_region attribute, which is required when S3 is used as the archive destination, sets the region where the S3 bucket is located. The delete mode is configured, and the integrity of archive files is verified by using the CRC32 algorithm.
  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 (the object storage service must be compatible with several S3 APIs that are implemented in OceanBase Database) can be used as the archive destination for OceanBase Database. You can access compatible object storage services in the same way as you access S3, for example, Amazon Cloud Storage (OBS), Google Cloud Storage (GCS), and Tencent Cloud COS.
  
  You can specify the checksum_type attribute to set a checksum algorithm to verify the integrity of archive files when you use S3-compatible object storage services as the archive destination. The supported value is md5. If you do not explicitly set the checksum_type attribute, the default value md5 is used. For more information about the checksum_type attribute, see SET LOG_ARCHIVE_DEST.
  
  Notice
  
  When you use an object storage service as the archive destination, separate the parameters in the object storage service path with &. Make sure that the parameters contain only uppercase and lowercase English letters, numbers, /-_$+=, and wildcard characters. If the parameters contain other characters, the setting might fail.
  
  Here is an example of configuring a compatible object storage service as the archive destination:
  
  When you use a compatible object storage service as the archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****' TENANT = mysql_tenant;
  
  When you use a compatible object storage service as the archive destination, the user sets the archive path for the current tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****';
  
  In the preceding example, s3:// indicates that a compatible object storage service is used as the archive destination, the bucket name is oceanbase-test-bucket, the path within the bucket is /backup/archive, and the parameters after the ? are other path parameters. The host attribute sets the domain name of the compatible object storage service. The access_id and access_key attributes set the access keys of the compatible object storage service.
  
  Here is an example of configuring GCS as the archive destination:
  
  When you use GCS as the archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com&access_id=****&access_key=****' TENANT = mysql_tenant;
  
  When you use GCS as the archive destination, the user sets the archive path for the current tenant.
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com&access_id=****&access_key=****';
  
  In the preceding example, s3:// indicates that a compatible object storage service is used as the archive destination, the bucket name is oceanbase-test-bucket, the path within the bucket is /backup/archive, and the parameters after the ? are other path parameters. The host attribute sets the domain name of the compatible object storage service. The access_id and access_key attributes set the access keys of the compatible object storage service.
  
  o configure COS as the archive destination, perform the following steps:
  
  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 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
  
  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.
  
  Set the archive path and the BINDING attribute.
  
  When you use COS as the archive destination, the tenant administrator of the sys tenant sets the archive path for the mysql_tenant tenant and configures the BINDING attribute to the delete mode. The following example shows how to do this:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test/backup/archive?host=cos.ap-xxxx.myqcloud.com&access_id=***&access_key=***&delete_mode=delete' TENANT = mysql_tenant;
  
  When you use COS as the archive destination, the user sets the archive path for the current tenant and configures the BINDING attribute to the delete mode. The following example shows how to do this:
  
  obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test/backup/archive?host=cos.ap-xxxx.myqcloud.com&access_id=***&access_key=***&delete_mode=delete';
  
  In the preceding example, s3:// indicates that a compatible object storage service is used as the archive destination, the bucket name is oceanbase-test, the path within the bucket is /backup/archive, and the parameters after the ? are other path parameters. The host attribute sets the domain name of the compatible object storage service. The access_id and access_key attributes set the access keys of the compatible object storage service. The delete mode is configured.
  
  Notice
  
  Once the log is archived, the data transmission cannot be switched during the archiving process. For example, you cannot switch from S3 to OSS or from OSS to S3.
- Configure the BINDING attribute (optional)
  
  The BINDING attribute specifies the priority mode between the archive and the business. Currently, the Optional mode and the Mandatory mode are supported. If you do not configure the attribute, the default Optional mode is used.
  - In the Optional mode, the business takes priority. In this mode, if the log archiving speed is slower than the log generation speed, the logs may be recycled before they are all archived. Then, the data transmission will be interrupted.
  - In the Mandatory mode, the archive takes priority. In this mode, if the log archiving speed is slower than the data write speed, the data write will be blocked.
  Here is an example of configuring the BINDING attribute when you use NFS as the archive destination:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional' TENANT = mysql_tenant;
```
  Here is an example of configuring the BINDING attribute when you use NFS as the archive destination:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional';
```
- Configure the PIECE_SWITCH_INTERVAL attribute (optional)
  
  The PIECE_SWITCH_INTERVAL attribute specifies the interval for switching piece, which ranges from [1d, 7d]. If you do not configure this attribute, the default value 1d is used.
  
  Here is an example of configuring the PIECE_SWITCH_INTERVAL attribute when you use NFS as the archive destination:
```
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;
```
  Here is an example of configuring the PIECE_SWITCH_INTERVAL attribute when you use NFS as the archive destination:
```
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 that you set from the views.

In the sys tenant, you can query the parameters from the CDB_OB_ARCHIVE_DEST view; in a user tenant, you can query the parameters 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, note the following considerations when you configure a log archive destination:

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 mainly checks whether the cluster, tenant, and backup destination type specified in the format file are consistent with those of the current operation.
If the format file does not exist or its content verification fails during backup, the task will fail.

Additionally, after the archive destination 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 value of BINDING, you still need to specify the value of the BINDING attribute in the command. Otherwise, the value of the unspecified attribute will default to the default value.

To change the attribute value, execute the following statements.

Modify the value of the attribute in 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 value of the attribute in the user tenant.

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

Configure the archive delay

OceanBase Database uses the tenant-level parameter archive_lag_target to control the latency of log archiving for a tenant. The parameter supports the time units of milliseconds (ms), seconds (s), minutes (m), and hours (h). The default value is 2m, which specifies the maximum interval in minutes between two consecutive archive I/Os. This ensures that online logs are archived in time, thereby reducing the risk of data loss.

Log archiving in OceanBase Database is performed on a log stream basis. If logs are written to a log stream and the time since the last archive of the log stream exceeds the interval specified by the archive_lag_target parameter, the system triggers an archive action to archive the unarchived logs in the log stream.

For example, if the value of the archive_lag_target parameter is set to 120s (or 2 minutes), each log stream will attempt to initiate an archive action every 2 minutes (unless another condition is met, such as the buffer for log archive caching being filled up), ensuring that the interval between the current archive action and the last archive action in the log stream is less than 2 minutes. Note that when the value of the archive_lag_target parameter is set to 0, the system can achieve quasi-real-time archiving.

For more information about the archive_lag_target parameter, see archive_lag_target.

Prerequisites

Before you modify the value of the archive_lag_target parameter, make sure that the archive destination has been configured. If the archive destination is not configured, the system will prompt you with the log_archive_dest has not been set, set archive_lag_target is not allowed message.

Considerations

If the archive medium is OSS, NFS, or COS, you can set the value of the archive_lag_target parameter to any value within the allowed range; if the archive medium is S3, the value of the archive_lag_target parameter cannot be less than 60s. Otherwise, the system will return an error.
We recommend that you set the archive_lag_target parameter to an appropriate value to avoid excessive I/O frequency, which can compromise system performance. Especially when an object storage service is used for log archiving, set the value of this parameter to a relatively low value. A high value cannot meet the requirement on timeliness for data restoration, therefore, it cannot ensure an adequate RPO. You need to set this parameter based on your business needs and the performance of the archive medium.

Procedure

Log in to the database as the tenant administrator of the sys tenant or a user tenant.
Choose an appropriate statement based on your situation to configure the archive delay.

The procedure is as follows:
- Configure the archive delay for a specified tenant from the sys tenant
```
obclient> ALTER SYSTEM SET archive_lag_target = '120s' TENANT = mysql_tenant;
```
  Notice
  
  When you configure the archive_lag_target parameter, the TENANT = all_user clause in the sys tenant is not supported.
- Configure the archive delay for the current tenant from a user tenant
```
obclient> ALTER SYSTEM SET archive_lag_target = '120s';
```

OceanBase

Customer Stories

Documentation

Prepare for log archiving

Configure the log archive concurrency level (optional)

Notice

Note

Configure the archive destination

Considerations

Procedure

Note

Notice

Notice

Notice

Notice

Notice

Notice

Considerations and notes

Configure the archive delay

Prerequisites

Considerations

Procedure

Notice

References