Modify the number of resource units for a tenant

Tenant scaling aims 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 number of resource units to increase or decrease service nodes to improve or reduce the overall service capabilities of a tenant, thereby implementing tenant scaling.

You can increase or decrease the number of resource units.

Background information

In the current version, OceanBase Database supports homogeneous and heterogeneous zone modes for tenants:

• In the homogeneous zone mode, all zones of a tenant must have the same number of units. To facilitate resource unit management, the system introduces the unit group mechanism. Resource units in different zones can be classified into the same unit group. The resource units in a single unit group share the same unit group ID. Increasing or decreasing the number of resource units is to create or delete resource units based on unit groups.

• In the heterogeneous zone mode, the UNIT_NUM values of different zones can be the same or different. However, a tenant can have at most two different UNIT_NUM values. Log streams are no longer bound to unit groups. Replicas in different zones are no longer required to be symmetric. For a tenant in the heterogeneous zone mode, you can increase or decrease the number of resource units of a resource pool in addition to increasing or decreasing the number of resource units of the tenant. This way, you can scale in or out a resource pool.

Prerequisites

Before you perform a scale-in or scale-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_rebalance and enable_transfer.

  You can specify the enable_rebalance parameter in the sys tenant to control whether to enable load balancing among tenants, and specify this parameter in a user tenant to control whether to enable load balancing for the current tenant. The default value is true. The setting takes effect immediately without the need to restart the OBServer node.

  You can specify the enable_transfer parameter to control whether to enable the transfer feature for a tenant. The default value is true. The setting takes effect immediately without the need to restart the OBServer node.

  • If the value of enable_rebalance is false, the system does not perform automatic load balancing regardless of whether the value of enable_transfer is true or false.

  • If the value of enable_rebalance is true and the value of enable_transfer is true, the system automatically adjusts partition distribution to achieve load balancing during a tenant scaling operation.

  • If the value of enable_rebalance is true and the value of enable_transfer is false, 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 sys tenant

    • Enable load balancing and the transfer feature for a specified tenant from the sys tenant

        ALTER SYSTEM SET enable_rebalance = true TENANT = 'tenant_name';
      

        ALTER SYSTEM SET enable_transfer = true TENANT = 'tenant_name';
      

      These statements only set the values of the enable_rebalance and enable_transfer parameters to true for the specified user tenant.

    • Enable intra-tenant load balancing and the transfer feature for all user tenants from the sys tenant

        ALTER 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 only set the values of the enable_rebalance and enable_transfer parameters to true for all user tenants.

      Note

      Starting from OceanBase Database V4.2.1, TENANT = all_user and TENANT = all express the same semantics. If you want an operation to take effect on all user tenants, we recommend that you use TENANT = all_user. TENANT = all will be deprecated.

  • Enable load balancing for a user tenant from the current tenant

    MySQL mode

    Oracle mode

    You can execute the following statements to enable load balancing and the transfer feature for a MySQL tenant:

      ALTER SYSTEM SET enable_rebalance = true;
    

      ALTER SYSTEM SET enable_transfer = true;
    

    You can execute the following statements to enable load balancing and the transfer feature for an Oracle tenant:

      ALTER SYSTEM SET enable_rebalance = 'true';
    

      ALTER SYSTEM SET enable_transfer = 'true';
    

  For more information about the enable_rebalance and enable_transfer parameters, see enable_rebalance and enable_transfer, respectively.

• If the tenant is deleted, drop the resource pool of the tenant to release resources. Resources in an idle resource pool are also considered occupied resources.

  For more information about how to drop a resource pool, see Drop a resource pool.

• Perform a minor compaction to release the occupied memory resources.

  For more information about how to manually initiate a minor compaction, see Manually initiate a minor compaction.

• Plan resources for the tenant to achieve the desired results.

  For more information, see Plan resources.

Considerations

When you scale in or out a tenant by adjusting the number of resource units, note the following considerations:

• Do not modify the locality of the tenant during scaling in or out.

• Do not expand the ZONE_LIST of the resource pool of the tenant during scaling in or out.

• Do not add a new resource pool to the tenant during scaling in or out.

• Do not merge resource pools during scaling in or out.

• Do not migrate a unit in the DELETING state during scaling in or out.

