Create a tenant

OceanBase Database is a native distributed database management system that can run multiple database instances in a database. First, you must create a tenant (database instance) and then use the database instance as a conventional standalone database. This topic describes how to create a tenant.

Procedure

In OceanBase Database, you can create only user tenants. The sys tenant is automatically created when you create a cluster. The creation of a user tenant involves a series of operations. First, create a unit config, then create a resource pool based on the unit config, and finally create a tenant and specify the resource pool for it. The creation sequence is: unit config -> resource pool -> tenant.

1. Create a unit config: Creating a unit config is simply a definition and does not actually allocate any resources. You can view all unit configs through the DBA_OB_UNIT_CONFIGS view. unit configs can be reused, so 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 unit config and one tenant needs an emergency resource expansion, you cannot directly modify the original specification. Instead, you need to create a new, independent unit config and switch to it, or directly switch to a larger specification.

2. Create a resource pool: When you create a resource pool, resource units are created. Resources are allocated to the resource units based on the unit config. If the resources reserved for a node are insufficient, the creation will fail. You can query the GV$OB_SERVERS view for the resource allocation information about all nodes. After a resource pool is created, you can query the DBA_OB_RESOURCE_POOLS and DBA_OB_UNITS views for the resource pool and its resource units. A resource pool cannot be reused. After a tenant is created, the specified resource pool will be allocated to the tenant.

3. Create a tenant: When you create a tenant, you can specify RESOURCE_POOL_LIST to allocate a resource pool to the tenant. You can query the DBA_OB_TENANTS view for all tenants. Each zone can use a resource pool with a different unit config. Alternatively, all zones can use the same resource pool with the same unit config. Besides the resource pool list, you must also set other important attributes and system variables such as the compatibility mode, primary zone, locality, and connection allowlist. The resource pool list attribute is required when you create a tenant. The password of the root user for a newly created tenant is empty. We recommend that you set a password before you use the root user.

Resource planning

Before you create a tenant, you must perform resource planning. After the tenant is created, resource adjustment is complex. You must deeply understand business scenarios when you participate in the design of the database architecture.

Take note of the following resource planning rules:

• Resources must be reserved on each node for emergency scale-up of a tenant.

• If the business system involves a large number of writes, set a large memory size and log disk size. Businesses that consume a large amount of CPU resources must be distributed to different nodes to avoid causing a load imbalance among nodes or hotspot nodes, which affects services.

• The cluster parameter resource_hard_limit, also referred to as the overprovisioning parameter, specifies the overprovisioning percentage of CPU resources. OceanBase Database supports the overprovisioning of only CPU resources. CPU resources can be overprovisioned in off-peak hours between different tenants in the same cluster to improve overall resource utilization. If the tenants reach a peak at the same time, the overprovisioning of CPU resources may cause the tenants to contend for CPU resources.

• 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 tenant modes: MySQL tenant and Oracle tenant. When you create a tenant, you must specify the tenant mode. The tenant mode cannot be modified after a tenant is created. Therefore, properly plan the tenant mode before you create a tenant.

Step 1: Create a unit config

