Create a tenant

OceanBase Database is a native distributed database. Multiple database instances can run in the same database. The first step is to create a tenant (database instance) and then use the database instance as you would a traditional standalone database. This topic describes how to create a tenant.

Procedure for creating a user tenant

OceanBase Database only supports creating user tenants. The system tenant is automatically created when the cluster is created. Creating a user tenant involves a series of operations: first, define a resource specification; then, based on that specification, create a resource pool; finally, create the tenant and specify its resource pool. Therefore, the order for creating a tenant is: resource specification -> resource pool -> tenant.

1. Create a resource specification: Creating a resource specification is merely a definition and does not actually allocate resources. You can view all resource specifications in the DBA_OB_UNIT_CONFIGS view. Resource specifications can be reused. It is recommended to abstract several different specifications based on business scenarios, such as small, medium, and large specifications, to reduce operational complexity. However, if multiple tenants share the same resource specification and one tenant needs emergency expansion due to insufficient resources, you cannot directly adjust the original specification. Instead, you need to create a new independent resource specification and switch to it, or directly use a larger resource specification.

2. Create a resource pool: When creating a resource pool, units are actually created and resources are allocated according to the specifications. If the reserved resources on the corresponding nodes are insufficient, the creation will fail. You can view the resource allocation information of all nodes in the GV$OB_SERVERS view. If the creation is successful, you can view the resource pool and its corresponding units in the DBA_OB_RESOURCE_POOLS and DBA_OB_UNITS views. Resource pools cannot be reused. After a tenant is successfully created, the specified resource pool will be allocated to the tenant.

3. Create a tenant: When creating a tenant, you specify the RESOURCE_POOL_LIST to allocate the resource pool to the tenant. You can view all tenants in the DBA_OB_TENANTS view. You can have one resource pool per zone, using independent resource specifications. Alternatively, all zones can share the same resource pool and resource specification. In addition to the resource pool list, other important attributes and system variables include compatibility mode, primary zone, locality, and connection allowlist. The resource pool list is a required field when creating a tenant. The root user password of a newly created tenant is empty. Please set a password before using it.

Resource planning

Before creating a tenant, you need to plan the resources. Adjusting resources after tenant creation can be very complicated. The premise for effective resource planning is a deep understanding of the business scenarios, allowing you to actively participate in the database architecture design.

Consider the following when planning resources:

• Reserve a certain amount of resources on each node for emergency expansion when a tenant's capacity is insufficient.

• For businesses with a large amount of write operations, set a larger memory and log disk specification. For businesses that heavily consume CPU resources, distribute them across different nodes to avoid uneven node load and potential hotspots that could affect business operations.

• The cluster configuration parameter resource_hard_limit defines the percentage of CPU resource over-subscription, also known as the "over-subscription configuration parameter." OceanBase Database only supports CPU over-subscription and does not support over-subscription for other resources. CPU over-subscription is suitable for scenarios where different tenants in the same cluster have peak resource usage at different times, thereby improving overall resource utilization. If multiple tenants have peak resource usage simultaneously, enabling CPU over-subscription may lead to CPU resource contention and mutual impact between tenants.

• The unit config of a resource unit cannot exceed the total available resources of a single node. For a tenant with a single resource unit, namely, UNIT_NUM is set to 1 for the resource pool of the tenant, when a capacity bottleneck occurs, you can replace the existing server with one of a larger specification, or add a resource unit for the tenant to use the resources on multiple nodes. For a tenant with multiple resource units, you must carefully design the distribution of business data among the resource units to prevent distributed transactions from compromising the performance. If you estimate that the business volume will exceed the capacity limit of a single server, you must design data sharding in advance and avoid distributed transactions.

  For a business system migrated from a conventional database to OceanBase Database, the original architecture where a tenant uses a single resource unit is used to ensure smooth migration. This ensures that the business system only needs to access a single node to access the database. When the business volume reaches the maximum capacity of a single node, you can add resource units and split the business data into multiple groups based on business scenarios. Place each group of business data into one resource unit to avoid cross-server access to the business data. This implements horizontal scaling without performance loss. This is also one of the architectural benefits of OceanBase Database against conventional databases. The horizontal scalability can easily break the limit on the capacity of a single server.