Increase the number of resource units

Increase the number of resource units for all resource pools of a tenant

For a tenant in a homogeneous zone mode or a heterogeneous zone mode, you can use the ALTER RESOURCE TENANT statement to increase the number of resource units for all resource pools of the tenant. The following example describes how to increase the number of resource units for all resource pools of the mysql001 tenant.

1. Log in to the sys tenant of the cluster as the root user.

   obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -A
   

2. Access the database named oceanbase.

   use oceanbase;
   

3. View the information about the mysql001 tenant to obtain its tenant 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 value of UNIT_NUM is 1:1:1, indicating that the tenant has one unit in each zone.

4. View the resource units of the mysql001 tenant.

   SELECT * 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
   

   The query result shows that the mysql001 tenant has one resource unit in each zone, and the three resource units have the same UNIT_GROUP_ID.

5. Change the value of UNIT_NUM to 2 for the mysql001 tenant.

   ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2;
   

6. After the command is executed, view the status of the current resource 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 new resource units are in the ADDING state. After internal balancing is completed, the resource unit state changes from ADDING to ACTIVE.

   Notice

   • In OceanBase Database versions earlier than V4.2.5 (excluding V4.2.5 BP5 and later BP versions and V4.4.2 and later versions), UNIT_NUM expansion is a synchronous process. In the current version, UNIT_NUM expansion is an asynchronous process. The new resource units are in the ADDING state.
   • During expansion (when the new resource units are still in the ADDING state), you can perform a rollback operation.

     For example, you can execute the ALTER RESOURCE TENANT mysql001 UNIT_NUM = 1; statement to revert UNIT_NUM to its original value. When you perform a rollback, the original ADDING resource units directly change to the DELETING state. Note that when you perform a rollback, you cannot delete specified resource units in the specified unit group. The system automatically selects ADDING resource units for deletion.

   • Before the expansion is completed, you can perform only a rollback operation and cannot modify UNIT_NUM to a different value.

7. View the resource units of the tenant after the modification.

   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 number of resource units before and after the change.

   If the value of JOB_STATUS in the corresponding change record is SUCCESS, the job for increasing the number of resource units is successfully executed.

   For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.

8. View the resource units of the mysql001 tenant after the modification.

   SELECT * 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
   

The query result shows that the number of resource units in each zone is changed from 1 to 2 for the mysql001 tenant. The tenant has one resource unit in each zone before the change, and two resource units in each zone after the change.

Increase the number of resource units in a resource pool

For tenants in heterogeneous zone mode, you can use the ALTER RESOURCE POOL statement to increase the number of resource units in a resource pool. This method is not supported for tenants in homogeneous zone mode.

The following example describes how to increase the number of resource units in the pool2 resource pool of the mysql001 tenant.

1. Log in to the sys tenant of the cluster as the root user.

   CODE_PLACEHOLDER_356863e6116c46ed897bb7e654f20ec5

2. Enter the oceanbase database.

    obclient(root@sys)[(none)]> use oceanbase;
   

3. View the information of the mysql001 tenant and obtain its TENANT_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
   

   The query result shows that the TENANT_ID of the mysql001 tenant is 1006, and the number of resource units in each zone is 2:2:2.

4. View the resource configuration of the current tenant.

   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
   

   The query result shows that the mysql001 tenant has three resource pools named pool1, pool2, and pool3, which are located in zone1, zone2, and zone3, respectively.

5. Change the UNIT_NUM of the pool2 resource pool of the mysql001 tenant to 3.

   obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 3;
   

6. View the status of the current resource 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
   

   The query result shows that the status of the new resource unit is ADDING. After the internal load balancing is completed, the status of the resource unit changes from ADDING to ACTIVE.

   Notice

   • In OceanBase Database versions earlier than V4.2.5 (excluding V4.2.5 BP5 and later BP versions and V4.4.2 and later versions), the UNIT_NUM expansion is a synchronous process. In the current version, the UNIT_NUM expansion is an asynchronous process. The status of the new resource unit is ADDING.
   • During the expansion process (while the status of the new resource unit is ADDING), you can roll back the operation.

     For example, you can execute the ALTER RESOURCE POOL pool2 UNIT_NUM = 2; statement to change the UNIT_NUM back to the original value. When you roll back, the resource units in the ADDING state directly change to the DELETING state. Note that when you roll back, you cannot delete the specified resource units. The system automatically selects the resource units in the ADDING state for deletion.

   • Before the expansion process is completed, you can only roll back the operation and cannot change the UNIT_NUM to another value.

