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

Clone a tenant

Last Updated：2024-04-19 08:42:49 Updated

You can create a tenant by cloning a specified tenant. The number of units and unit distribution on OBServer nodes are the same for the new tenant and the source tenant.

Limitations

You cannot clone a standby tenant.
You cannot clone a tenant during switchover.

For more information about the switchover, see Switchover.
You cannot clone a tenant when you add an LS, delete an LS, or modify LS attributes.
You cannot clone a tenant during partition transfer.
You cannot clone a tenant during unit migration.
You cannot clone a tenant when you scale in the tenant by reducing the number of units in the resource pool.
You cannot clone a tenant when any unit used by the tenant resides on an unavailable OBServer node.
You cannot clone a tenant when the log stream replica is used in a disaster recovery task.

You can determine whether the log stream replica of the current tenant is used in a disaster recovery task as follows:
- If you are logged on to the sys tenant, specify tenant_id and query the CDB_OB_LS_REPLICA_TASKS view. If the query result is not empty, a disaster recovery task is being executed in the tenant.
- If you are logged on to a user tenant, you can query the DBA_OB_LS_REPLICA_TASKS view. If the query result is not empty, a disaster recovery task is being executed in the tenant.
You cannot clone a tenant during an upgrade.
You cannot clone a tenant in OceanBase Database earlier than V4.3.0.

Considerations

Data and resources are isolated between the new tenant and the source tenant. Data changes in the new tenant will not affect the source tenant, and data changes in the source tenant will not affect the new tenant. The new tenant and the source tenant will not contend for CPU and memory resources.
The source tenant and the new tenant use shared physical macroblocks in the initial state. As data is respectively written to the two tenants, they are going to share fewer macroblocks but exclusively occupy more macroblocks, and the usage of storage space also gradually increases. You must monitor the usage of storage space on OBServer nodes.
You cannot perform the following operations when a tenant cloning job is being executed:
- Perform switchover on the source tenant.
- Scale in or scale out the source tenant by changing the number of units or modifying the top priority of the primary zone for the source tenant.
- Add replicas, remove replicas, or adjust replica distribution for the source tenant.
- Transfer partitions for the source tenant.
- Migrate units for the source tenant.
- Upgrade the source tenant.
If you want to perform the preceding operations, you must cancel the tenant cloning job first. For more information about how to cancel a tenant cloning job, see Cancel tenant cloning.

Prerequisites

The tenant cloning feature depends on the log archiving feature for tenants. Before you clone a tenant, make sure that log archiving is enabled for the source tenant. During tenant cloning, do not disable log archiving for the source tenant. For more information about how to specify the archive destination and enable log archiving for the source tenant, see Preparations and Enable ARCHIVELOG.

Notice

If you want to immediately clone a tenant after you enable log archiving for the tenant, you must execute the ALTER SYSTEM MINOR FREEZE TENANT = tenant_name; statement to initiate a minor compaction for the tenant. For more information, see Manually initiate a minor compaction.

Background information

Tenant cloning is applicable to various scenarios, some of which are as follows:

If you want to analyze the data of an online tenant but are worried that the data analysis statement may affect the TP load of online data, you can create a tenant by cloning the tenant, and analyze online data in the new tenant.
Before you release a new version for your application, you can create a small-scale tenant at the current point in time by cloning the business tenant involved in the application. If an error occurs in the newly released application version, you can quickly roll back the data.
If you want to test and verify an application version, you can create a test tenant by cloning the online tenant and use the test tenant for testing and verification.
If you need to perform high-risk operations, such as DDL operations, on the database, you can:
- Create a test tenant by cloning the online tenant, execute the DDL statements in the test tenant, and verify the execution result.
- Before you execute the DDL statements, create a small-scale tenant at the current point in time by cloning the online tenant. If an error occurs during the execution of the DDL statements, you can quickly roll back the data.

Procedure

Log on to the sys tenant of the cluster as the root user.

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;
```
where
- new_tenant_name specifies the name of the new tenant. You can create only one tenant in a cloning job. If you want to create multiple tenants, you can initiate another cloning job after the current one is completed.
- source_tenant_name specifies the name of the source tenant.
- resource_pool_name specifies the name of the resource pool for the new tenant. 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 specifies the unit config for the new tenant. You can specify an existing unit config or create a unit config based on your business needs. For more information about how to query existing unit configs in the system, see Query unit configs.
The following example creates a tenant named clone_tnt by cloning the tenant mysql:
```
obclient [oceanbase]> CREATE TENANT clone_tnt FROM mysql
	 WITH
   RESOURCE_POOL = clone_tnt_pool,
	 UNIT= S1_unit_config;
```
In this example, the resource pool for the new tenant is clone_tnt_pool, and the unit config is S1_unit_config. The number of units and unit distribution on OBServer nodes are the same for the new tenant and the source tenant.

Query the status of cloning jobs from a view.

Query ongoing cloning jobs

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

Query historical cloning jobs

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