Considerations

OceanBase Database supports two types of tenants: MySQL-compatible mode and Oracle-compatible mode. When creating a tenant, you need to specify the tenant type. Once a tenant is created, its type cannot be modified. Therefore, plan your tenant type before creating the tenant.

Step 1: Create a resource specification

A resource specification defines resources such as CPU, memory, disk space, and IOPS.

Procedure

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

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

2. Enter the oceanbase database.

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

3. Query the DBA_OB_UNIT_CONFIGS view to obtain existing resource specifications.

   obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS;
   

   The result is as follows:

   +----------------+-----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+---------------------+---------------------+-------------+---------------------+----------------------+
   | UNIT_CONFIG_ID | NAME            | CREATE_TIME                | MODIFY_TIME                | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | DATA_DISK_SIZE | MAX_IOPS            | MIN_IOPS            | IOPS_WEIGHT | MAX_NET_BANDWIDTH   | NET_BANDWIDTH_WEIGHT |
   +----------------+-----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+---------------------+---------------------+-------------+---------------------+----------------------+
   |              1 | sys_unit_config | 2025-05-16 11:30:47.000298 | 2025-05-16 11:30:47.000298 |       4 |       4 |  5368709120 |   17448304640 |           NULL | 9223372036854775807 | 9223372036854775807 |           4 | 9223372036854775807 |                    4 |
   |           1001 | unit001         | 2025-05-16 11:31:08.531754 | 2025-05-16 11:31:08.531754 |       2 |       2 |  6442450944 |   19327352832 |           NULL | 9223372036854775807 | 9223372036854775807 |           2 | 9223372036854775807 |                    2 |
   +----------------+-----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+---------------------+---------------------+-------------+---------------------+----------------------+
   2 rows in set
   

   For more information about the DBA_OB_UNIT_CONFIGS view, see DBA_OB_UNIT_CONFIGS.

