Restore from a specified path

When a data backup set (backup_set) and log archive (archivelog_piece) are manually moved to another path for business reasons, you can restore the tenant by loading the corresponding backup_set and archivelog_piece and then issuing a restore command.

Prerequisites

• You have obtained the storage paths for the backup set and archive log pieces to be restored.

• The backup set and archive log pieces to be restored belong to the same tenant. Currently, restoring from a backup set and archive log pieces of the same tenant is only allowed to create a new tenant.

• You have completed the pre-restoration preparations. For specific operations, see Prepare before restore.

Procedure

1. Log in to the sys tenant of the cluster where the tenant to be restored is located as the root user.

2. (Optional) Execute the ALTER SYSTEM RESTORE...PREVIEW command to specify the original data backup path, log archive path, and the desired restore time.

   The statement is as follows:

   ALTER SYSTEM RESTORE FROM 'uri' UNTIL { TIME='timestamp' | SCN=scn } PREVIEW;
   

   The relevant parameters are described as follows:

   • uri: Specifies the original data backup path and log archive path, separated by commas.

     • If a backup target path was specified using the TO syntax during data backup (for example, backing up to a specified directory A), then the uri should contain the backup target path specified during backup (A), not the default path configured by the system parameter data_backup_dest. The format remains A,log_archive_dest.
     • If the tenant has performed an archive backup with the DELETE INPUT parameter, the format is A,log_archive_dest,backup_archive_dest.

   • TIME='timestamp' | SCN=scn: Specifies the desired restore timestamp or SCN. When executing this statement, you must explicitly specify a time.

   For complete parameter descriptions, see ALTER SYSTEM - RESTORE PREVIEW.

   Examples are as follows:

   OSS

   NFS

   • Specify the original data backup path and log archive path, and restore to the specified SCN 1712650554000909004.

     obclient [oceanbase]> ALTER SYSTEM RESTORE FROM 'oss://test_bucket/data?host=***&access_id=****&access_key=****, oss://test_bucket/archive?host=***&access_id=****&access_key=****' UNTIL SCN = 1712650554000909004 PREVIEW;
     

   • Specify the original data backup path and log archive path, and restore to the specified timestamp 2024-04-09 16:15:54.

     obclient [oceanbase]> ALTER SYSTEM RESTORE FROM 'oss://test_bucket/data?host=***&access_id=****&access_key=****, oss://test_bucket/archive?host=***&access_id=****&access_key=****' UNTIL TIME = '2024-04-09 16:15:54' PREVIEW;
     

   • Specify the original data backup path and log archive path, and restore to the specified SCN 1712650554000909004.

     obclient [oceanbase]> ALTER SYSTEM RESTORE FROM 'file:///ob_backup/data, file:///ob_backup/archive' UNTIL SCN = 1712650554000909004 PREVIEW;
     

   • Specify the original data backup path and log archive path, and restore to the specified timestamp 2024-04-09 16:15:54.

     obclient [oceanbase]> ALTER SYSTEM RESTORE FROM 'file:///ob_backup/data, file:///ob_backup/archive' UNTIL TIME = '2024-04-09 16:15:54' PREVIEW;
     

3. (Optional) Run the SHOW RESTORE PREVIEW command to display the backup_set and archivelog_piece required to restore to the specified time.

   Notice

   You must run the SHOW RESTORE PREVIEW command after the ALTER SYSTEM RESTORE...PREVIEW command succeeds. Otherwise, the required results cannot be obtained.

   obclient [oceanbase]> SHOW RESTORE PREVIEW;
   

   For example, the result is as follows:

   +--------------+-----------+--------------------------------------------------------------------------------+------------------------------------------------------------------------------+
   | backup_type  | backup_id | backup_dest                                                                    | description                                                                  |
   +--------------+-----------+--------------------------------------------------------------------------------+------------------------------------------------------------------------------+
   | BACKUP_SET   |         1 | file:///ob_backup/data/backup_set_1_full                                       |                                                                              |
   | BACKUP_PIECE |         1 | file:///ob_backup/archive/piece_d1002r1p1                                      | start_scn_display: 20240409T155954, checkpoint_scn_display: 20240409T160154. |
   | BACKUP_PIECE |         2 | file:///ob_backup/archive/piece_d1002r1p2                                      | start_scn_display: 20240409T160154, checkpoint_scn_display: 20240409T160353. |
   | BACKUP_PIECE |         3 | file:///ob_backup/archive/piece_d1002r1p3                                      | start_scn_display: 20240409T160354, checkpoint_scn_display: 20240409T160553. |
   | BACKUP_PIECE |         4 | file:///ob_backup/archive/piece_d1002r1p4                                      | start_scn_display: 20240409T160554, checkpoint_scn_display: 20240409T160754. |
   | BACKUP_PIECE |         5 | file:///ob_backup/archive/piece_d1002r1p5                                      | start_scn_display: 20240409T160754, checkpoint_scn_display: 20240409T160953. |
   | BACKUP_PIECE |         6 | file:///ob_backup/archive/piece_d1002r1p6                                      | start_scn_display: 20240409T160954, checkpoint_scn_display: 20240409T161154. |
   | BACKUP_PIECE |         7 | file:///ob_backup/archive/piece_d1002r1p7                                      | start_scn_display: 20240409T161154, checkpoint_scn_display: 20240409T161354. |
   | BACKUP_PIECE |         8 | file:///ob_backup/archive/piece_d1002r1p8                                      | start_scn_display: 20240409T161354, checkpoint_scn_display: 20240409T161554. |
   +--------------+-----------+--------------------------------------------------------------------------------+------------------------------------------------------------------------------+
   9 rows in set
   

   The query result shows all the backup_set and archivelog_piece required to restore to the specified time, along with their storage paths in the original data backup and log archive destinations. If, due to business needs, you have manually moved some or all of these files to other paths or storage media, you need to maintain the mapping between the original paths and the current paths for each backup_set and archivelog_piece based on your actual situation.

   For example, in the query result above, if you need to use the archivelog_piece with BACKUP_PIECE set to 1 for restoration, but this file has already been manually moved to oss://test_bucket/archive/piece_1, then when using the ADD RESTORE SOURCE command to load the backup path, you need to specify the new storage path oss://test_bucket/archive/piece_1.

