Clone a tenant|V4.3.5| docs|Distributed Database

Clone a tenant

Last Updated：2025-12-18 11:08:33 Updated

By cloning a tenant, you can create a new tenant based on an existing one. The number of units and their distribution across OBServer nodes in the cloned tenant will be exactly the same as those in the source tenant.

Limitations

Cloning a tenant is not allowed during a switchover operation.

For more information about switchover operations, see Switchover.
Cloning a tenant is not allowed while adding or deleting LS, or when LS attributes are being changed.

You can verify this in the system tenant (sys tenant) by running the following statement: SELECT * FROM oceanbase.CDB_OB_BALANCE_JOBS WHERE tenant_id = XXX;
Cloning a tenant is not allowed during a transfer operation.

You can check if there are any ongoing transfer tasks in the system tenant (sys tenant) using: SELECT * FROM oceanbase.CDB_OB_BALANCE_JOBS WHERE tenant_id = XXX;
Cloning a tenant is not allowed during unit migration.

To confirm whether there are any ongoing unit migrations, run the following statement in the system tenant (sys tenant): SELECT * FROM oceanbase.DBA_OB_UNITS WHERE MIGRATE_FROM_SVR_PORT IS NOT NULL;
Cloning a tenant is not allowed while scaling down a tenant by reducing the number of UNIT_NUM in the resource pool.
Cloning is not supported if any OBServer node hosting units in the source tenant is unavailable.
Cloning a tenant is not allowed when there are disaster recovery tasks on log stream replicas.

To check if the current tenant has any ongoing disaster recovery tasks for log stream replicas:
- In the system tenant, query the CDB_OB_LS_REPLICA_TASKS view with the current tenant’s tenant_id. If the result is not empty, it means there are disaster recovery tasks in progress for that tenant.
- In a user tenant, query DBA_OB_LS_REPLICA_TASKS. If the result is not empty, it means there are disaster recovery tasks in progress for that tenant.
Cloning a tenant is not allowed during an upgrade.
Cloning a tenant is not supported for tenants created with OceanBase Database versions earlier than V4.3.0.

Considerations

There is strict data and resource isolation between the cloned tenant and the source tenant. Any changes made to the data in the new tenant will not affect the source tenant, and vice versa; the two tenants will not compete for resources such as CPU and memory.
Initially, the source tenant and the cloned tenant share physical macro blocks. As data is written to each tenant over time, the number of shared macro blocks gradually decreases while the number of exclusive macro blocks increases. This leads to a gradual increase in storage usage, so it’s important to monitor storage space utilization on OBServer nodes.
During the tenant cloning process, the following operations are not allowed:
- Performing a switchover operation on the source tenant
- Scaling in or out the source tenant by changing its UNIT_NUM or adjusting the priority of the primary zone
- Adding, removing, or redistributing replicas for the source tenant
- Manually performing a transfer operation on the source tenant
- Manually migrating units for the source tenant
- Upgrading the source tenant
If you need to perform any of these operations, you can cancel the cloning task first and then proceed. For details on how to cancel a cloning task, see Cancel the tenant cloning task.

Prerequisites

The tenant cloning feature depends on the tenant's log archiving functionality. Before performing a tenant clone operation, make sure that log archiving mode is enabled for the source tenant, and that log archive mode remains enabled throughout the cloning process. For detailed instructions on setting the archive destination and enabling log archiving mode for the source tenant, see Preparation before log archive and Enable archive mode.

Notice

After you enable the log archiving mode for a tenant, you must execute the ALTER SYSTEM MINOR FREEZE TENANT = tenant_name; statement to initiate a minor freeze for the tenant if you want to immediately execute the tenant clone operation. For more information about how to manually trigger a minor freeze, see Manually trigger a minor compaction.

Background information

The tenant cloning feature is suitable for a variety of scenarios, including the following:

When you need to perform data analysis on the data of an online tenant but are concerned that analysis queries may impact the tenant's transactional (TP) workload, you can clone a new tenant from the existing one and perform online data analysis on the cloned tenant.
Before releasing a new version of your application, you can clone a small-sized tenant at the current point in time for the business tenant involved in the application. If any issues arise with the new application version, you can quickly roll back the data.
When you need to perform version testing and validation for your application, you can quickly clone a test tenant from the online tenant and use the test tenant for application testing and validation.
When you need to perform relatively high-risk operations such as DDL on the database, you can:
- Quickly clone a test tenant from the online tenant, run the required DDL statements on the test tenant, and validate the results.
- Clone a small-sized tenant from the online tenant at the current point in time before executing the DDL statements. If any issues occur during the execution of the DDL statements, you can quickly roll back the data.

Procedure

obclient -h172.30.xx.xx -P2883 -uroot@sys#cluster -p**** -A

Execute the following statement to clone a tenant.
```
CREATE TENANT new_tenant_name FROM source_tenant_name 
   WITH
   RESOURCE_POOL [=] resource_pool_name,
   UNIT [=] unit_config;
```
The parameters are described as follows:
- new_tenant_name: the name of the new tenant to be cloned. You can clone only one tenant at a time. If you want to clone multiple tenants, you need to wait until the cloning task of one tenant is completed before you can clone another tenant.
- source_tenant_name: the name of the source tenant.
- resource_pool_name: the name of the resource pool for the new tenant to be cloned. When you clone a tenant, the system automatically creates a resource pool for the new tenant based on the resource distribution of the source tenant.
- unit_config: the unit specification for the new tenant to be cloned. You can specify an existing unit specification in the system or create a new one. For more information about how to query existing unit specifications, see View resource specifications.
The following example shows how to clone a tenant named mysql to a new tenant named clone_tnt.
```
obclient [oceanbase]> CREATE TENANT clone_tnt FROM mysql
	 WITH
   RESOURCE_POOL = clone_tnt_pool,
	 UNIT= S1_unit_config;
```
In this example, the new tenant is named clone_tnt, and the resource pool is named clone_tnt_pool. The unit specification is S1_unit_config. The number of units and their distribution across OBServer nodes are the same as those of the source tenant.

During the cloning process, you can view the status of the cloning task by querying views.

View the status of a running cloning task

obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_CLONE_PROGRESS\G

The query result is as follows:

*************************** 1. row ***************************
        CLONE_JOB_ID: 1702211800546509768
            TRACE_ID: YA4740B7C050F-00060C210F4A4848-0-0
    SOURCE_TENANT_ID: 1004
  SOURCE_TENANT_NAME: mysql
     CLONE_TENANT_ID: 1016
   CLONE_TENANT_NAME: clone_tnt
  TENANT_SNAPSHOT_ID: 1702211800802135214
TENANT_SNAPSHOT_NAME: _inner_snapshot$1702211800702058206
    RESOURCE_POOL_ID: 1008
  RESOURCE_POOL_NAME: clone_tnt_pool
    UNIT_CONFIG_NAME: S1_unit_config
         RESTORE_SCN: 1702211802014048020
              STATUS: CLONE_SYS_CREATE_TENANT
      CLONE_JOB_TYPE: FORK
    CLONE_START_TIME: 2023-12-10 20:36:40.551169
 CLONE_FINISHED_TIME: NULL
            RET_CODE: NULL
       ERROR_MESSAGE: NULL
1 row in set

View the history of cloning tasks

obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_CLONE_HISTORY\G