4. Use the CREATE RESOURCE UNIT statement to create a resource specification.

   The syntax is as follows:

   CREATE RESOURCE UNIT unit_name 
       MEMORY_SIZE [=] 'size_value',
       MAX_CPU [=] cpu_num,  
       [MAX_IOPS [=] iops_num,]
       [MIN_CPU [=] cpu_num,]
       [MIN_IOPS [=] iops_num,]
       [IOPS_WEIGHT [=]iopsweight,]
       [MAX_NET_BANDWIDTH [=] bandwidth_num,] 
       [NET_BANDWIDTH_WEIGHT [=] bandwidth_weight_num,]
       [LOG_DISK_SIZE [=] 'size_value'];
   

   Parameters:

   When creating a resource specification, MAX_CPU and MEMORY_SIZE are required.

   • unit_name: the name of the unit config.

   • MEMORY_SIZE: the memory size. Its minimum value is controlled by the __min_full_resource_pool_memory parameter, which is 5 GB by default. You can change the minimum value to 4 GB. OceanBase Database does not support memory overprovisioning in V4.0 and later.

   • MAX_CPU: the maximum number of CPU cores. MIN_CPU specifies the minimum number of CPU cores. The value is the number of CPU cores. If MIN_CPU is not specified, its value is equal to that of MAX_CPU by default.

   • MIN_CPU: the minimum number of CPU cores. The sum of the MIN_CPU values of all tenants cannot exceed the total CPU capacity of the node, which is specified by CPU_CAPACITY.

   • MAX_IOPS and MIN_IOPS: the maximum and minimum IOPS values for the current unit config. The minimum value is 1024. The MAX_IOPS value must be greater than or equal to the MIN_IOPS value.

     After the MAX_IOPS and MIN_IOPS parameters are specified, OceanBase Database compares their values with the baseline IOPS value for 16 KB reads based on the current disk. If their values are greater than the baseline IOPS value, OceanBase Database uses the baseline IOPS value as the valid value of these two parameters. Therefore, we recommend that you set MAX_IOPS and MIN_IOPS to the baseline IOPS value to facilitate resource isolation among tenants. For more information about how to calculate the baseline IOPS value, see Calibrate the disk performance. For more information about resource isolation among tenants, see Overview of resource isolation.

     If the IOPS parameters are not specified, the following rules apply:

     If IOPS-related parameters are not specified, their internal values are determined as follows:

     • If neither MIN_IOPS nor MAX_IOPS is specified, the system automatically allocates IOPS resources based on IOPS_WEIGHT. In this case:

       • Both MIN_IOPS and MAX_IOPS are set to INT64_MAX.

       • If IOPS_WEIGHT is not specified, it defaults to MIN_CPU.

       • If IOPS_WEIGHT is specified, the specified value is used.

     • If only MAX_IOPS is specified, MIN_IOPS is set to the value of MAX_IOPS. Similarly, if only MIN_IOPS is specified, MAX_IOPS is set to the value of MIN_IOPS. In this case:

       • If IOPS_WEIGHT is not specified, it defaults to 0.

   • MAX_NET_BANDWIDTH: specifies the upper limit of network bandwidth available for each unit of a tenant. The minimum value is 1 MB. If not specified, the default value is INT64_MAX.

   • NET_BANDWIDTH_WEIGHT: specifies the network bandwidth weight of a tenant unit, used to calculate the proportion of bandwidth allocated to each tenant by each OBServer. The minimum value is 0. If not specified, the system automatically calculates the value of NET_BANDWIDTH_WEIGHT based on the following rules:

     • If MAX_NET_BANDWIDTH is specified, NET_BANDWIDTH_WEIGHT is set to 0.

     • If MAX_NET_BANDWIDTH is not specified, NET_BANDWIDTH_WEIGHT = MIN_CPU.

   • LOG_DISK_SIZE: the size of the log disk. In OceanBase Database V4.0, the log disk space is managed per tenant. The system reserves log disk space for each tenant to ensure tenant isolation. If not specified, the default value of LOG_DISK_SIZE is three times the memory size, with a minimum of 2G.

   • OceanBase Database V4.0 supports IOPS isolation between tenants. The isolation is determined by the MAX_IOPS, MIN_IOPS, and IOPS_WEIGHT parameters. By default, the IOPS specifications do not need to be specified, and the system automatically calculates them based on the CPU specifications.

   • When specifying a value for a parameter, you can use a pure number without quotes or a number with a unit and quotes (e.g., '1T', '1G', '1M', '1K').

     Here:

     • For integer parameters such as MAX_CPU, MIN_CPU, MAX_IOPS, MIN_IOPS, IOPS_WEIGHT, and NET_BANDWIDTH_WEIGHT, if the parameter value is specified with a unit and quotes, the unit represents the number of units. For example, '1K' = 1000 and '1M' = 1,000,000. For example, MAX_IOPS='2K' is equivalent to MAX_IOPS=2000.

       If the parameter value is specified without a unit and quotes, the meaning is the same as without quotes. For example, '100' = 100 and '1000' = 1000.

     • For capacity parameters such as MEMORY_SIZE, MAX_NET_BANDWIDTH, and LOG_DISK_SIZE, if the parameter value is specified with a unit and quotes, the unit represents bytes. For example, '1K' = 1024 and '1M' = 1024 * 1024.

       If the parameter value is specified without a unit and quotes, the default unit is MB. For example, '100' = '100M' = 100 * 1024 * 1024.

   For more information about the CREATE RESOURCE UNIT statement, see CREATE RESOURCE UNIT.

   Example:

   Create a resource specification named S1_unit_config with 1 CPU core, 5G of memory, and 6G of log disk space.

   obclient(root@sys)[oceanbase]> CREATE RESOURCE UNIT S1_unit_config
                   MEMORY_SIZE = '5G',
                   MAX_CPU = 1, MIN_CPU = 1,
                   LOG_DISK_SIZE = '6G',
                   MAX_IOPS = 10000, MIN_IOPS = 10000, IOPS_WEIGHT=1;
   