7. View the execution status of the task to increase the number of resource units.

   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
   

   The query result shows the following fields to locate the task record:

   • START_TIME: the time when the task was initiated.

   • SQL_TEXT: the SQL statement corresponding to the task.

   • EXTRA_INFO: the number of resource units before and after the change.

   When the value of the JOB_STATUS field in the corresponding change record is SUCCESS, the task to increase the number of resource units is successful.

   For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.

8. View the resource units of the mysql001 tenant 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
   

The query result shows that the number of resource units in the pool2 resource pool of the mysql001 tenant is changed from 2 to 3. Before the change, the number of resource units in each zone was 2. After the change, the number of resource units in zone1 and zone3 is still 2, and the number of resource units in zone2 is changed to 3.

Decrease the number of resource units

Considerations

Before you decrease the number of resource units of a tenant, make sure whether the GTS standalone feature is enabled. The enable_gts_standalone parameter at the tenant level specifies whether to enable the GTS standalone feature. The default value is False, which indicates that the feature is disabled.

If the GTS standalone feature is enabled, note the following considerations:

• After the GTS standalone feature is enabled, the UNIT_NUM of each zone of the tenant must be greater than or equal to 2. If you decrease the UNIT_NUM of any zone to a value less than 2, an error is returned.

• When you decrease the number of resource units by deleting a specified unit or unit group, you cannot delete a unit or unit group in the GTS standalone mode. Otherwise, an error is returned.

Decrease the number of resource units in all resource pools

For tenants in homogeneous zone mode or heterogeneous zone mode, you can use the ALTER RESOURCE TENANT statement to decrease the number of resource units in all resource pools. The following example describes how to decrease the number of resource units in all resource pools of the mysql001 tenant.

The following example describes how to decrease the number of resource units of the mysql001 tenant.

1. Log in to the sys tenant of the cluster as the root user.

   obclient -h172.xxx.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -A
   

2. Access the database named oceanbase.

   use oceanbase;
   

3. View the information about the mysql001 tenant to obtain its tenant 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 set
   

   In the query result, the TENANT_ID of the tenant is 1006, and the value of UNIT_NUM is 3, indicating that the tenant has three units in each zone.

4. View the resource units of the mysql001 tenant.

   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
   

   The query result shows that the mysql001 tenant has three resource units in each zone. The resource units with the IDs 1001, 1005, and 1007 belong to the unit group with the ID 1018. The resource units with the IDs 1006, 1011, and 1012 belong to the unit group with the ID 1019. The resource units with the IDs 1013, 1014, and 1015 belong to the unit group with the ID 1020.

5. Change the value of UNIT_NUM to 2 for the mysql001 tenant.

   • Randomly delete a unit to decrease the number of resource units

     For a homogeneous or heterogeneous zone tenant, you can execute the following statement to decrease the number of resource units.

     obclient(root@sys)[oceanbase]> ALTER RESOURCE TENANT mysql001 UNIT_NUM = 2;
     

     After this statement is executed:

     • For a homogeneous zone tenant, such as the mysql001 tenant in this example, where the UNIT_NUM of all resource pools is changed from 3 to 2, the system randomly specifies a unit group with the same UNIT_GROUP_ID for deletion.

     • For a heterogeneous zone tenant, the system randomly selects a unit group for deletion.

   • Delete a specified unit group to decrease the number of resource units

     For a homogeneous zone tenant, you can also execute the following statement to decrease the number of resource units. This statement is not supported for a heterogeneous zone tenant.

     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 resource units, the system redistributes the data in the specified unit group to other unit groups, and then deletes the unit group.

