Overview
The ALTER SYSTEM SET LOG_ARCHIVE_DEST statement is used to configure the archive destination for user tenants. The configuration of the archive destination mainly includes attributes such as LOCATION, BINDING, and PIECE_SWITCH_INTERVAL.
Usage limitations and considerations
The system tenant and Meta tenant do not support backup and recovery, so they do not require an archive destination configuration.
Currently, OceanBase AI Database supports backup media including NFS, Azure Blob, AWS S3, and object storage compatible with the S3 protocol, such as Huawei OBS, Google GCS, and Tencent Cloud COS. Some backup media may require meeting specific basic requirements before use. For detailed requirements of each backup medium, refer to the Backup media requirements section in Overview of physical backup and recovery.
When configuring attributes such as
LOCATION,BINDING, andPIECE_SWITCH_INTERVAL, separate these parameters with spaces. Ensure no spaces are present before or after the equal sign (=) that sets each parameter's value.After the archive destination is successfully configured, incremental configuration is not supported. That is, you must specify the values for all parameters every time you execute the
ALTER SYSTEM SET LOG_ARCHIVE_DESTstatement. Otherwise, unspecified parameters will use default values.
Privilege requirements
This statement must be executed by the root user of the sys tenant (root@sys) or the administrator user (root) of a user tenant.
Syntax
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=archive_path [BINDING=archive_mode] [PIECE_SWITCH_INTERVAL=piece_switch_interval]' [TENANT = tenant_name];
Parameters
Parameter |
Description |
|---|---|
| archive_path | Specifies the archive path. For more information about this parameter, see archive_path. |
| archive_mode | Configures the priority mode between archiving and business operations. Optional. Currently supports Optional mode and Mandatory mode. If not set, the default is Optional mode.
|
| piece_switch_interval | Configure the switch cycle of the piece. The value range is [1d, 7d]. If not specified, the default value is 1d. For more information about pieces, see Log archiving overview. |
| tenant_name | The system tenant specifies the tenant name of the destination for archiving.
NoticeOnly the system tenant needs to specify the target tenant via the |
archive_path
Specifies the archive path and source configuration. The following describes the archive_path format for different types of media.
NFS
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file://your-nfs-server-path/your-archive-path[?{zone=zone_name | idc=idc_name | region=region_name}];
The related parameters are described as follows:
file://your-nfs-server-path/your-archive-path: Specifies the NFS server path and the archive path.zone,idc,region: Specifies the source of the archive path, i.e., the range of nodes that can access this path. These are optional parameters, separated from the archive path by a question mark (?). You can select configurations at three different levels:zone,idc, orregion. You can only choose one level at a time or not set any level at all. By default, no level is set.If you need to set the region or IDC level, you must first set the region information using the
ALTER SYSTEM MODIFY ZONE zone_name SET REGION=region_name;statement, or set the IDC information using theALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name;statement. It is recommended to set the source configuration at the IDC level. This way, the archive task can utilize an IDC with more network bandwidth resources, has a wider range of selectable nodes, and users do not need to worry about changes in zones within the IDCs in the cluster.If the specified
zone,idc, orregiondoes not exist during setup, an error will be reported indicating that the source information does not exist (error code-9133).Since all log archive traffic is written by the leader replica, there is no difference in access priority for log archive paths; only the range of nodes that can access the archive path is limited. If you need to set multiple zones, IDCs, or regions, separate the multiple values with commas (,) or semicolons (;). For example,
zone=z1,z2;z3specifiesz1,z2, andz3as the source for archiving.When configuring
zone,idc, orregion, the leader replica must be located within the specifiedzone,idc, orregion. Otherwise, archiving will not proceed.
Object storage
# AWS S3
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://your-bucket-name/your-archive-path?host=s3.your-region.amazonaws.com&access_id=your-access-id&access_key=your-access-key&s3_region=your-s3-region[&delete_mode={delete | tagging}][&checksum_type={md5 | crc32}][&{zone=zone_name | idc=idc_name | region=region_name}];
# Object storage compatible with the S3 protocol
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://your-bucket-name/your-archive-path?host=your-service.com&access_id=your-access-id&access_key=your-access-key[&addressing_model={virtual_hosted_style | path_style}][&checksum_type=md5][&{zone=zone_name | idc=idc_name | region=region_name}];
# Azure Blob
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=azblob:////your-bucket-name/your-archive-path?host=your-service.com&access_id=your-access-id&access_key=your-access-key[&delete_mode={delete | tagging}][&checksum_type=md5][&{zone=zone_name | idc=idc_name | region=region_name}]';
The related parameters are described as follows:
Notice
When using object storage as the archive medium, the parameters of the object storage path are separated by the & symbol. Ensure that the parameter values you enter contain only uppercase and lowercase letters, numbers, /-_$+=, and wildcard characters. Entering characters other than those listed above may cause the configuration to fail.
host: The access domain name of the object storage service.For Azure Blob object storage, the value corresponding to the
hostparameter can be obtained by concatenating the container properties or the storage account's connection string. The prefix for thehostparameter must be specified ashttp://orhttps://. In addition, Azure Blob has security transfer enabled by default, and access is typically throughhttps://. If you need to access throughhttp://, you must disable the security transfer option for Azure Blob. For detailed operations on disabling the security transfer option for Azure Blob, see the Azure Blob official documentation.access_id: The access key ID for object storage.access_key: The access key for object storage.delete_mode: Specifies the cleanup mode for archived files. This parameter is supported only for AWS S3, COS (accessed via the S3 protocol), and Azure Blob storage services. Multiple options are concatenated with the&operator. Valid values:delete: Indicates that the cleanup mode is to directly delete archive files that meet the cleanup criteria.After this mode is enabled, when you automatically clean up archived files, the system will directly delete the archived files that meet the cleanup criteria.
tagging: Indicates that the cleanup mode is to set aTagfor archive files that meet the cleanup criteria, and the archive files will still be retained.After this mode is enabled, when you automatically clean up archived files, the system will tag the files that meet the cleanup criteria. The tag's
keywill be"delete_mode"and thevaluewill be"tagging". This allows users to later manage the lifecycle of these files in object storage using the set tag.
checksum_type: Specifies the checksum algorithm for verifying the integrity of the archive file. If not explicitly specified, MD5 is used by default for all object storages. The supported values for this parameter vary by object storage:md5: checks the integrity of the archive file using the MD5 algorithm.Notice
MD5 verification does not take effect for the
GetObjectAPI.no_checksum: Do not verify the integrity of the archive file. This value is supported only for Azure Blob storage. For object storage accessed through the S3 protocol, including AWS S3, OBS, GCS, and COS, this value is not supported due to limitations of the S3 SDK.crc32: uses the CRC32 algorithm to verify the integrity of the archive file. This value is supported only by AWS S3.
s3_region: The region where the Amazon S3 bucket is located. This parameter is required when the archive medium is AWS S3.addressing_model: the URL format for accessing object storage. This is an optional parameter for accessing object storage services compatible with the S3 protocol, such as OBS, GCS, and COS. It must be concatenated with other parameters using the&symbol. Currently, this parameter supports the following two values:virtual_hosted_style: The default value. It specifies to access object storage in virtual-hosted style.path_style: specifies to access object storage in path-style.
For example, to configure a user tenant to use OBS as its archive media and access it in virtual-hosted-style format, you can use the following statement:
ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****&addressing_model=virtual_hosted_style';zone: the source for the archive path, which specifies the range of nodes that can access this path. This is an optional parameter. Multiple options are separated by the ampersand (&) symbol. You can specify configurations at three different levels:zone,idc, orregion. Only one level can be specified at a time, or none at all. By default, no level is specified.If you need to set the region level or IDC level, you must first use the
ALTER SYSTEM MODIFY ZONE zone_name SET REGION=region_name;orALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name;statement to configure the region or IDC information. It is recommended to set the source configuration at the IDC level. This way, the archive task can be executed using an IDC with more network bandwidth resources, providing a wider range of available nodes. Additionally, users do not need to worry about changes in zones within the IDCs of the cluster.If the specified
zone,idc, orregiondoes not exist, an error will be returned indicating that the source information does not exist (error code-9133).Since all traffic for log archiving is written by the leader replica, there is no difference in access priority for log archive paths; only the range of nodes that can access the archive path is limited. If you need to specify multiple zones, IDCs, or regions, separate the values with commas (,) or semicolons (;). For example,
zone=z1,z2;z3specifiesz1,z2, andz3as the source for archiving.When configuring
zone,idc, orregion, the leader replica must be located within the specifiedzone,idc, orregion. Otherwise, archiving cannot proceed.
Examples
System tenant
The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is NFS, the mode is user-business priority, and a piece is split every other day.obclient [oceanbase]> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is NFS. The zones that can access this archive path are z1, z2, and z3. The mode is user-business priority, and a piece is split every other day.obclient [oceanbase]> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive?zone=z1,z2,z3 BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is AWS S3. The cleanup mode for archived files isdelete. The mode is user-business priority, and a piece is split every other day.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 BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is AWS S3. The cleanup mode for archived files istagging. The integrity of archived files is verified using the CRC32 algorithm.obclient [oceanbase]> 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=tagging&checksum_type=crc32' TENANT = mysql_tenant;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is OBS, accessed via the S3 protocol.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;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is GCS, accessed via the S3 protocol.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;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is COS. The cleanup mode for archived files isdelete, and access is via the S3 protocol.Note
When using COS as the archive media, you must first set the cluster-level parameter ob_storage_s3_url_encode_type. For detailed operations, see the Preparation work for log archiving.
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test/backup/archive?host=cos.ap-***.myqcloud.com&access_id=***&access_key=***&delete_mode=delete' TENANT = mysql_tenant;The system tenant configures an archive path for the
mysql_tenanttenant. The archive media is Azure Blob. The cleanup mode isdelete. The verification algorithm is specified asmd5. The mode is user-business priority, and a piece is split every other day.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 BINDING=Optional PIECE_SWITCH_INTERVAL=1d' TENANT = mysql_tenant;
User tenant
Tenant
mysql_tenantconfigures an archive path for itself. The archive media is NFS. The mode is user-business priority, and a piece is split every other day.obclient [oceanbase]> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive BINDING=Optional PIECE_SWITCH_INTERVAL=1d';Tenant
mysql_tenantconfigures an archive path for itself. The archive media is NFS. The region that can access this archive path isregion1. The mode is user-business priority, and a piece is split every other day.obclient [oceanbase]> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=file:///data/nfs/backup/archive?region=region1 BINDING=Optional PIECE_SWITCH_INTERVAL=1d';The tenant
mysql_tenantis configured with an archive path, the archive media is set to AWS S3, the cleanup mode for archived files is set todelete, the user business priority mode is adopted, and a Piece is split every other day.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 BINDING=Optional PIECE_SWITCH_INTERVAL=1d';The tenant
mysql_tenanthas its own archive path configured. The archive media is AWS S3, the cleanup mode for archived files istagging, and the CRC32 algorithm is used to verify the integrity of archived files.obclient [oceanbase]> 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=tagging&checksum_type=crc32';The tenant
mysql_tenantis configured with an archive path for this tenant. The archive medium is OBS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com&access_id=****&access_key=****';The tenant
mysql_tenantis configured with an archive path. The archive medium is GCS, accessed via the S3 protocol.obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com&access_id=****&access_key=****';The tenant
mysql_tenantis configured with an archive path, the archive medium is set to COS, the cleanup mode for archived files is set todelete, and access is provided via the S3 protocol.Notice
When using COS as the archiving media, you must first set the cluster-level parameter ob_storage_s3_url_encode_type. For detailed operations, see the Preparation work for log archiving.
obclient> ALTER SYSTEM SET LOG_ARCHIVE_DEST='LOCATION=s3://oceanbase-test/backup/archive?host=cos.ap-***.myqcloud.com&access_id=***&access_key=***&delete_mode=delete';For the
mysql_tenanttenant, configure an archive path, set the archive medium to Azure Blob, configure the cleanup mode todelete, specify the verification algorithm asmd5, enable user business priority mode, and split data into Pieces every other day.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 BINDING=Optional PIECE_SWITCH_INTERVAL=1d';