5. Query the DBA_OB_UNIT_CONFIGS view to confirm that the resource specification was created successfully.

   obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS WHERE NAME = 'S1_unit_config';
   

   The returned result is as follows:

   +----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+----------+----------+-------------+---------------------+----------------------+
   | UNIT_CONFIG_ID | NAME           | CREATE_TIME                | MODIFY_TIME                | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | DATA_DISK_SIZE | MAX_IOPS | MIN_IOPS | IOPS_WEIGHT | MAX_NET_BANDWIDTH   | NET_BANDWIDTH_WEIGHT |
   +----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+----------+----------+-------------+---------------------+----------------------+
   |           1002 | S1_unit_config | 2025-05-28 10:20:38.299456 | 2025-05-28 10:20:38.299456 |       1 |       1 |  5368709120 |    6442450944 |           NULL |    10000 |    10000 |           1 | 9223372036854775807 |                    1 |
   +----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------------+----------+----------+-------------+---------------------+----------------------+
   1 row in set
   

Step 2: Create a resource pool

After creating a resource specification, you can specify the resource specification when you create a resource pool and use the corresponding amount of resource units to be allocated to the corresponding tenant.

Prerequisites

• Check whether the cluster has enough available resources to create a resource pool. For more information, see View tenant and resource information.
• When you create a resource pool, you must specify its resource specification. Before you create a resource pool, make sure that a resource specification exists. For more information about how to create a resource specification, see Step 1: Create a resource specification.

Procedure

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

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

2. Log in to the oceanbase database.

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

3. Query the DBA_OB_RESOURCE_POOLS view to obtain the configurations of resource pools.

   obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_RESOURCE_POOLS;
   

   The returned results are as follows:

   +------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   | RESOURCE_POOL_ID | NAME     | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST | REPLICA_TYPE |
   +------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   |                1 | sys_pool |         1 | 2025-05-16 11:30:47.004523 | 2025-05-16 11:30:47.011196 |          1 |              1 | zone1     | FULL         |
   |             1001 | pool001  |      1002 | 2025-05-16 11:31:11.735042 | 2025-05-16 11:31:19.924596 |          1 |           1001 | zone1     | FULL         |
   |             1002 | pool002  |      1004 | 2025-05-16 11:31:15.142237 | 2025-05-16 11:32:01.555002 |          1 |           1001 | zone1     | FULL         |
   +------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   3 rows in set
   

   For more information about the DBA_OB_RESOURCE_POOLS view, see DBA_OB_RESOURCE_POOLS.

4. Create a resource pool by using the CREATE RESOURCE POOL statement.

   The syntax is as follows:

   CREATE RESOURCE POOL poolname 
       UNIT [=] unitname, 
       UNIT_NUM [=] unitnum, 
       ZONE_LIST [=] ('zone' [, 'zone' ...]);
   

   Parameters:

   • UNIT: the resource specifications of the resource pool.
   • UNIT_NUM: The number of units in the resource pool within the destination zone. The value of this parameter must be less than the number of nodes in the destination zone. Additionally, each node can have at most one unit of the same tenant.
   • ZONE_LIST: describes the Zones of the resource pool. OceanBase Database creates UNIT_NUM OBUs in each zone specified by ZONE_LIST. The resource specifications of each OBU are set to the value specified by the UNIT parameter.

   For more information about the CREATE RESOURCE POOL statement, see CREATE RESOURCE POOL.

   For example:

   • Create a resource pool named mq_pool_01, create one unit in zone1, and set the unit's resource config to S1_unit_config.

     obclient(root@sys)[oceanbase]> CREATE RESOURCE POOL mq_pool_01 
                       UNIT='S1_unit_config', 
                       UNIT_NUM=1, 
                       ZONE_LIST=('zone1','zone2'); 
     

   • Create a resource pool named mq_pool_02, create two units in zone3, and set the resource config of each unit to S1_unit_config.

     obclient [oceanbase]> CREATE RESOURCE POOL mq_pool_02 
                       UNIT='S1_unit_config', 
                       UNIT_NUM=2, 
                       ZONE_LIST=('zone3'); 
     

