Tenant scaling in and out aim to improve or reduce the service capabilities of the tenant, including the computing and storage capacities. To meet this purpose, you can improve the service capabilities of a single node or add service nodes. This topic describes how to modify the unit number to increase or decrease service nodes to improve or reduce the overall service capabilities of a tenant, thereby implementing tenant scaling in and out.
Modifying the unit number includes increasing or decreasing the unit number.
Background information
In the current version, OceanBase Database supports homogeneous zone mode and heterogeneous zone mode for tenants:
In homogeneous zone mode, the
UNIT_NUMof each zone in a tenant must be the same. To facilitate unified management of units across zones, the system introduces the unit group mechanism. units with the sameUNIT_GROUP_IDacross different zones belong to the same unit group. For tenants in homogeneous zone mode, increasing or decreasing the unit number is essentially creating or deleting units by unit group.In heterogeneous zone mode, the
UNIT_NUMof each zone in a tenant can be the same or different, but a tenant can have at most two differentUNIT_NUMvalues across all zones. Log stream distribution is no longer bound to unit groups, and replicas in each zone no longer need to be limited to symmetric units. For tenants in heterogeneous zone mode, in addition to uniformly increasing or decreasing the tenant's unit number, if there are multiple resource pools, you can also separately increase or decrease the unit number of a specific resource pool of the tenant to achieve resource-pool-level scale-in and scaling out.
Notice
Typically, for existing tenants or tenants upgraded from earlier versions, the default mode is homogeneous zone mode. To enable heterogeneous zone mode, you need to set the tenant-level parameter zone_deploy_mode to hetero (heterogeneous zone mode). After the modification, switching back to homo (homogeneous zone mode) is not supported.
Prerequisites
Before you perform a scale-in or scaling out operation on a tenant, you must perform the following steps:
Enable load balancing for the tenant.
The load balancing strategy for a tenant is jointly controlled by the tenant-level parameters
enable_rebalanceandenable_transfer.You can specify the
enable_rebalanceparameter in thesystenant to control whether to enable load balancing among tenants, and specify this parameter in a user tenant to control whether to enable intra-tenant load balancing. When performing scale-in or scaling out operations on a tenant, you must enable intra-tenant load balancing. For more information about inter-tenant load balancing and intra-tenant load balancing, see Best practices for data load balancing. The default value istrue, which means load balancing is enabled. The setting takes effect immediately without the need to restart the OBServer node.You can specify the
enable_transferparameter to control whether to enable the transfer feature for a tenant. The default value istrue, which means the transfer feature is enabled. The setting takes effect immediately without the need to restart the OBServer node.If the value of
enable_rebalanceisfalse, the system does not perform automatic load balancing regardless of whether the value ofenable_transferistrueorfalse.If the value of
enable_rebalanceistrueand the value ofenable_transferistrue, the system automatically adjusts partition distribution to achieve load balancing during a tenant scaling operation.If the value of
enable_rebalanceistrueand the value ofenable_transferisfalse, the system cannot initiate transfer operations during tenant scaling, but can implement limited load balancing through log stream migration.
You can enable load balancing for a tenant in the following ways:
Enable load balancing for a specified tenant from the
systenantEnable intra-tenant load balancing and the transfer feature for a specified tenant from the
systenantALTER SYSTEM SET enable_rebalance = true TENANT = 'tenant_name';ALTER SYSTEM SET enable_transfer = true TENANT = 'tenant_name';These statements set the values of the
enable_rebalanceandenable_transferparameters totrueonly for the specified tenant.Enable intra-tenant load balancing and the transfer feature for all user tenants (excluding the
systenant and Meta tenants) from thesystenantALTER SYSTEM SET enable_rebalance = true TENANT = all_user;ALTER SYSTEM SET enable_transfer = true TENANT = all_user;or
ALTER SYSTEM SET enable_rebalance = true TENANT = all;ALTER SYSTEM SET enable_transfer = true TENANT = all;These statements set the values of the
enable_rebalanceandenable_transferparameters totruefor all user tenants.Note
Starting from OceanBase Database V4.2.1,
TENANT = all_userandTENANT = allexpress the same semantics. If you want an operation to take effect on all user tenants, we recommend that you useTENANT = all_user.TENANT = allwill be deprecated.
Enable load balancing for a user tenant from the current tenant
MySQL-compatible modeOracle-compatible modeYou can execute the following statements to enable intra-tenant load balancing and the transfer feature for the current MySQL-compatible tenant:
ALTER SYSTEM SET enable_rebalance = true;ALTER SYSTEM SET enable_transfer = true;You can execute the following statements to enable intra-tenant load balancing and the transfer feature for the current Oracle-compatible tenant:
ALTER SYSTEM SET enable_rebalance = 'true';ALTER SYSTEM SET enable_transfer = 'true';
For more information about the
enable_rebalanceandenable_transferparameters, see enable_rebalance and enable_transfer, respectively.Before scaling out, if a tenant is deleted, we recommend that you also drop the resource pool corresponding to the tenant to release resources, because idle resource pools are also considered occupied resources.
For more information about how to drop a resource pool, see Drop a resource pool.
Before tenant scaling in, we recommend that you perform a minor compaction to release the memory resources used by the tenant.
For more information about how to manually initiate a minor compaction, see Manually initiate a minor compaction.
Before you perform a scale-in or scaling out operation on a tenant, we recommend that you plan resources for the tenant to achieve better results.
For more information, see Resource planning for tenant scaling in and out.
Considerations
When adjusting the unit number for tenant scaling in and out, note the following:
Do not modify the tenant's locality during the scaling process.
Do not expand the
ZONE_LISTof the tenant's resource pool during the scaling process.Do not add new resource pools to the tenant during the scaling process.
Do not merge resource pools during the scaling process.
Do not perform migration operations on units in the
DELETINGstate during the scaling process.
Increase the unit number
Increase the unit number for all resource pools of a tenant
For tenants in homogeneous zone mode or heterogeneous zone mode, you can use the ALTER RESOURCE TENANT statement to uniformly increase the unit number for all resource pools of a tenant. The following example describes how to increase the unit number for all resource pools of the mysql001 tenant.
Log in to the
systenant of the cluster as therootuser.obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -AAccess the database named
oceanbase.obclient(root@sys)[(none)]> use oceanbase;View the information about the
mysql001tenant to obtain itsTENANT_ID.obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY, TENANT_ROLE, UNIT_NUM, ZONE_UNIT_NUM_LIST FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';The query result is as follows:
+-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | TENANT_ROLE | UNIT_NUM | ZONE_UNIT_NUM_LIST | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | 1006 | mysql001 | USER | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | PRIMARY | 1 | zone1:1,zone2:1,zone3:1 | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+
1 row in set
In the query result, the `TENANT_ID` of the tenant is 1006, and the unit number of the tenant in each zone is 1:1:1.
4. View the units of the `mysql001` tenant.
```shell
obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;
The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+
| UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID |
+---------+-----------+--------+------------------+---------------+-------+----------------+
| 1013 | 1006 | ACTIVE | 1002 | 1023 | zone2 | 1001 |
| 1014 | 1006 | ACTIVE | 1001 | 1023 | zone1 | 1001 |
| 1015 | 1006 | ACTIVE | 1003 | 1023 | zone3 | 1001 |
+---------+-----------+--------+------------------+---------------+-------+----------------+
3 rows in set
According to the query result, the mysql001 tenant has one unit in each zone, and the three units share the same UNIT_GROUP_ID.
Change the value of
UNIT_NUMto2for themysql001tenant.obclient(root@sys)[oceanbase]> ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2;After the command is successfully executed, view the current status of units.
obclient> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1013 | 1006 | ACTIVE | 1002 | 1024 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1024 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1024 | zone3 | 1001 | | 1025 | 1006 | ADDING | 1001 | 1025 | zone1 | 1001 | | 1026 | 1006 | ADDING | 1002 | 1025 | zone2 | 1001 | | 1027 | 1006 | ADDING | 1003 | 1025 | zone3 | 1001 | +---------+-----------+--------+------------------+---------------+-------+----------------+
6 rows in set
You can see that the units to be added are in the `ADDING` state. After internal balancing is complete, the unit status will change from `ADDING` to `ACTIVE`.
<main id="notice" type='notice'>
<h4>Notice</h4>
<ul><li>In earlier versions of OceanBase Database, <code>UNIT_NUM</code> scaling out was a synchronous process. In the current version, <code>UNIT_NUM</code> scaling out is an asynchronous process, and the units to be added are in the <code>ADDING</code> state.</li>
<li>Rollback is supported during the scaling out process (when the units to be added are still in the <code>ADDING</code> state).<p>For example, in this example, you can execute <code>ALTER RESOURCE TENANT mysql001 UNIT_NUM = 1;</code> to restore <code>UNIT_NUM</code> to its original value. During rollback, units that were in the <code>ADDING</code> state directly change to the <code>DELETING</code> state. Note that when performing a rollback, you cannot roll back by deleting a specified UNIT_GROUP. The system automatically selects units in the <code>ADDING</code> state for deletion.</p></li>
<li>Before the scaling out process ends, only rollback is allowed. Modifying <code>UNIT_NUM</code> to other values is prohibited.</li></ul>
</main>
7. View the execution status of the job for increasing the unit number.
```shell
obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_RESOURCE_TENANT_UNIT_NUM' AND TENANT_ID = 1006;
The query result is as follows:
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
| JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT |
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
| 26 | ALTER_RESOURCE_TENANT_UNIT_NUM | SUCCESS | 0 | 100 | 2025-06-18 10:10:19.430962 | 2025-06-18 10:10:54.229794 | 1006 | ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2 | new unit num: '2' | 6.xx.xxx.xxx | 29700 |
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
1 row in set
In the query result, find the corresponding job record based on the following fields:
START_TIME: the time when the job was initiated.SQL_TEXT: the SQL statement corresponding to the job.EXTRA_INFO: the unit number before and after the change.
If the value of JOB_STATUS in the corresponding job record is SUCCESS, the job for increasing the unit number is successfully executed.
For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.
View the units of the
mysql001tenant after the modification.obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1013 | 1006 | ACTIVE | 1002 | 1024 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1024 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1024 | zone3 | 1001 | | 1025 | 1006 | ACTIVE | 1001 | 1025 | zone1 | 1001 | | 1026 | 1006 | ACTIVE | 1002 | 1025 | zone2 | 1001 | | 1027 | 1006 | ACTIVE | 1003 | 1025 | zone3 | 1001 | +---------+-----------+--------+------------------+---------------+-------+----------------+
6 rows in set
Through the above example, the unit number for all resource pools of the `mysql001` tenant is changed from 1 to 2. Before the change, the tenant had one unit in each zone. After the change, the tenant has two units in each zone, thereby implementing tenant scaling out.
### Increase the unit number for a single resource pool of a tenant
For tenants in heterogeneous zone mode, if there are multiple resource pools, you can also use the `ALTER RESOURCE POOL` statement to separately increase the unit number of a specific resource pool of the tenant. Tenants in homogeneous zone mode do not support this method.
The following example describes how to increase the unit number of the `pool2` resource pool of the `mysql001` tenant.
1. Log in to the `sys` tenant of the cluster as the `root` user.
```shell
obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -A
Access the database named
oceanbase.obclient(root@sys)[(none)]> use oceanbase;View the information about the
mysql001tenant to obtain itsTENANT_ID.obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY, TENANT_ROLE, UNIT_NUM, ZONE_UNIT_NUM_LIST FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';The query result is as follows:
+-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | TENANT_ROLE | UNIT_NUM | ZONE_UNIT_NUM_LIST | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | 1006 | mysql001 | USER | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | PRIMARY | 2 | zone1:2,zone2:2,zone3:2 | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+
1 row in set
In the query result, the `TENANT_ID` of the tenant is 1006, and the unit number of the tenant in each zone is 2:2:2.
4. View the current resource configuration of the tenant.
```shell
obclient(root@sys)[oceanbase]> SELECT c.TENANT_ID, e.TENANT_NAME, concat(c.NAME, ': ', d.NAME) `pool:conf`,c.ZONE_LIST, concat(c.UNIT_COUNT, ' unit: ', d.min_cpu, 'C/', ROUND(d.MEMORY_SIZE/1024/1024/1024,0), "G") unit_info
FROM oceanbase.DBA_OB_RESOURCE_POOLS c, oceanbase.DBA_OB_UNIT_CONFIGS d, oceanbase.DBA_OB_TENANTS e
WHERE c.UNIT_CONFIG_ID=d.UNIT_CONFIG_ID AND c.TENANT_ID=e.TENANT_ID AND c.TENANT_ID=1006;
The query result is as follows:
+-----------+-------------+------------------+-----------+---------------+
| TENANT_ID | TENANT_NAME | pool:conf | ZONE_LIST | unit_info |
+-----------+-------------+------------------+-----------+---------------+
| 1006 | mysql001 | pool3: test_unit | zone3 | 2 unit: 1C/8G |
| 1006 | mysql001 | pool2: test_unit | zone2 | 2 unit: 1C/8G |
| 1006 | mysql001 | pool1: test_unit | zone1 | 2 unit: 1C/8G |
+-----------+-------------+------------------+-----------+---------------+
3 rows in set
According to the query result, the mysql001 tenant has three resource pools: pool1, pool2, and pool3, distributed on zone1, zone2, and zone3 respectively.
According to your requirements, change the
UNIT_NUMof thepool2resource pool of themysql001tenant to 3.obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 3;After the command is successfully executed, view the current status of units.
obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1013 | 1006 | ACTIVE | 1002 | 1026 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1024 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1024 | zone3 | 1001 | | 1025 | 1006 | ACTIVE | 1001 | 1025 | zone1 | 1001 | | 1026 | 1006 | ACTIVE | 1002 | 1027 | zone2 | 1001 | | 1027 | 1006 | ACTIVE | 1003 | 1025 | zone3 | 1001 | | 1028 | 1006 | ADDING | 1002 | 1028 | zone2 | 1001 | +---------+-----------+--------+------------------+---------------+-------+----------------+
7 rows in set
You can see that the unit to be added is in the `ADDING` state. After internal balancing is complete, the unit status will change from `ADDING` to `ACTIVE`.
<main id="notice" type='notice'>
<h4>Notice</h4>
<ul><li>In earlier versions of OceanBase Database, <code>UNIT_NUM</code> scaling out was a synchronous process. In the current version, <code>UNIT_NUM</code> scaling out has been changed to an asynchronous process, and the units to be added are in the <code>ADDING</code> state.</li>
<li>Rollback is supported during the scaling out process (when the units to be added are still in the <code>ADDING</code> state).<p>For example, in this example, you can execute <code>ALTER RESOURCE POOL pool2 UNIT_NUM = 2;</code> to restore <code>UNIT_NUM</code> to its original value. During rollback, units that were in the <code>ADDING</code> state directly change to the <code>DELETING</code> state. Note that when performing a rollback, you cannot roll back by deleting a specified unit. The system automatically selects units in the <code>ADDING</code> state for deletion.</p></li>
<li>Before the scaling out process ends, only rollback is allowed. Modifying <code>UNIT_NUM</code> to other values is prohibited.</li></ul>
</main>
7. View the execution status of the job for increasing the unit number.
```shell
obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_RESOURCE_TENANT_UNIT_NUM' AND TENANT_ID=1006;
The query result is as follows:
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
| JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT |
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
| 27 | ALTER_RESOURCE_TENANT_UNIT_NUM | INPROGRESS | NULL | 0 | 2025-06-18 11:02:52.005261 | 2025-06-18 11:02:52.005261 | 1006 | ALTER RESOURCE POOL pool2 UNIT_NUM = 3 | new unit num: '3' | 6.xx.xxx.xxx | 29700 |
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
1 row in set
In the query result, find the corresponding job record based on the following fields:
START_TIME: the time when the job was initiated.SQL_TEXT: the SQL statement corresponding to the job.EXTRA_INFO: the unit number before and after the change.
If the value of JOB_STATUS in the corresponding job record is SUCCESS, the job for increasing the unit number is successfully executed.
For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.
View the units of the
mysql001tenant after the modification.obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1013 | 1006 | ACTIVE | 1002 | 1026 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1024 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1024 | zone3 | 1001 | | 1025 | 1006 | ACTIVE | 1001 | 1025 | zone1 | 1001 | | 1026 | 1006 | ACTIVE | 1002 | 1027 | zone2 | 1001 | | 1027 | 1006 | ACTIVE | 1003 | 1025 | zone3 | 1001 | | 1028 | 1006 | ADDING | 1002 | 1028 | zone2 | 1001 | +---------+-----------+--------+------------------+---------------+-------+----------------+
7 rows in set
Through the above example, the unit number of the `pool2` resource pool of the `mysql001` tenant is changed from 2 to 3. Before the change, the tenant had two units in each zone. After the change, the tenant still has two units in `zone1` and `zone3`, but has three units in `zone2`, thereby implementing tenant scaling out.
## Decrease the unit number
### Considerations
Before decreasing the unit number of a tenant, confirm whether GTS standalone is enabled. The GTS standalone feature is controlled by the tenant-level parameter [enable_gts_standalone](../../../../700.reference/800.configuration-items-and-system-variables/100.system-configuration-items/400.tenant-level-configuration-items/2550.enable_gts_standalone.md). The default value is `False`, which means it is disabled.
If GTS standalone is enabled, note the following:
* After GTS standalone is enabled, the `UNIT_NUM` of each zone in the tenant must be greater than or equal to 2. If you scale in any zone of the tenant to `UNIT_NUM` less than 2, the system will report an error.
* When decreasing the unit number by deleting a specified UNIT_LIST or unit group, you cannot specify the deletion of the unit or unit group used by GTS standalone. Otherwise, the system will report an error.
### Decrease the unit number for all resource pools of a tenant
For tenants in homogeneous zone mode or heterogeneous zone mode, you can use the `ALTER RESOURCE TENANT` statement to uniformly decrease the unit number for all resource pools of a tenant. The following example describes how to decrease the unit number for all resource pools of the `mysql001` tenant.
The following example describes how to decrease the unit number for the `mysql001` tenant.
1. Log in to the `sys` tenant of the cluster as the `root` user.
```shell
obclient -h172.xxx.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -A
Access the database named
oceanbase.obclient(root@sys)[(none)]> use oceanbase;View the information about the
mysql001tenant to obtain itsTENANT_ID.obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY, TENANT_ROLE, UNIT_NUM, ZONE_UNIT_NUM_LIST FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';The query result is as follows:
+-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | TENANT_ROLE | UNIT_NUM | ZONE_UNIT_NUM_LIST | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | 1006 | mysql001 | USER | zone1;zone2,zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | PRIMARY | 3 | zone1:3,zone2:3,zone3:3 | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ 1 row in setIn the query result, the
TENANT_IDof the tenant is 1006, and the unit number of the tenant in each zone is 3.View the units of the
mysql001tenant.obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1001 | 1006 | ACTIVE | 1001 | 1018 | zone1 | 1001 | | 1005 | 1006 | ACTIVE | 1003 | 1018 | zone3 | 1001 | | 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 | | 1007 | 1006 | ACTIVE | 1002 | 1018 | zone2 | 1001 | | 1011 | 1006 | ACTIVE | 1002 | 1019 | zone2 | 1001 | | 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 | | 1013 | 1006 | ACTIVE | 1002 | 1020 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 | +---------+-----------+--------+------------------+---------------+-------+----------------+
9 rows in set
According to the query result, the `mysql001` tenant has three units in each zone. The units with `UNIT_ID` 1001, 1005, and 1007 share the same `UNIT_GROUP_ID` of 1018; the units with `UNIT_ID` 1006, 1011, and 1012 share the same `UNIT_GROUP_ID` of 1019; the units with `UNIT_ID` 1013, 1014, and 1015 share the same `UNIT_GROUP_ID` of 1020.
5. Change the value of `UNIT_NUM` to `2` for the `mysql001` tenant.
* Decrease the `UNIT_NUM` by randomly deleting units.
For tenants in homogeneous zone mode or heterogeneous zone mode, you can use the following statement to decrease the `UNIT_NUM`:
```shell
obclient(root@sys)[oceanbase]> ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2;
```
After this statement is executed:
* For tenants in homogeneous zone mode, for example, in this example, when the `UNIT_NUM` of all resource pools of the tenant is changed from 3 to 2, the system randomly specifies a unit group with the same `UNIT_GROUP_ID` for deletion.
* For tenants in heterogeneous zone mode, the system randomly selects a set of UNIT_LIST for deletion.
* Decrease the `UNIT_NUM` by deleting a specified `UNIT_GROUP`.
For tenants in homogeneous zone mode, you can also use the following statement to decrease the `UNIT_NUM`. Tenants in heterogeneous zone mode do not support this statement.
```shell
obclient(root@sys)[oceanbase]> ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2 DELETE UNIT_GROUP =(1018);
```
After this statement is executed, for a scenario where each zone has three units, the system redistributes the data on the specified unit group to other unit groups, and then deletes the unit group.
6. After the command is successfully executed, view the current status of units.
```shell
obclient> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;
An example of the query result is as follows:
+---------+-----------+----------+------------------+---------------+-------+----------------+
| UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID |
+---------+-----------+----------+------------------+---------------+-------+----------------+
| 1001 | 1006 | DELETING | 1001 | 1018 | zone1 | 1001 |
| 1005 | 1006 | DELETING | 1003 | 1018 | zone3 | 1001 |
| 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 |
| 1007 | 1006 | DELETING | 1002 | 1018 | zone2 | 1001 |
| 1011 | 1006 | ACTIVE | 1002 | 1019 | zone2 | 1001 |
| 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 |
| 1013 | 1006 | ACTIVE | 1002 | 1020 | zone2 | 1001 |
| 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 |
| 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 |
+---------+-----------+----------+------------------+---------------+-------+----------------+
9 rows in set
You can see that the units to be deleted are in the DELETING state.
Notice
- In OceanBase Database,
UNIT_NUMscaling in is an asynchronous process. During the scaling in process (when the units to be deleted are still in theDELETINGstate), rollback is supported.For example, in this example, you can execute
ALTER RESOURCE TENANT mysql001 UNIT_NUM = 3;to restoreUNIT_NUMto its original value. During rollback, units that were in theDELETINGstate directly change to theADDINGstate. - During the scaling in process, only rollback is allowed. Modifying
UNIT_NUMto other values is prohibited.
View the execution status of the job for decreasing the unit number.
obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_RESOURCE_TENANT_UNIT_NUM' AND TENANT_ID=1006;An example of the query result is as follows:
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+ | JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT | +--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+ | 25 | ALTER_RESOURCE_TENANT_UNIT_NUM | SUCCESS | 0 | 100 | 2025-06-18 10:06:15.648806 | 2025-06-18 10:08:39.969346 | 1006 | alter resource tenant mysql001 unit_num=2 | new unit num: '2' | 6.xx.xxx.xxx | 29700 | +--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
1 row in set
In the query result, find the corresponding job record based on the following fields:
* `START_TIME`: the time when the job was initiated.
* `SQL_TEXT`: the SQL statement corresponding to the job.
* `EXTRA_INFO`: the unit number before and after the change.
If the value of `JOB_STATUS` in the corresponding job record is `SUCCESS`, the job for decreasing the unit number is successfully executed.
For more information about the fields in the `DBA_OB_TENANT_JOBS` view, see [DBA_OB_TENANT_JOBS](../../../../700.reference/700.system-views/300.system-view-of-sys-tenant/200.dictionary-view-of-sys-tenant/23000.o-dba_ob_tenant_jobs-of-sys-tenant.md).
8. View the units of the `mysql001` tenant after the modification.
```shell
obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;
The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+
| UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID |
+---------+-----------+--------+------------------+---------------+-------+----------------+
| 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 |
| 1011 | 1006 | ACTIVE | 1002 | 1019 | zone2 | 1001 |
| 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 |
| 1013 | 1006 | ACTIVE | 1002 | 1020 | zone2 | 1001 |
| 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 |
| 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 |
+---------+-----------+--------+------------------+---------------+------+-----------------+
6 rows in set
Through the above example, the unit number for all resource pools of the mysql001 tenant is changed from 3 to 2. Before the change, the tenant had three units in each zone. After the change, the tenant has two units in each zone, thereby implementing tenant scaling in.
Decrease the unit number for a single resource pool of a tenant
For tenants in heterogeneous zone mode, if there are multiple resource pools, you can also use the ALTER RESOURCE POOL statement to separately decrease the unit number of a specific resource pool of the tenant. Tenants in homogeneous zone mode do not support this method.
The following example describes how to decrease the unit number of the pool2 resource pool of the mysql001 tenant.
Log in to the
systenant of the cluster as therootuser.obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -AAccess the database named
oceanbase.obclient(root@sys)[(none)]> use oceanbase;View the information about the
mysql001tenant to obtain itsTENANT_ID.obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY, TENANT_ROLE, UNIT_NUM, ZONE_UNIT_NUM_LIST FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';The query result is as follows:
+-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | TENANT_ROLE | UNIT_NUM | ZONE_UNIT_NUM_LIST | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+ | 1006 | mysql001 | USER | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | PRIMARY | 2 | zone1:2,zone2:2,zone3:2 | +-----------+-------------+-------------+--------------------+---------------------------------------------+-------------+----------+-------------------------+
1 row in set
In the query result, the `TENANT_ID` of the tenant is 1006, and the unit number of the tenant in each zone is 2:2:2.
4. View the current resource configuration of the tenant.
```shell
obclient(root@sys)[oceanbase]> SELECT c.TENANT_ID, e.TENANT_NAME, concat(c.NAME, ': ', d.NAME) `pool:conf`,c.ZONE_LIST, concat(c.UNIT_COUNT, ' unit: ', d.min_cpu, 'C/', ROUND(d.MEMORY_SIZE/1024/1024/1024,0), "G") unit_info
FROM oceanbase.DBA_OB_RESOURCE_POOLS c, oceanbase.DBA_OB_UNIT_CONFIGS d, oceanbase.DBA_OB_TENANTS e
WHERE c.UNIT_CONFIG_ID=d.UNIT_CONFIG_ID AND c.TENANT_ID=e.TENANT_ID AND c.TENANT_ID=1006;
The query result is as follows:
+-----------+-------------+------------------+-----------+---------------+
| TENANT_ID | TENANT_NAME | pool:conf | ZONE_LIST | unit_info |
+-----------+-------------+------------------+-----------+---------------+
| 1006 | mysql001 | pool3: test_unit | zone3 | 2 unit: 1C/8G |
| 1006 | mysql001 | pool2: test_unit | zone2 | 2 unit: 1C/8G |
| 1006 | mysql001 | pool1: test_unit | zone1 | 2 unit: 1C/8G |
+-----------+-------------+------------------+-----------+---------------+
3 rows in set
According to the query result, the mysql001 tenant has three resource pools: pool1, pool2, and pool3, distributed on zone1, zone2, and zone3 respectively.
View the unit information of the
mysql001tenant.obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;The query result is as follows:
+---------+-----------+--------+------------------+---------------+-------+----------------+ | UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID | +---------+-----------+--------+------------------+---------------+-------+----------------+ | 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 | | 1011 | 1006 | ACTIVE | 1002 | 1019 | zone2 | 1001 | | 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 | | 1013 | 1006 | ACTIVE | 1002 | 1020 | zone2 | 1001 | | 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 | | 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 | +---------+-----------+--------+------------------+---------------+------+-----------------+
6 rows in set
6. According to your requirements, change the `UNIT_NUM` of the `pool2` resource pool of the `mysql001` tenant to 1.
* Decrease the `UNIT_NUM` by randomly deleting units.
```shell
obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 1;
```
* Decrease the `UNIT_NUM` by deleting a specified unit.
```shell
obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 1 DELETE UNIT=(1011);
```
7. After the command is successfully executed, view the current status of units.
```shell
obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;
The query result is as follows:
+---------+-----------+----------+------------------+---------------+-------+----------------+
| UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID |
+---------+-----------+----------+------------------+---------------+-------+----------------+
| 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 |
| 1011 | 1006 | DELETING | 1002 | 1019 | zone2 | 1001 |
| 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 |
| 1013 | 1006 | ACTIVE | 1002 | 1020 | zone2 | 1001 |
| 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 |
| 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 |
+---------+-----------+----------+------------------+---------------+------+-----------------+
6 rows in set
You can see that the unit to be deleted is in the DELETING state.
Notice
- In OceanBase Database,
UNIT_NUMscaling in is an asynchronous process. During the scaling in process (when the units to be deleted are still in theDELETINGstate), rollback is supported.For example, in this example, you can execute
ALTER RESOURCE POOL pool2 UNIT_NUM = 2;to restoreUNIT_NUMto its original value. During rollback, units that were in theDELETINGstate directly change to theADDINGstate. - During the scaling in process, only rollback is allowed. Modifying
UNIT_NUMto other values is prohibited.
View the execution status of the job for decreasing the unit number.
obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_RESOURCE_TENANT_UNIT_NUM' AND TENANT_ID=1006;The query result is as follows:
+--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+ | JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT | +--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+ | 24 | ALTER_RESOURCE_TENANT_UNIT_NUM | SUCCESS | 0 | 100 | 2025-06-18 09:39:34.319331 | 2025-06-18 09:40:30.439822 | 1006 | alter resource pool pool2 unit_num=1 | new unit num: '1' | 6.xx.xxx.xxx | 29700 | +--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
1 row in set
In the query result, find the corresponding job record based on the following fields:
* `START_TIME`: the time when the job was initiated.
* `SQL_TEXT`: the SQL statement corresponding to the job.
* `EXTRA_INFO`: the unit number before and after the change.
If the value of `JOB_STATUS` in the corresponding job record is `SUCCESS`, the job for decreasing the unit number is successfully executed.
For more information about the fields in the `DBA_OB_TENANT_JOBS` view, see [DBA_OB_TENANT_JOBS](../../../../700.reference/700.system-views/300.system-view-of-sys-tenant/200.dictionary-view-of-sys-tenant/23000.o-dba_ob_tenant_jobs-of-sys-tenant.md).
9. View the units of the `mysql001` tenant after the modification.
```shell
obclient(root@sys)[oceanbase]> SELECT UNIT_ID, TENANT_ID, STATUS, RESOURCE_POOL_ID, UNIT_GROUP_ID, ZONE, UNIT_CONFIG_ID FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID = 1006;
The query result is as follows:
+---------+-----------+----------+------------------+---------------+-------+----------------+
| UNIT_ID | TENANT_ID | STATUS | RESOURCE_POOL_ID | UNIT_GROUP_ID | ZONE | UNIT_CONFIG_ID |
+---------+-----------+----------+------------------+---------------+-------+----------------+
| 1006 | 1006 | ACTIVE | 1003 | 1019 | zone3 | 1001 |
| 1012 | 1006 | ACTIVE | 1001 | 1019 | zone1 | 1001 |
| 1013 | 1006 | ACTIVE | 1002 | 1021 | zone2 | 1001 |
| 1014 | 1006 | ACTIVE | 1001 | 1020 | zone1 | 1001 |
| 1015 | 1006 | ACTIVE | 1003 | 1020 | zone3 | 1001 |
+---------+-----------+----------+------------------+---------------+------+-----------------+
5 rows in set
Through the above example, the unit number of the pool2 resource pool of the mysql001 tenant is changed from 2 to 1. Before the change, the tenant had two units in each zone. After the change, the tenant still has two units in zone1 and zone3, but has one unit in zone2, thereby implementing tenant scaling in.