A unit config defines the resource items such as the CPU, memory, disk space, and input/output operations per second (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. Access the database named oceanbase.

   obclient> USE oceanbase;
   

3. Query the DBA_OB_UNIT_CONFIGS view for information about existing unit configs.

   obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS;
   

   The query 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. Execute the CREATE RESOURCE UNIT statement to create a unit config.

   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'];
   

   The parameters are described as follows:

   When you create a unit config, the MAX_CPU and MEMORY_SIZE parameters 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 both MIN_IOPS and MAX_IOPS are not specified, the system automatically allocates IOPS resources based on IOPS_WEIGHT. In this case:

       • The values of both MIN_IOPS and MAX_IOPS are INT64_MAX.

       • If IOPS_WEIGHT is not specified, IOPS_WEIGHT = MIN_CPU.

       • If IOPS_WEIGHT is specified, the specified value takes precedence.

     • If only MAX_IOPS is specified, the MIN_IOPS value is the same as the MAX_IOPS value. If only MIN_IOPS is specified, the MAX_IOPS value is the same as the MIN_IOPS value. In this case:

       • If IOPS_WEIGHT is not specified, the value is 0 by default.

   • MAX_NET_BANDWIDTH: the maximum network bandwidth that each unit of a tenant can use, with a minimum value of 1 M. If not specified, the default value is INT64_MAX.

   • NET_BANDWIDTH_WEIGHT: the network bandwidth weight of the tenant’s unit, which is used to calculate the proportion of bandwidth allocated to each tenant on each OBServer. The minimum value is 0. If not specified, the system will automatically calculate the value of NET_BANDWIDTH_WEIGHT according to the following rules:

     • If MAX_NET_BANDWIDTH is specified, then the value of NET_BANDWIDTH_WEIGHT is 0.

     • If MAX_NET_BANDWIDTH is not specified, then NET_BANDWIDTH_WEIGHT = MIN_CPU.

   • LOG_DISK_SIZE: the log disk size. OceanBase Database V4.0 manages the log disk based on tenants. The system reserves specific log disk space for each tenant to implement log disk space isolation between tenants. If LOG_DISK_SIZE is not specified, its default value is three times that of the memory size. The minimum value is 2 GB.

   • OceanBase Database V4.0 supports IOPS isolation between tenants. The IOPS resources are determined by the MAX_IOPS, MIN_IOPS, and IOPS_WEIGHT parameters. By default, you do not need to specify the IOPS parameters. The system automatically calculates the parameter values based on the CPU specification.

   • When you specify a value for a parameter, you can use a number without quotation marks ('), a number and a unit enclosed in quotation marks, or a number enclosed in quotation marks, for example, '1T', '1G', '1M', or '1K'.

     The parameters are described as follows:

     • For integer parameters such as MAX_CPU, MIN_CPU, MAX_IOPS, MIN_IOPS, and IOPS_WEIGHT, if the parameter value is a number and a letter enclosed in quotation marks, the letter is interpreted in the decimal system. For example, '1K' = 1000, and '1M' = 1000000. For example, MAX_IOPS='2K' is equivalent to MAX_IOPS=2000.

       If you use a number enclosed in quotation marks, the meaning is the same as that without quotation marks. For example, '100' = 100, and '1000' = 1000.

     • For capacity parameters such as MEMORY_SIZE and LOG_DISK_SIZE, if you use a number and a unit enclosed in quotation marks, the unit is interpreted in the binary system. This is equivalent to the case in which you use only a number without quotation marks. For example, '1K' = 1024, and '1M' = 1024 * 1024.

       If you use a number enclosed in quotation marks, the unit is MB by default, For example, '100' = '100M' = 100 * 1024 * 1024.

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

   Here is an example:

   Create a unit config named S1_unit_config that contains one CPU core, 5 GB of memory, and 6 GB of log disk space.

   obclient [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 verify whether the unit config is successfully created.

   obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS WHERE NAME = 'S1_unit_config';
   

   The query 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 you create a unit config, you can specify this unit config when you create a resource pool. The unit config defines the sizes of resource items in the resource units, which are finally allocated to corresponding tenants.

Prerequisites

• Sufficient resources are available in the cluster to create a resource pool. For more information, see View tenant and resource information.
• A unit config is available. When you create a resource pool, you must specify its unit config. For more information about how to create a unit config, see Step 1: Create a unit config.

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. Access the database named oceanbase.

   obclient [(none)]> USE oceanbase;
   

3. Query the DBA_OB_RESOURCE_POOLS view for the configuration information about resource pools.

   obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_RESOURCE_POOLS;
   

   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 |
   +------------------+----------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   |                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. Execute the CREATE RESOURCE POOL statement to create a resource pool.

   The syntax is as follows:

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

   The parameters are described as follows:

   • UNIT: the unit config for the resource pool.
   • UNIT_NUM: the number of resource units of this resource pool in the target zone. The value must be smaller than the number of nodes in the target zone. Each tenant can have only one resource unit distributed on a node.
   • ZONE_LIST: the distribution of the resource pool in zones. OceanBase Database creates a number of resource units in each zone specified by ZONE_LIST. This number is specified by the UNIT_NUM parameter. The unit config of each resource unit is the one specified by the UNIT parameter.

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

   Here is an 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 [oceanbase]> CREATE RESOURCE POOL mq_pool_01 
                   UNIT='S1_unit_config', 
                   UNIT_NUM=1, 
                   ZONE_LIST=('zone1'); 
   

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

   obclient [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 | 2025-05-28 10:31:04.926243 | 2025-05-28 10:31:04.926243 |          1 |           1002 | zone1     | FULL         |
   +------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-----------+--------------+
   1 row in set
   

Step 3: Create a tenant

After you create a resource pool, you can allocate it to a tenant based on business needs.

Prerequisites

A resource pool is available. For more information about how to create a resource pool and resource unit, see Step 2: Create a resource pool.

Considerations

OceanBase Database supports two tenant modes: MySQL tenant and Oracle tenant. When you create a tenant, you must specify the tenant mode. The tenant mode cannot be modified after a tenant is created. Therefore, properly plan the tenant mode before you create a tenant.

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. Access the database named oceanbase.

   USE oceanbase;
   

3. Query the DBA_OB_TENANTS view for information about all tenants.

   obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANTS;
   

   The query result is as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE | LOCALITY      | PREVIOUS_LOCALITY | COMPATIBILITY_MODE | STATUS | IN_RECYCLEBIN | LOCKED | TENANT_ROLE | SWITCHOVER_STATUS | SWITCHOVER_EPOCH | SYNC_SCN            | REPLAYABLE_SCN      | READABLE_SCN        | RECOVERY_UNTIL_SCN  | LOG_MODE     | ARBITRATION_SERVICE_STATUS | UNIT_NUM | COMPATIBLE | MAX_LS_ID | RESTORE_DATA_MODE |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   |         1 | sys         | SYS         | 2025-05-16 11:30:47.031736 | 2025-05-16 11:30:47.031736 | RANDOM       | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |         1 | NORMAL            |
   |      1001 | META$1002   | META        | 2025-05-16 11:31:19.917288 | 2025-05-16 11:31:31.619972 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |         1 | NORMAL            |
   |      1002 | mysql001    | USER        | 2025-05-16 11:31:19.921431 | 2025-05-16 11:31:31.671475 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1748398983043914000 | 1748398983043914000 | 1748398982543622004 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |      1001 | NORMAL            |
   |      1003 | META$1004   | META        | 2025-05-16 11:32:01.550769 | 2025-05-16 11:32:15.460704 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |         1 | NORMAL            |
   |      1004 | oracle001   | USER        | 2025-05-16 11:32:01.551827 | 2025-05-16 11:32:15.539634 | zone1        | FULL{1}@zone1 | NULL              | ORACLE             | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1748398983043914001 | 1748398983043914001 | 1748398983043914001 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |      1001 | NORMAL            |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   5 rows in set
   

   For more information about the DBA_OB_TENANTS view, see DBA_OB_TENANTS.

4. 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] ...
   

   The parameters are described as follows:

   • IF NOT EXISTS: optional. If the tenant to be created already exists and IF NOT EXISTS is not specified, an error is returned.

   • tenant_name: the name of the tenant to be created. It cannot contain reserved keywords of OceanBase Database.

   • PRIMARY_ZONE: the primary zone of the tenant.

     PRIMARY_ZONE specifies the priorities for the zones of the tenant to provide read and write services. The value is a list of zones. In the list, zones separated with semicolons (;), are arranged in descending order of priority, and those separated with commas (,) have the same priority, indicating that the traffic is distributed to multiple zones that provide services at the same time.

     For example, primary_zone='zone1;zone2,zone3' indicates that zone1 of the tenant preferentially provides read and write services and has a higher priority than zone2 and zone3, which have the same priority.

     Notice

     You can set PRIMARY_ZONE to RANDOM (uppercase) to specify all zones of the tenant as top-priority zones in 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, they must have the same UNIT_NUM value, which indicates the number of resource units.

     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.

     Notice

     The zones of resource pools allocated to the same tenant must not overlap.

   • ENABLE_ARBITRATION_SERVICE: specifies whether to enable the arbitration service for the tenant. If this parameter is not specified, the arbitration service is disabled by default. You can enable the arbitration service after the tenant is created. For more information, see Enable the arbitration service.

     Applicability

     This parameter 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_tcp_invited_nodes: the allowlist of client IP addresses allowed to connect to the tenant. In the example, the percent sign (%) indicates that all clients can connect to this tenant. If ob_tcp_invited_nodes is not specified, by default, the tenant is accessible only to the clients on the server where the tenant is hosted. For more information about the connection allowlist, see View and set the tenant allowlist.

     • ob_compatibility_mode: the compatibility mode of the tenant, which can be specified only when the tenant is created. Valid values are mysql and oracle. If ob_compatibility_mode is not specified, the default compatibility mode is MySQL.

     • ob_compatibility_control: specifies whether OceanBase Database is to keep compatible with MySQL 5.7 or MySQL 8.0 when a MySQL compatibility behavior conflict occurs. You must specify this variable when you create a tenant in MySQL-compatible mode. It cannot be modified after the tenant is created. If ob_compatibility_control is not specified, OceanBase Database keeps compatible with MySQL 5.7 by default.

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

   Here are two examples:

   • Create a tenant named mq_t1 (by default, a MySQL-compatible tenant), assign the resource pool mq_pool_01, set the primary zone to zone1, and allow all IPs to connect to the database.

     The list of zones where the tenant is 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 the same as 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.

     obclient [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 tenant named oracle_tenant1. You must explicitly set ob_compatibility_mode to 'oracle'.

     obclient [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';
     

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

   obclient [oceanbase]> SELECT * FROM DBA_OB_TENANTS WHERE TENANT_NAME = 'mq_t1';
   

   The query result is as follows:

   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME                | MODIFY_TIME                | PRIMARY_ZONE | LOCALITY      | PREVIOUS_LOCALITY | COMPATIBILITY_MODE | STATUS | IN_RECYCLEBIN | LOCKED | TENANT_ROLE | SWITCHOVER_STATUS | SWITCHOVER_EPOCH | SYNC_SCN            | REPLAYABLE_SCN      | READABLE_SCN        | RECOVERY_UNTIL_SCN  | LOG_MODE     | ARBITRATION_SERVICE_STATUS | UNIT_NUM | COMPATIBLE | MAX_LS_ID | RESTORE_DATA_MODE |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   |      1002 | mq_t1       | USER        | 2025-05-28 11:23:36.528377 | 2025-05-28 11:23:59.809322 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1748402687353930000 | 1748402687353930000 | 1748402687353930000 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |        1 | 4.3.4.0    |      1001 | NORMAL            |
   +-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+----------+------------+-----------+-------------------+
   1 row in set
   

6. 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.

   • MySQL-compatible mode

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

        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 [(none)]> ALTER USER root IDENTIFIED BY '****';
        Query OK, 0 rows affected
        

   • Oracle-compatible mode

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

        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 [SYS]> ALTER USER sys IDENTIFIED BY ****;
        Query OK, 0 rows affected
        

7. 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 to the database as an administrator. For more information, see Overview (MySQL-compatible mode) and Overview (Oracle-compatible mode). To log in as a regular user, you must create a regular user for the tenant and grant privileges to the user. For more information, see Users and permissions.

References

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

• View tenant and resource information

• Modify attributes of a tenant

• Drop a tenant

• Restore a tenant

• View and set the tenant allowlist