5. Query the DBA_OB_RESOURCE_POOLS view to verify whether the resource pool is successfully created.

   Verify whether the mq_pool_01 resource pool is successfully created:

   obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.DBA_OB_RESOURCE_POOLS WHERE NAME = 'mq_pool_01';
   

   The query result is as follows:

   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-------------+--------------+
   | RESOURCE_POOL_ID | NAME       | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST   | REPLICA_TYPE |
   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-------------+--------------+
   |             1003 | mq_pool_01 |      NULL | 2026-01-10 22:37:08.212366 | 2026-01-10 22:37:08.212366 |          1 |           1002 | zone1;zone2 | FULL         |
   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-------------+--------------+
   1 row in set
   

   Verify whether the mq_pool_02 resource pool is successfully created:

   obclient(root@sys)[oceanbase]> SELECT * FROM DBA_OB_RESOURCE_POOLS WHERE NAME = 'mq_pool_02';
   

   The query result is as follows:

   obclient(root@sys)[oceanbase]> SELECT * FROM DBA_OB_RESOURCE_POOLS WHERE NAME = 'mq_pool_02';
   

   The results are as follows:

   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   | RESOURCE_POOL_ID | NAME       | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST | REPLICA_TYPE |
   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   |             1004 | mq_pool_02 |      NULL | 2026-01-10 21:53:58.258888 | 2026-01-10 22:10:36.404338 |          2 |           1002 | zone3     | FULL         |
   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   1 row in set
   

Step 3: Create a tenant

After a resource pool is created, it can be assigned to tenants based on business requirements.

Prerequisites

Make sure that a resource pool has been created. For more information about how to create a resource pool and resource units, see Create a resource pool.

Precautions

OceanBase Database supports two types of tenants: MySQL and Oracle compatible tenants. When you create a tenant, you must specify its type. After a tenant is created, you cannot modify its type. Therefore, plan the type of tenants before you create them.

Procedure

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

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

2. Log in to the oceanbase database.

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

3. Query the DBA_OB_TENANTS view to obtain the information of all tenants.

   obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, CREATE_TIME, MODIFY_TIME, PRIMARY_ZONE, LOCALITY, COMPATIBILITY_MODE, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS;
   

   The results are as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE | LOCALITY      | COMPATIBILITY_MODE | STATUS | TENANT_ROLE |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   |         1 | sys         | SYS         | 2026-01-07 15:06:23.115389 | 2026-01-07 15:06:23.115389 | RANDOM       | FULL{1}@zone1 | MYSQL              | NORMAL | PRIMARY     |
   |      1001 | META$1002   | META        | 2026-01-07 15:07:29.169646 | 2026-01-07 15:07:35.175576 | zone1        | FULL{1}@zone1 | MYSQL              | NORMAL | PRIMARY     |
   |      1002 | mysql001    | USER        | 2026-01-07 15:07:29.173619 | 2026-01-07 15:07:35.213500 | zone1        | FULL{1}@zone1 | MYSQL              | NORMAL | PRIMARY     |
   |      1003 | META$1004   | META        | 2026-01-07 15:07:39.123961 | 2026-01-07 15:07:45.464339 | zone1        | FULL{1}@zone1 | MYSQL              | NORMAL | PRIMARY     |
   |      1004 | oracle001   | USER        | 2026-01-07 15:07:39.123961 | 2026-01-07 15:07:45.487566 | zone1        | FULL{1}@zone1 | ORACLE             | NORMAL | PRIMARY     |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   5 rows in set
   

   For more information about the DBA_OB_TENANTS view, see DBA_OB_TENANTS.

