Overview of physical backup and restore

Backup and restore is a core component of the high availability feature in OceanBase Database. It primarily serves to ensure data security, including protection against storage media damage and user misoperations. If data loss occurs due to storage media damage or user error, you can restore your data from backup.

Overview

The backup and restore module of OceanBase Database provides features such as backup, backup verification, restore, and cleanup.

Backup

OceanBase Database supports physical backup at the tenant level. Physical backup consists of data backup and log archiving, so it is a combination of these two functions. The term "tenant" here refers to the user's User tenant; physical backup is not supported for the sys or Meta tenant.

Data backup is the function of backing up data. It is divided into full backup and incremental backup:

• Full backup refers to backing up all macroblocks.

• Incremental backup refers to backing up the macroblocks that were newly added or modified since the last backup.

The main data backed up by data backup includes:

• Tenant-related information, including the tenant name, cluster name, time zone (timezone), locality, and tenant compatibility mode (MySQL or Oracle).

• All user table data.

  Note

  Data backup backs up system variables and tenant parameters, but does not back up cluster-level parameters or private system table data.

Log archiving is the automatic archiving of log data. OBServer nodes regularly archive log data to the specified backup path. This action is fully automatic and does not require external periodic triggering. After the log archiving service is enabled, data dictionaries are also archived.

Backup verification

The backup verification feature of OceanBase Database is mainly used to address the integrity and correctness of backup and archived data. Users can proactively verify whether backup sets and archived logs have issues such as missing files, physical data corruption, or logical inconsistencies without performing an actual restore operation.

Backup verification can be classified into Basic verification and Physical verification based on the verification level. Specifically:

• Basic verification: Checks only the integrity of the file list.

• Physical verification: Checks the correctness of physical data and logical consistency.

Backup verification supports verification at different granularities, including the entire backup and archive path, a specified backup set or log archive piece, and a specified path across clusters.

Restore

The overall architecture of physical restore is as follows:

1. Physical restore supports restore at the tenant level and the table level.

   • Tenant-level restore: Tenant-level restore is the process of rebuilding a new tenant based on backups of existing data. Tenant restore ensures global consistency across tables and partitions.

   • Table-level restore: Table-level restore restores a user-specified table from backup data to an existing tenant. The existing tenant can be the same one where the original table resides, a different tenant within the same cluster, or a tenant in a different cluster.

2. Tenant-level restore supports both full restore and quick restore.

   Notice

   A tenant restored by the quick restore method does not support manual initiation of major compactions, data backup, or switchover/failover to become the primary database. It can only exist as a standby database.

   • Full restore: Refers to restoring macroblock data and incremental logs. After all data is restored from backup media to the local storage, the restored tenant can provide services. The full restore process includes the Restore and Recover steps for tenant system tables and user tables. The Restore step copies the baseline data to the target tenant's OBServer nodes, while the Recover step restores the logs corresponding to the baseline to the respective OBServer nodes.

   • Quick restore: Refers to providing services to users without restoring macroblock data, which can reduce restore wait time and lower user usage costs.

3. Select a restore point for your physical restore

   • Complete restore: No restore timestamp is specified.

   • Incomplete restore by specifying SCN or timestamp: Here, SCN is an internal, precise version number in OceanBase Database. A timestamp is accurate to nanoseconds in Oracle-compatible mode with no precision loss; in MySQL-compatible mode, it is accurate to microseconds, with precision lost after microseconds.

For the physical restore process, see Restore process.

Cleanup

OceanBase Database provides automatic and manual cleanup capabilities for backup data, allowing users to handle it flexibly based on their business scenarios.

• Automatic cleanup: An automatic cleanup mechanism based on the recovery window (recovery_window). After you set an expiration time for backup data, the system periodically triggers cleanup tasks to remove expired backup sets and data archive pieces.

• Manual cleanup: Manual cleanup can be divided into two categories: the first is to manually clean up specific backup sets or log archive pieces; the second is to manually clear all backup sets or data archive pieces in an entire path (either the data backup path or the log archive path).

Backup media requirements

The current version of OceanBase Database supports backup media such as Alibaba Cloud OSS, NFS, Azure Blob, AWS S3, and object storage compatible with the S3 protocol (for example, Huawei OBS, Google GCS, and Tencent Cloud COS). Some backup media require meeting specific basic requirements before they can be used.

SDK version requirements

In the current version, both the Single-Named Mode (SN mode) and Shared Storage Mode (SS mode) use obdal by default to access object storage. obdal is a unified object storage framework developed based on OpenDAL. For more information about OpenDAL, see OpenDAL.

