Modify the number of primary zones for a tenant

Scaling out or in a tenant involves increasing or decreasing the tenant's service capabilities, including computing power and storage capacity. This can be achieved by upgrading or downgrading the service capabilities of a single node or by adding or removing nodes to adjust the tenant's overall service capacity. This topic explains how to scale up or down a tenant by modifying the primary zone to add or remove computing nodes.

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. The enable_transfer parameter depends on the value of the enable_rebalance parameter.

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

  • If both enable_rebalance and enable_transfer are set to true, the system automatically adjusts partition distribution during tenant scaling to achieve load balancing.

  • If enable_rebalance is set to true and enable_transfer is set to 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 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.

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

  For more information, see Plan resources.

Add a primary zone

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. Query the basic information about the mysql001 tenant, such as the TENANT_ID and PRIMARY_ZONE attributes.

   obclient> SELECT TENANT_ID, TENANT_NAME, PRIMARY_ZONE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';
   

   The query result is as follows:

   +-----------+-------------+--------------+
   | TENANT_ID | TENANT_NAME | PRIMARY_ZONE |
   +-----------+-------------+--------------+
   |      1004 | mysql001    | zone1;zone2  |
   +-----------+-------------+--------------+
   1 row in set
   

   As shown in the query result, the TENANT_ID of tenant mysql001 is 1004, and the top priority of PRIMARY_ZONE is zone1.

4. Query the number of resource units of the mysql001 tenant. In this example, the value of UNIT_NUM is 2, indicating that the tenant has two resource units in each zone.

   obclient> SELECT TENANT_ID, LS_ID, SVR_IP, SVR_PORT, ZONE, ROLE, REPLICA_TYPE FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE TENANT_ID = 1004 AND LS_ID != 1 AND ROLE = 'LEADER';
   

   The query result is as follows:

   +-----------+-------+---------------+----------+--------+--------+--------------+
   | TENANT_ID | LS_ID | SVR_IP        | SVR_PORT | ZONE   | ROLE   | REPLICA_TYPE |
   +-----------+-------+---------------+----------+--------+--------+--------------+
   |      1004 |  1001 | 172.xx.xxx.xx |    2882  |  zone1 | LEADER | FULL         |
   |      1004 |  1012 | 172.xx.xxx.xx |    2882  |  zone1 | LEADER | FULL         |
   +-----------+-------+---------------+----------+--------+--------+--------------+
   2 rows in set
   

   As shown in the query result, the mysql001 tenant has two leader replicas that are evenly distributed on the two servers in zone1.

5. Modify the PRIMARY_ZONE attribute of the mysql001 tenant to change the number of zones with top priority from 2 to 1.

   obclient> ALTER TENANT mysql001 PRIMARY_ZONE='zone1,zone2'; 
   

6. View the execution status of the job for adding a primary zone.

   SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_TENANT_PRIMARY_ZONE' 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 |
   +--------+---------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+--------------------------------------------------+-------------+----------------+-------------+
   |      4 | ALTER_TENANT_PRIMARY_ZONE | SUCCESS    |           0 |      100 | 2024-12-18 17:26:00.069089 | 2024-12-18 17:26:20.919021 |      1004 | ALTER TENANT mysql001 PRIMARY_ZONE='zone1,zone2' | zone1;zone2 | 172.xx.xxx.xx  |       2882  |
   +--------+---------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+--------------------------------------------------+-------------+----------------+-------------+
   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 primary zone information before or after the modification.

   If the value of JOB_STATUS is SUCCESS in the corresponding job record, the job for adding the primary zone is successfully executed.

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

7. Query the basic information of the mysql001 tenant. The zones with the highest priority change from zone1 to zone1,zone2.

   obclient> SELECT PRIMARY_ZONE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_ID = 1004;
   

   The query result is as follows:

   +--------------+
   | PRIMARY_ZONE |
   +--------------+
   | zone1,zone2  |
   +--------------+
   1 row in set
   

8. Query the distribution information of the mysql001 tenant's log stream leader replica locations again.

   obclient> SELECT TENANT_ID, LS_ID, SVR_IP, SVR_PORT, ZONE, ROLE, REPLICA_TYPE FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE TENANT_ID = 1004 AND LS_ID != 1 AND ROLE = 'LEADER';
   

   The query result is as follows:

   +-----------+-------+---------------+----------+-------+--------+--------------+
   | TENANT_ID | LS_ID | SVR_IP        | SVR_PORT | ZONE  | ROLE   | REPLICA_TYPE |
   +-----------+-------+---------------+----------+-------+--------+--------------+
   |      1004 |  1001 | 172.xx.xxx.xx |    2882  | zone1 | LEADER | FULL         |
   |      1004 |  1012 | 172.xx.xxx.xx |    2882  | zone1 | LEADER | FULL         |
   |      1004 |  1013 | 172.xx.xxx.xx |    2882  | zone2 | LEADER | FULL         |
   |      1004 |  1014 | 172.xx.xxx.xx |    2882  | zone2 | LEADER | FULL         |
   +-----------+-------+---------------+----------+-------+--------+--------------+
   4 rows in set
   

   As shown in the query results, tenant mysql001 has two leader replicas in zone1 and two leader replicas in zone2, meaning a total of four leader replicas provide services.

The preceding example shows that before the change, the PRIMARY_ZONE of tenant mysql001 had one top-priority zone with two leader replicas providing services. After the change, the number of top-priority zones in PRIMARY_ZONE increased from one to two, and the number of leader replicas providing services grew from two to four. This added computing nodes, enabling the tenant to scale out.