4. (Optional) In the current version, you can create a tenant deployed in heterogeneous zones. However, the zone_deploy_mode parameter cannot be specified as hetero in the CREATE TENANT statement. To create a tenant deployed in heterogeneous zones, you can modify the parameter template as follows:

   obclient(root@sys)[oceanbase]> ALTER SYSTEM SET zone_deploy_mode = 'hetero' tenant = 'seed';
   

   Note

   Alternatively, you can first create a tenant deployed in homogeneous zones and then modify the tenant-level parameter zone_deploy_mode to hetero.

   After the command is executed, all subsequent tenants created will be deployed in heterogeneous zones.

5. Execute the CREATE TENANT statement to create a tenant.

   The syntax is as follows:

   CREATE TENANT [IF NOT EXISTS] tenant_name  
       PRIMARY_ZONE [=] zone,
       RESOURCE_POOL_LIST [=](poolname [, poolname...])
       [ENABLE_ARBITRATION_SERVICE = {true | false}]
       {SET | SET VARIABLES | VARIABLES} system_var_name = expr [,system_var_name = expr] ...
   

   Parameters:

   • IF NOT EXISTS: Optional clause. If a tenant with the specified name exists and you do not specify IF NOT EXISTS, an error is returned.

   • tenant_name: specifies the name of the tenant. You cannot specify an OceanBase Database keyword as the tenant name.

   • PRIMARY_ZONE: specifies the primary zone of the tenant.

     The PRIMARY_ZONE parameter specifies the priority of zones where the tenant provides read and write services. It is essentially a list of zones, where each zone's priority is specified. If the list contains multiple zones separated by semicolons (;), the zones have different priorities, from high to low. If the list contains multiple zones separated by commas (,), the zones have the same priority and the traffic is distributed across these zones.

     For example, primary_zone ='zone1;zone2,zone3' indicates that read and write services for the tenant are provided preferentially by zone1, with zone2 and zone3 at the same priority level.

     Note

     When you specify PRIMARY_ZONE, its value can be set to RANDOM (must be uppercase), indicating that all zones where the specified tenant resides are considered the first priority for PRIMARY_ZONE.

   • RESOURCE_POOL_LIST: the list of resource pools allocated to the tenant. This parameter is required. If the tenant has multiple resource pools:

     • In homogeneous zone mode, the resource pools must have the same UNIT_NUM value, which indicates the number of resource units.

     • In heterogeneous zone mode, the resource pools can have different UNIT_NUM values, but a tenant can have at most two distinct UNIT_NUM values. For example, if a tenant has three resource pools pool1, pool2, and pool3, and their unit_num values are 2, 4, and 4 respectively, and you change the unit_num value of pool3 to 1, the system will return an error message: More than two distinct unit_num in a single tenant not allowed.

     The list of zones where the replicas of a tenant are distributed is inherited from the ZONE_LIST attribute of the resource pool specified by RESOURCE_POOL_LIST. The number of replicas of the tenant is equal to the number of zones specified by the ZONE_LIST attribute of the resource pool specified by RESOURCE_POOL_LIST. The number of resource units in each zone is equal to the value of the UNIT_NUM attribute of the resource pool specified by RESOURCE_POOL_LIST. The unit config for the resource units of the tenant is determined by the UNIT attribute of the resource pool specified by RESOURCE_POOL_LIST.

     • In heterogeneous Zone mode, the UNIT_NUM values of a tenant's resource pools can be the same or different, but a tenant can have a maximum of two different UNIT_NUM values. For example, a tenant has three resource pools named pool1, pool2, and pool3, with unit_num values of 2, 4, and 4 respectively. If you change the unit_num of pool3 to 1, the system will return the More than two distinct unit_num in a single tenant not allowed error.

     A tenant's zone list is inherited from the ZONE_LIST attribute of the RESOURCE_POOL_LIST, and the number of replicas for the tenant is inherited from the number of zones in the ZONE_LIST attribute of the RESOURCE_POOL_LIST. The number of units per zone for the tenant is inherited from the UNIT_NUM attribute of the RESOURCE_POOL_LIST. Unit attributes, including resource specifications, of the tenant unit are inherited from the unit attributes of RESOURCE_POOL_LIST.

     Important

     Multiple resource pools in the same tenant cannot have overlapping ZONE_LIST settings.

   • ENABLE_ARBITRATION_SERVICE : Specifies whether to enable the arbitration service for a tenant. If not explicitly specified, the arbitration service is disabled for tenants created by default. If the arbitration service is not enabled for a tenant, you can enable it later. For more information, see Enable arbitration service.

     Functionality applicability

     This topic applies only to OceanBase Database Enterprise Edition. OceanBase Database Community Edition does not support the arbitration service.

   • system_var_name: a system variable or parameter.

     • ob_compatibility_control: specifies whether the behavior of a feature that has conflicting MySQL-compatible behaviors is consistent with that of MySQL 5.7 or MySQL 8.0. This variable must be specified when you create a MySQL-compatible tenant, and cannot be modified after the tenant is created. If you do not explicitly specify ob_compatibility_control, the behavior of the feature is consistent with that of MySQL 5.7.

   For more information about the CREATE TENANT statement, see CREATE TENANT.

   Here are some examples:

   • Create a tenant named mq_t1 (a MySQL-compatible tenant by default), with the resource pool specified as mq_pool_01, the primary zone specified as zone1, and all IP addresses allowed to connect to the database.

     The zone list of the tenant's replica distribution is inherited from the zone_list attribute of the resource_pool_list. The number of replicas of the tenant is inherited from the number of zones in the zone_list attribute of the resource_pool_list. The number of units in each zone for the tenant is inherited from the unit_num attribute of the resource_pool_list. The resource specifications of the tenant's units are inherited from the unit attribute of the resource_pool_list.

     obclient(root@sys)[oceanbase]> CREATE TENANT IF NOT EXISTS mq_t1 
                     PRIMARY_ZONE='zone1', 
                     RESOURCE_POOL_LIST=('mq_pool_01')
                     set OB_TCP_INVITED_NODES='%';
     

   • Create an Oracle-compatible tenant named oracle_tenant1, and explicitly specify ob_compatibility_mode='oracle'.

     obclient(root@sys)[oceanbase]>CREATE TENANT IF NOT EXISTS oracle_tenant1 
                     PRIMARY_ZONE='zone1', 
                     RESOURCE_POOL_LIST=('mq_pool_01')
                     SET OB_TCP_INVITED_NODES='%',
                     ob_compatibility_mode='oracle';
     

   • Create a heterogeneous deployment tenant named mq_t2 (default MySQL-compatible mode). Specify mq_pool_01 and mq_pool_02 as the resource pools, zone1,zone2 as the primary zone, and allow all IPs to connect to the database.

     obclient(root@sys)[oceanbase]> CREATE TENANT IF NOT EXISTS mq_t2 
                     PRIMARY_ZONE='zone1,zone2', 
                     RESOURCE_POOL_LIST=('mq_pool_01','mq_pool_02')
                     set OB_TCP_INVITED_NODES='%';
     