4. Run the ADD RESTORE SOURCE command to load the required backup_set and archivelog_piece for restoration.

   The syntax for loading paths is as follows:

   ALTER SYSTEM ADD RESTORE SOURCE 'restore_path';
   

   Usage instructions:

   • restore_path: Enter the path of the backup_set or archivelog_piece to be loaded. This can be one or multiple paths.

     Notice

     If the backup_set or archivelog_piece to be loaded is stored on object storage, the host, access_id, and access_key parameters in the path for each backup_set or archivelog_piece must be the same.

   • This statement can be executed multiple times consecutively within the same session. When executed multiple times in the same session, the system will incrementally add them to the restore source list.

   Example:

   1. Load the backup_set to be restored.

      obclient [oceanbase]> ALTER SYSTEM ADD RESTORE SOURCE 'file:///ob_backup/data/backup_set_1_full';
      

   2. Load the archivelog_piece to be restored.

      obclient [oceanbase]> ALTER SYSTEM ADD RESTORE SOURCE 'file:///ob_backup/archive/piece_d1002r1p1,file:///ob_backup/archive/piece_d1002r1p2';
      

      obclient [oceanbase]> ALTER SYSTEM ADD RESTORE SOURCE 'oss://test_bucket/archive/piece_1?host=***&access_id=x****&access_key=****';
      

5. (Optional) If you load a backup set or archive log piece and find that an incorrect path was entered, you can execute the following statement to undo the previous input and then reload the correct restore path.

   obclient [oceanbase]> ALTER SYSTEM CLEAR RESTORE SOURCE;
   

6. After all paths are successfully loaded, call the restore command.

   Notice

   • The session that executes the restore command must be the same one that executed the ADD RESTORE SOURCE command. If it is not the same session (the original session was interrupted or a new session was used), the previously loaded list of restore sources will be cleared.
   • After executing the ADD RESTORE SOURCE command, you cannot restore a tenant in the same session by specifying the backup destination in a restore command.
   • After executing the restore command, regardless of whether the restore is successful, the previously loaded list of restore sources will be cleared. If you need to call the restore command again, you must reload the required backup sets and archive log pieces.

   Execute the following statement:

   ALTER SYSTEM RESTORE restore_tenant_name [UNTIL {TIME='timestamp' | SCN=scn} ] WITH 'restore_option';
   

   For complete parameter descriptions, see ALTER SYSTEM - RESTORE.

   For detailed descriptions of each parameter, see Parameters related to physical restore.

   An example of calling the restore command is as follows:

   • Restore tenant mysql from the specified path to the specified SCN 1712650554000909004, and specify the resource pool as restore_pool.

     // Full restore
     obclient [oceanbase]> ALTER SYSTEM RESTORE mysql UNTIL SCN = 1712650554000909004 WITH 'pool_list=restore_pool';
     
     // Quick restore
     obclient [oceanbase]> ALTER SYSTEM RESTORE mysql UNTIL SCN = 1712650554000909004 WITH 'pool_list=restore_pool&method=quick';
     

   • Restore tenant mysql from the specified path to the specified timestamp 2024-04-09 16:15:54, and specify the resource pool as restore_pool.

     // Full restore
     obclient [oceanbase]> ALTER SYSTEM RESTORE mysql UNTIL TIME = '2024-04-09 16:15:54' WITH 'pool_list=restore_pool';
     
     // Quick restore
     obclient [oceanbase]> ALTER SYSTEM RESTORE mysql UNTIL TIME = '2024-04-09 16:15:54' WITH 'pool_list=restore_pool&method=quick';
     

What to do next

• After initiating a restore task, you can view the progress and results of the restore through views. For specific operations, see View restore progress.

• After the restore task is completed, if you are restoring from backup data of a lower version to a cluster of a higher version, you also need to upgrade the restored tenant. For specific operations, see Upgrade a tenant after restore.

• The physical restore process is unified with that of a physical standby database. After physical restore, the tenant becomes a standby tenant. Subsequently, this tenant can provide related services as a standby tenant or be promoted to a primary tenant to provide services. For detailed operations on continuing log archiving and replaying logs from the source tenant as a standby tenant, see Replay logs to a standby tenant; for detailed operations on promoting a standby tenant to a primary tenant, see Convert a standby tenant into primary tenant.

References

For more information about restore, see Restore process.