Additionally, if you need to use the object storage SDK, the following table describes the version correspondence between the object storage SDK and the observer version:

Interface requirements

• Alibaba Cloud OSS:

  • Supports Alibaba Cloud's official OSS. The required interfaces are listed in the following table.

    Interface name	Description
    PutObject	Upload a single object.
    DeleteObject	Delete a single object.
    DeleteObjects	Batch delete objects.
    GetObject	Retrieve a specific object.
    ListObjects	List all objects in the storage space (requires strong consistency).
    HeadObject	Retrieve the metadata of a specific object.
    AppendObject	Upload an object in append-only mode.
    PutObjectTagging (Optional)	Set or update object tags.
    GetObjectTagging (Optional)	Retrieve object tags.
    InitiateMultipartUpload	Initialize a multipart upload.
    UploadPart	Upload a part.
    CompleteMultipartUpload	Merge uploaded parts into a single object.
    AbortMultipartUpload	Cancel a multipart upload and delete uploaded parts.
    ListMultipartUploads	List initialized but incomplete or unterminated multipart uploads.
    ListParts	List parts that have been uploaded in a multipart upload task.

  • Supports only the V1 signature algorithm.

• NFS: Requires NFS version 3 or later.

• Object storage compatible with the S3 protocol (for example, Huawei OBS, Google GCS, and Tencent Cloud COS):

  1. Must support the S3 API behaviors shown in the following table.

     Interface name	Description
     PutObject	Upload a single object.
     DeleteObject	Delete a single object.
     DeleteObjects	Batch delete objects.
     GetObject	Download a single object.
     ListObjects	List all objects under the path.
     HeadObject	Retrieve the metadata of a specific object.
     PutObjectTagging (Optional)	Set object tags.
     GetObjectTagging (Optional)	Retrieve object tags.
     CreateMultipartUpload	Initialize a multipart upload.
     UploadPart	Upload a single part.
     CompleteMultipartUpload	Merge uploaded parts into a single object.
     AbortMultipartUpload	Abort a multipart upload and delete uploaded parts.
     ListMultipartUploads	List uploaded parts.
     ListParts	List parts that have been uploaded in a multipart upload task.

  2. The object access URL in virtual-hosted–style is required. For more information about virtual-hosted–style requests, visit AWS S3 official website.

When selecting a backup medium, you can use the test_io_device command in the ob_admin tool to verify whether the I/O interface and current I/O permissions provided by the backup medium meet the requirements of backup and restore operations. Additionally, you can use the io_adapter_benchmark command in the ob_admin tool to view the read and write performance of the OBServer node to the backup medium, which serves as a reference for backup performance. For detailed information and usage instructions of the test_io_device and io_adapter_benchmark commands, see test_io_device and io_adapter_benchmark.

Directory structure

Data backup directory

The data backup feature creates directories at the backup destination, and the file types stored in each directory are as follows.

data_backup_dest
├── format.obbak                                            // Formatting information for the backup path
├── check_file
│   └── 1002_connect_file_20230111T193020.obbak             // Connectivity check file
├── backup_sets                                             // Summary directory for the data backup list, records all data backup set lists
│   ├── backup_set_1_full_end_success_20230111T193420.obbak // Full backup end placeholder
│   ├── backup_set_1_full_start.obbak                       // Full backup start placeholder
│   ├── backup_set_2_inc_start.obbak                        // Incremental backup start placeholder
│   └── backup_set_2_inc_end_success_20230111T194420.obbak  // Incremental backup end placeholder
└── backup_set_1_full                                        // Full backup set, a file ending with 'full' indicates a full backup, 'inc' indicates an incremental backup
    ├── file_list.0.obbak
    ├── backup_set_1_full_20230111T193330_20230111T193420.obbak // Placeholder, shows the start and end times of a full backup
    ├── single_backup_set_info.obbak                        // Metadata of the current backup set
    ├── tenant_backup_set_infos.obbak                       // Full backup set information for the current tenant
    ├── infos
    ├── logstream_1                                          // Log stream 1
    └── logstream_1001                                       // Log stream 1001

In the data backup directory, the top-level directory contains the following three types of data:

• format.obbak: Records metadata for the backup path.

• check_file: Used to check the connectivity of the user's data backup directory.

• backup_sets: Summary directory for the data backup list, records all data backup set lists.