6. Query the DBA_OB_TENANTS view to verify whether the tenant is successfully created.

   For example, verify whether the tenant mq_t1 is successfully created:

   obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, CREATE_TIME, MODIFY_TIME, PRIMARY_ZONE, LOCALITY, COMPATIBILITY_MODE, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mq_t1';
   

   The return result is as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE | LOCALITY      | COMPATIBILITY_MODE | STATUS | TENANT_ROLE |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   |      1006 |  mq_t1      | USER        | 2026-01-11 15:06:23.115389 | 2026-01-11 15:06:23.115389 | zone1        | FULL{1}@zone1 | MYSQL              | NORMAL | PRIMARY     |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+--------------------+--------+-------------+
   1 row in set
   

   Verify whether the tenant mq_t2 is successfully created:

   obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, CREATE_TIME, MODIFY_TIME, PRIMARY_ZONE, LOCALITY, COMPATIBILITY_MODE, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE TENANT_NAME = 'mq_t2';
   

   The query result is as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE      | LOCALITY                                    | COMPATIBILITY_MODE | STATUS | TENANT_ROLE |
   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   |      1008 |  mq_t2      | USER        | 2026-01-11 21:55:14.624399 | 2026-01-11 13:50:39.955638 | zone1,zone2;zone3 | FULL{1}@zome1, FULL{1}@zone2, FULL{1}@zone3 | MYSQL              | NORMAL | PRIMARY     |
   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   1 row in set
   

