RESTORE|V4.2.5| docs|Distributed Database

RESTORE

Last Updated：2026-02-11 07:43:39 Updated

Purpose

The ALTER SYSTEM RESTORE statement is used to restore data from a tenant backup.

Limitations and considerations

Physical restore in OceanBase Database supports restoring within the same cluster and across different clusters.
Before using the ALTER SYSTEM RESTORE statement for physical restore, please confirm the version of the backup data to be restored. OceanBase Database currently only supports restoring backup data from a lower version to the same version or a higher version, and does not support reverse restore between minor versions within the same version.
Before using the ALTER SYSTEM RESTORE statement for physical restore, please ensure that the required resources for the tenant to be restored have been created. For specific operations on creating resources for the tenant to be restored, please refer to Preparation before restore.
The tenant restored by the ALTER SYSTEM RESTORE statement is by default a standby tenant. If you want to activate the standby tenant as the primary tenant to provide services, you need to execute the ALTER SYSTEM ACTIVATE STANDBY statement. For more information about the ALTER SYSTEM ACTIVATE STANDBY statement, please refer to ACTIVATE STANDBY.

Privilege requirements

Only the root user of the sys tenant (root@sys) can execute the ALTER SYSTEM RESTORE statement.

Syntax

ALTER SYSTEM RESTORE dest_tenant_name FROM uri [ UNTIL {TIME='timestamp' | SCN=scn} ] WITH 'restore_option' [WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'] [DESCRIPTION [=] 'description'];

restore_option:
  pool_list=pool_name[&locality=locality][&primary_zone=zone_name][&concurrency=int_num][&kms_encrypt={true | false}]

Parameters

Parameter	Description
dest_tenant_name	The name of the new tenant to be restored.
uri	The data backup path `backup_data_dest` and log archive path `log_archive_dest` set during backup. This value must include at least one data backup path and one log archive path, separated by commas (,). Currently, OceanBase Database supports the following archive destination media: NFS, Alibaba Cloud OSS, Azure Blob (supported from V4.2.5 BP6 in V4.2.5), AWS S3, and object storage compatible with the S3 protocol, such as Huawei OBS, Google GCS, and Tencent Cloud COS. For examples of `uri` paths, please refer to SET LOG_ARCHIVE_DEST or SET DATA_BACKUP_DEST.
timestamp	The timestamp to restore to, including this `timestamp` point. The `timestamp` must be specified with an equals sign (=). `timestamp` only supports the `YYYY-MM-DD HH24:MI:SS.FF` format, and the fractional part (`FF`) can have 0 to 6 decimal places, allowing for microsecond precision. For more information about how to select `timestamp` and `scn` values during restore, please refer to Parameters related to physical restore.
scn	The SCN to restore to, including this `scn` point. The `scn` must be specified with an equals sign (=).
restore_option	Supports parameters such as `pool_list`, `locality`, `primary_zone`, `concurrency`, and `kms_encrypt`, separated by `&`. When specifying `locality` and `primary_zone`, it is recommended to keep them consistent with the source tenant. If they are inconsistent, load balancing operations may occur when the standby tenant is activated as the primary tenant, affecting performance. `pool_list`: Required. The resource pool to be created for the new tenant to be restored. Multiple resource pools are separated by commas (,). `locality`: Optional. The Locality information for the new tenant's replica distribution, which must match the zone information in the `pool_list` of the cluster where the new tenant resides. When keeping consistency with the source tenant, it is recommended that the number of F replicas for the new tenant be the same as that for the source tenant. If not explicitly specified, the system will default to setting one F replica for each zone in the `zone_list` of the `resource_pool`. Example: `locality='F@z1,F@z2,F@z3'`. `primary_zone`: Optional. The preferred location for the leader replica of the new tenant, which must match the `pool_list` and `locality`, i.e., the zone information must match, and there must be at least two Paxos members in the `primary_region`. When keeping consistency with the source tenant, it is recommended that the number of primary zones with the highest priority for the new tenant be the same as that for the source tenant. If not explicitly specified, the system will randomly distribute the leader replicas across the zones specified in the `zone_list` of the `locality`. Example: `primary_zone='z1'` `concurrency`: Optional. The concurrency level for data restore. If not explicitly specified, the default value is equal to the MAX_CPU value allocated to the tenant. For example, if the system tenant allocates a `MAX_CPU` value of 16 to the tenant to be restored, the default value of `concurrency` is 16 when not explicitly specified. Example: `concurrency=50` `kms_encrypt`: Optional. If set to `true`, it indicates that the `kms_encrypt_info` specified during backup is required for restore.
WITH KEY FROM 'backup_key_path' ENCRYPTED BY 'password'	Specifies the encrypted key backup information for the tenant. This option is required only when the source tenant is configured with transparent encryption. The parameters are as follows: `backup_key_path`: The backup path of the key. `password`: The encryption password set during key backup.
description	Optional. The user-specified description.

Examples

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

Restore the mysql tenant from the NFS data backup path and NFS log archive path to the specified SCN, specify the resource pool as restore_pool.

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

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

obclient [oceanbase]> 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-01 00:00:00' WITH 'pool_list=restore_pool';

Execute the RESTORE command on the target cluster to create and restore a standby tenant using the tenant's backup and archive.

obclient [oceanbase]> 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';