6. View the status of the current unit after the statement is executed.

   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 |
   +---------+-----------+----------+------------------+---------------+-------+----------------+
   |    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
   

   The unit to be deleted is in the DELETING state.

   Notice

   • In OceanBase Database, UNIT_NUM reduction is an asynchronous process. During the reduction process (when the unit to be deleted is in the DELETING state), you can roll back the operation.

     For example, you can execute the ALTER RESOURCE TENANT mysql001 UNIT_NUM = 3; statement to change the value of UNIT_NUM back to the original value. When you roll back the operation, the unit in the DELETING state will directly change to the ADDING state.

   • During the reduction process, you can only roll back the operation and cannot change the value of UNIT_NUM to other values.

7. View the execution status of the job for decreasing the number of resource units.

   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 |
   +--------+--------------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+-----------------------------------------------------------+-------------------+--------------+-------------+
   |     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 number of resource units before and after the change.

   If the value of JOB_STATUS is SUCCESS in the corresponding job record, the job for decreasing the number of resource units is successfully executed.

   For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.

8. View the resource units of the mysql001 tenant 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 |
   +---------+-----------+--------+------------------+---------------+-------+----------------+
   |    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
   

The query result shows that the number of resource units in each zone is changed from 3 to 2 for the mysql001 tenant. The tenant has three resource units in each zone before the change, and two resource units in each zone after the change.

Scale in the number of resource units in a resource pool

For a tenant in a heterogeneous zone mode, you can use the ALTER RESOURCE POOL statement to scale in the number of resource units in a resource pool. You cannot use this statement for a tenant in a homogeneous zone mode.

The following example shows how to scale in the number of resource units in the pool2 resource pool of the mysql001 tenant.

1. Log in to the sys tenant of the cluster as the root user.

   obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -A
   

2. Switch to the oceanbase database.

   obclient(root@sys)[(none)]> use oceanbase;
   

3. Query the information of the mysql001 tenant to obtain its TENANT_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
   

   The query result shows that the TENANT_ID of the mysql001 tenant is 1006, and the number of resource units in each zone is 2:2:2.

4. Query the resource pool configuration of the current tenant.

   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
   

   The query result shows that the mysql001 tenant has three resource pools: pool1, pool2, and pool3, which are located in the zone1, zone2, and zone3 zones, respectively.

5. Query the resource units of the mysql001 tenant.

   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. Change the UNIT_NUM of the pool2 resource pool of the mysql001 tenant to 1.

   • Scale in the number of resource units by randomly deleting resource units.

     obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 1;
     

   • Scale in the number of resource units by deleting specified resource units.

     obclient(root@sys)[oceanbase]> ALTER RESOURCE POOL pool2 UNIT_NUM = 1 DELETE UNIT=(1011);
     

7. After the command is executed, query the status of the current resource 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 |
   +---------+-----------+----------+------------------+---------------+-------+----------------+
   |    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
   

   The query result shows that the status of the resource unit to be deleted is DELETING.

   Notice

   • Scaling in the number of resource units in OceanBase Database is an asynchronous process. During the scaling-in process (when the status of the resource unit to be deleted is DELETING), you can roll back the operation.

     For example, you can execute the ALTER RESOURCE POOL pool2 UNIT_NUM = 2; statement to change the UNIT_NUM value back to the original value. When you roll back the operation, the resource units in the DELETING state will directly change to the ADDING state.

   • During the scaling-in process, you can only roll back the operation and cannot change the UNIT_NUM value to another value.

8. Query the execution status of the scaling-in task.

   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
   

   The query result shows the following fields for the task record:

   • START_TIME: the start time of the task.
   • SQL_TEXT: the SQL statement corresponding to the task.
   • EXTRA_INFO: the number of resource units before and after the change.

   When the value of the JOB_STATUS field in the corresponding change record is SUCCESS, the scaling-in task is executed successfully.

   For more information about the fields in the DBA_OB_TENANT_JOBS view, see DBA_OB_TENANT_JOBS.

9. View the resource units of the mysql001 tenant 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 |
   +---------+-----------+----------+------------------+---------------+-------+----------------+
   |    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
   

The query result shows that the number of resource units in the pool2 resource pool of the mysql001 tenant is changed from 2 to 1. Before the change, the number of resource units in each zone is 2. After the change, the number of resource units in the zone1 and zone3 zones is still 2, but the number of resource units in the zone2 zone is changed to 1. The tenant is scaled in.

References

• Tenant scaling