7. After the tenant is created, try to log in to the tenant.

   By default, the password of the administrator user is empty. The administrator user is named root in MySQL-compatible mode and SYS in Oracle-compatible mode. You must change its password as soon as possible.

   The return result is as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE      | LOCALITY                                    | COMPATIBILITY_MODE | STATUS | TENANT_ROLE |
   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   |      1008 |  mq_t2      | USER        | 2026-01-11 21:55:14.624399 | 2026-01-11 13:50:39.955638 | zone1,zone2;zone3 | FULL{1}@zome1, FULL{1}@zone2, FULL{1}@zone3 | MYSQL              | NORMAL | PRIMARY     |
   +-----------+-------------+-------------+----------------------------+----------------------------+-------------------+---------------------------------------------+--------------------+--------+-------------+
   1 row in set
   

8. After the tenant is created, you can log in to the tenant.

   The password of the default administrator user (root for MySQL-compatible tenants and sys for Oracle-compatible tenants) is empty. You need to change the password of the administrator user as soon as possible.

   • MySQL-compatible mode

     1. Log in to the root user of the mq_t1 tenant.

        obclient -h172.30.xx.xx -P2883 -uroot@mq_t1#cluster  -A
        

     2. Execute the following statement to change the password of the root user.

        obclient(root@mq_t1)[(none)]> ALTER USER root IDENTIFIED BY '****';
        Query OK, 0 rows affected
        

   • Oracle-compatible mode

     1. Log in to the SYS user of the moracle_tenant1 tenant.

        obclient -h172.30.xx.xx -P2883 -usys@oracle_tenant1#cluster  -A
        

     2. Execute the following statement to change the password of the SYS user.

        obclient(syst@oracle_tenant1)[SYS]> ALTER USER sys IDENTIFIED BY ****;
        Query OK, 0 rows affected
        

9. After the password is changed, log in to the tenant again.

   • MySQL-compatible mode

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

   • Oracle-compatible mode

     obclient -h172.30.xx.xx -P2883 -usys@oracle_tenant1#cluster -p**** -A
     

What to do next

After you create a tenant, you can log in as the administrator and connect to the database. For more information about how to connect to the database, see Overview of methods for connecting to a database (MySQL mode) and Overview of methods for connecting to a database (Oracle mode). If you want to log in as a normal user, you must create a normal user for the tenant and grant privileges to the user. For more information about how to create a user and grant privileges to the user, see User and privilege management.

References

After you create a tenant, you can view and maintain the tenant configuration. For more information, see:

• View tenant and resource information

• Modify tenant properties

• Delete a tenant

• Restore a tenant

• View and set a tenant whitelist