• backup_set_1_full: This directory represents a data backup set. backup_set_1 indicates that the backup set's backup_set_id is 1. A directory name ending with full indicates a full backup, and inc indicates an incremental backup. Each data backup generates a corresponding backup set, which will not be modified after the backup is complete.

  Within a data backup set, the main contents include:

  • file_list.0.obbak: This file records the files and directories contained in the current directory.

  • backup_set_1_full_20230111T193330_20230111T193420.obbak: This file displays the ID, start, and end times of the current backup set. This file is only used for display purposes.

  • single_backup_set_info.obbak: This file records the metadata of the current backup set, including the backup checkpoint, dependent logs, and other information.

  • tenant_backup_set_infos.obbak: This file records the metadata of all existing backup sets for the current tenant.

  • infos: This directory records the metadata of the data backup set.

  • logstream_1: This directory records all data from log stream 1, which is the system log stream for an OceanBase Database tenant.

  • logstream_1001: This directory records all data for log stream 1001. Log streams greater than 1000 are user log streams for an OceanBase Database tenant.

Backup directory for cluster-level parameters

Each time a backup of cluster-level parameters is initiated, the system generates a backup file for the cluster-level parameters in a specified directory. The specific directory structure is as follows.

cluster_parameters_backup_dest
├── cluster_parameter.20240710T103610.obbak # Information for cluster-level parameters with non-default settings. File naming format: `cluster_parameter.[timestamp]`
└── cluster_parameter.20241018T140609.obbak

Log archive directory

For backup media such as NFS, OSS, and Azure Blob, the log archive feature creates directories at the archive destination and saves files in these directories according to the following types.

log_archive_dest
    ├── check_file
    │   └── 1002_connect_file_20230111T193049.obbak // Connectivity check file
    ├── format.obbak                                // Formatting information for the backup path
    ├── rounds                                      // Rounds placeholder directory
    │   └── round_d1002r1_start.obarc               // Start placeholder for a round
    ├── pieces                                      // Piece placeholder directory
    │   ├── piece_d1002r1p1_start_20230111T193049.obarc // Start placeholder for a piece, piece_destID_roundID_PIECEID_start_DATE
    │   └── piece_d1002r1p1_end_20230111T193249.obarc   // End placeholder for a piece, piece_destID_roundID_PIECEID_end_DATE
    └── piece_d1002r1p1                             // Piece directory. Directory naming format is piece_destID_roundID_PIECEID
        ├── file_list.0.obarc
        ├── piece_d1002r1p1_20230111T193049_20230111T193249.obarc // Records the continuous intervals of the piece
        ├── checkpoint
        ├── single_piece_info.obarc                 // Records the meta information of this piece
        ├── tenant_archive_piece_infos.obarc        // Records the meta information of all frozen pieces before this piece
        ├── file_info.obarc                         // List of all log stream files
        ├── logstream_1                             // Log stream 1
        └── logstream_1001                          // Log stream 1001

In the above log archive directory, the top-level directory contains the following three types of data:

• format.obbak: Records meta information for the archive path, including information about the tenant using the path.

• check_file: Used for connectivity checks of the user log archive directory.

• rounds: A summary list of log archive rounds, recording the list of all rounds.

• pieces: A summary list of log archive pieces, recording the list of all pieces.

• piece_d1002r1p1: A piece directory for log archive. Directory naming format is piece_destID_roundID_PIECEID. Here, DESTID refers to the ID corresponding to log_archive_dest; ROUNDID refers to the ID of the log archive round, which is a monotonically increasing integer; PIECEID refers to the piece_id of the log archive piece, also a monotonically increasing integer.

  A piece directory for log archive contains the following data:

  • file_list.0.obarc: This file records the files and directories contained in the current directory.

  • piece_d1002r1p1_20230111T193049_20230111T193249.obarc: This file displays the ID, start time, and end time of the current piece and is used only for information display.

  • checkpoint: This directory records the archive checkpoints for active pieces. The ObArchiveScheduler module periodically updates the checkpoint information in this directory.

  • single_piece_info.obarc: This file records the metadata of the current piece.

  • tenant_archive_piece_infos.obarc: This file records the metadata of all frozen pieces within the current tenant.

  • file_info.obarc: This file records the list of log streams within a piece.

  • logstream_1: This directory records the log files for log stream 1, which is the system log stream for an OceanBase Database tenant.

  • logstream_1001: This directory records the log files for log stream 1001. Log streams with IDs greater than 1000 are user log streams for an OceanBase Database tenant.

Differences from related features in V3.x/V2.x

Log archiving

Data backup

Physical restore

References

For more detailed information about physical backup and restore, see the Backup and restore chapter.