RESTORE|V4.2.0| docs|Distributed Database

RESTORE

Last Updated：2025-12-03 11:18:03 Updated

Description

This statement is used to restore the backup data of a tenant.

Note

Only the data blocks are restored in a tenant-level snapshot backup, and not the clogs.
Only the root user of the sys tenant can initiate a tenant-level backup restore.

Syntax

alter_system_restore_stmt:
    ALTER SYSTEM restore_action;

restore_action:
  /* Restore data to the specified timestamp */
  RESTORE dest_tenant_name FROM uri UNTIL TIME='timestamp' WITH 'restore_option' [WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'] [DESCRIPTION description];

  /* Restore data to the specified SCN */
  RESTORE dest_tenant_name FROM uri UNTIL SCN=scn WITH 'restore_option' [WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'] [DESCRIPTION description];

  /* Restore data to the latest checkpoint */
  RESTORE dest_tenant_name FROM uri WITH 'restore_option' [WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'] [DESCRIPTION description];

 /* Restore the required macroblocks from the full backup and incremental backup to the restore tenant, and synchronize and apply the transaction logs. */
  RESTORE tenant_name FROM restore_path UNTIL restore_checkpoint
         WITH 'pool_list=<pool_name>&primary_zone=<zone_name>';

 /* Cancel an ongoing tenant restore */
  CANCEL RESTORE dest_tenant_name;

Parameter explanation

Parameter	Description
dest_tenant_name	The name of the tenant to restore or unrestore.
uri	The data backup path `backup_data_dest` and log archive path `log_archive_dest` set during backup. This parameter value contains at least one data backup path and one log archive path, which are separated with `,`.
timestamp	The timestamp to restore to. The restore is performed up to this timestamp, and the `timestamp` parameter is included in the restore scope. The `timestamp` parameter must be specified with `=`. The `timestamp` parameter supports only the `YYYY-MM-DD HH24:MI:SS.FF` format, and the value is precise to the nanosecond.
scn	The SCN to restore to. The restore is performed up to this SCN, and the `scn` parameter is included in the restore scope. The `scn` parameter must be specified with `=`.
restore_option	Allows you to specify `pool_list`, `locality`, `primary_zone`, `concurrency`, and `kms_encrypt`. The parameters are separated with `&`. We recommend that you specify `locality` and `primary_zone` to be consistent with the source tenant. If they are inconsistent, activating the restored tenant as the primary tenant may cause load balancing operations after restoration, which affects the performance. `pool_list`: Required. It specifies the resource pools created for the new tenant. Multiple resource pools are separated with commas (,). `locality`: Optional. It specifies the locality information of the replicas of the new tenant. The locality information must be consistent with the zone information in `pool_list` of the cluster where the new tenant resides. We recommend that you specify `locality` to keep the same number of full-featured (F) replicas as the source tenant. If you do not specify this parameter, the system will set up an F replica in each zone based on the `zone_list` in `resource_pool`. The locality information is in the format of `locality='F@z1,F@z2,F@z3'`. `primary_zone`: Optional. It specifies the preferred zone of the leader replica of the new tenant. The specified zone must be included in `pool_list` and `locality`, namely, the zone information must match and there must be at least two Paxos members in the `primary_region`. We recommend that you specify `primary_zone` to keep the same number of primary zones as the source tenant. If you do not specify this parameter, the system will randomly distribute the leader replicas in the zones specified in `locality`. The primary zone is in the format of `primary_zone='z1'`. `concurrency`: Optional. It specifies the degree of concurrency of data restore. If you do not specify this parameter, the default value, which is equal to the maximum number of CPU cores allocated to the tenant, is used. The example format is `concurrency=50`. `kms_encrypt`: Optional. If set to `true`, the tenant key specified in `kms_encrypt_info` is required during restore. The default value is `false`.
WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'	The secret key backup information of the tenant to be restored. This parameter is required only when the source tenant is configured with transparent encryption. In this case, the parameters `backup_key_path` and `password` are required. `backup_key_path`: The backup path of the secret key. `password`: The encryption password set during secret key backup.
description	The description information specified by the user. This parameter is optional.
tenant_name	The name of the new tenant.
restore_path	The destination for backup.
restore_checkpoint	The time point to restore to.
pool_list	The list of resource pools.
primary_zone	The primary cluster.

Examples

Restore the mysql tenant to the specified timestamp 2022-06-1 00:00:00 from the NFS data backup path and the NFS log archive path. Specify the resource pool as restore_pool, the replica locality as F@z1,F@z2,F@z3, and the primary_zone as z1.
```
obclient> ALTER SYSTEM RESTORE mysql FROM 'file:///data/nfs/backup/data,file:///data/nfs/backup/archive' UNTIL TIME='2022-06-1 00:00:00' WITH 'pool_list=restore_pool&locality=F@z1,F@z2,F@z3&primary_zone=z1';
```
Restore the mysql tenant to the latest archive point, using the data backup path and the log archive path. Specify the resource pool as restore_pool.
```
obclient> ALTER SYSTEM RESTORE mysql FROM 'file:///data/nfs/backup/data,file:///data/nfs/backup/archive' WITH 'pool_list=restore_pool';
```

Restore the mysql tenant to the specified SCN, using the data backup path and the log archive path. Specify the resource pool as restore_pool.

obclient> ALTER SYSTEM RESTORE mysql FROM 'file:///data/nfs/backup/data,file:///data/nfs/backup/archive' UNTIL SCN='xxxxxxxx' WITH 'pool_list=restore_pool';

Restore the mysql tenant to the specified timestamp 2022-06-1 00:00:00 from the OSS data backup path and the OSS log archive path. Specify the resource pool as restore_pool.

obclient> ALTER SYSTEM RESTORE mysql FROM 'oss://oceanbase-test-bucket/backup/data/?host=xxx.aliyun-inc.com&access_id=xxx&access_key=xxx,oss://oceanbase-test-bucket/backup/archive/?host=xxx.aliyun-inc.com&access_id=xxx&access_key=xxx' UNTIL TIME='2022-06-1 00:00:00' WITH 'pool_list=restore_pool';

In the target cluster, execute the RESTORE statement to create a restore tenant and restore the data and logs of the tenant.

obclient> ALTER SYSTEM RESTORE restore_oracle_tenant FROM 'file:///data/nfs/backup//ob_backup_oracle_tenant/archive,file:///data/nfs/backup//ob_backup_oracle_tenant/data' UNTIL TIME='2022-11-11 15:04:23.825558' with 'pool_list=small_pool_2&primary_zone=z1';
Query OK, 0 rows affected

Cancel the ongoing restore operation of the mysql tenant.

obclient> ALTER SYSTEM CANCEL RESTORE mysql;
Query OK, 0 rows affected