Remove a primary zone

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. Query the basic information about the mysql001 tenant, such as the TENANT_ID and PRIMARY_ZONE attributes.

   obclient> SELECT TENANT_ID, TENANT_NAME, PRIMARY_ZONE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mysql001';
   

   The query result is as follows:

   +-----------+-------------+--------------+
   | TENANT_ID | TENANT_NAME | PRIMARY_ZONE |
   +-----------+-------------+--------------+
   |      1004 | mysql001    | zone1,zone2  |
   +-----------+-------------+--------------+
   1 row in set
   

   As shown in the query result, the TENANT_ID of tenant mysql001 is 1004, and the top priority of PRIMARY_ZONE is zone1 and zone2.

4. Query the distribution of leader replicas of log streams of the mysql001 tenant.

   obclient> SELECT TENANT_ID, LS_ID, SVR_IP, SVR_PORT, ZONE, ROLE, REPLICA_TYPE FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE TENANT_ID = 1004 AND LS_ID != 1 AND ROLE = 'LEADER';
   

   The query result is as follows:

   +-----------+-------+---------------+----------+-------+--------+--------------+
   | TENANT_ID | LS_ID | SVR_IP        | SVR_PORT | ZONE  | ROLE   | REPLICA_TYPE |
   +-----------+-------+---------------+----------+-------+--------+--------------+
   |      1004 |  1001 | 172.xx.xxx.xx |    2882  | zone1 | LEADER | FULL         |
   |      1004 |  1012 | 172.xx.xxx.xx |    2882  | zone1 | LEADER | FULL         |
   |      1004 |  1013 | 172.xx.xxx.xx |    2882  | zone2 | LEADER | FULL         |
   |      1004 |  1014 | 172.xx.xxx.xx |    2882  | zone2 | LEADER | FULL         |
   +-----------+-------+---------------+----------+-------+--------+--------------+
   4 rows in set
   

   As shown in the query result, the mysql001 tenant has four leader replicas providing services, which are evenly distributed on two servers in zone1 and two servers in zone2.

5. Modify the PRIMARY_ZONE attribute of the mysql001 tenant to change the number of zones with top priority from 2 to 1.

   obclient> ALTER TENANT mysql001 PRIMARY_ZONE='zone1;zone2'; 
   

6. View the execution status of the job for reducing primary zones.

   SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE='ALTER_TENANT_PRIMARY_ZONE' 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 |
   +--------+---------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+--------------------------------------------------+---------------+----------------+-------------+
   |      4 | ALTER_TENANT_PRIMARY_ZONE | SUCCESS    |           0 |      100 | 2024-12-18 17:26:00.069089 | 2024-12-18 17:26:20.919021 |      1004 | ALTER TENANT mysql001 PRIMARY_ZONE='zone1,zone2' | zone1;zone2   |  172.xx.xxx.xx |        2882 |
   |      5 | ALTER_TENANT_PRIMARY_ZONE | SUCCESS    |           0 |      100 | 2024-12-18 17:41:44.412459 | 2024-12-18 17:41:54.965873 |      1004 | ALTER TENANT mysql001 PRIMARY_ZONE='zone1;zone2' | zone1,zone2   |  172.xx.xxx.xx |        2882 |
   +--------+---------------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+--------------------------------------------------+---------------+----------------+-------------+
   2 rows 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 primary zone information before or after the modification.

   If the value of JOB_STATUS is SUCCESS in the corresponding job record, the job for reducing primary zones is successfully executed.

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

7. Query the basic information of the mysql001 tenant and confirm that the value of the PRIMARY_ZONE attribute is changed from zone1,zone2 to zone1;zone2.

   obclient> SELECT PRIMARY_ZONE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_ID = 1004;
   

   The query result is as follows:

   +--------------+
   | PRIMARY_ZONE |
   +--------------+
   |  zone1;zone2 |
   +--------------+
   1 row in set
   

8. Query the distribution of leader replicas of log streams of the mysql001 tenant again.

   obclient> SELECT TENANT_ID, LS_ID, SVR_IP, SVR_PORT, ZONE, ROLE, REPLICA_TYPE FROM oceanbase.CDB_OB_LS_LOCATIONS WHERE TENANT_ID = 1004 AND LS_ID != 1 AND ROLE = 'LEADER';
   

   The query result is as follows:

   +-----------+-------+---------------+----------+--------+--------+--------------+
   | TENANT_ID | LS_ID | SVR_IP        | SVR_PORT | ZONE   | ROLE   | REPLICA_TYPE |
   +-----------+-------+---------------+----------+--------+--------+--------------+
   |      1004 |  1001 | 172.xx.xxx.xx |    2882  |  zone1 | LEADER | FULL         |
   |      1004 |  1012 | 172.xx.xxx.xx |    2882  |  zone1 | LEADER | FULL         |
   +-----------+-------+---------------+----------+--------+--------+--------------+
   2 rows in set
   

   As shown in the query result, the mysql001 tenant has two leader replicas providing services on servers in zone1.

The preceding example shows that before the change, the PRIMARY_ZONE of tenant mysql001 had two top-priority zones with four leader replicas providing services. After the change, the number of top-priority zones in PRIMARY_ZONE decreased from two to one, and the number of leader replicas providing services as reduced from two to four. This reduced the number of computing nodes, thereby achieving tenant scaling in.