Create a tenant|V4.3.1|OceanBase Database| docs|Distributed Database

OceanBase Database is a native distributed database management system that supports multiple instances running concurrently in a single database. To get started, the first step typically involves creating a tenant, or a new instance of a database. Once created, tenants can be used as conventional standalone databases. This topic aims to guide you through the process of creating a tenant in OceanBase Database.

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.

Create a unit config: When you create a unit config, you only define the specification and do not allocate resources. You can query the DBA_OB_UNIT_CONFIGS view for all unit configs. A unit config can be reused. We recommend that you define different unit configs such as small specification, medium specification, and large specification to simplify O&M. When an urgent scale-up is required due to insufficient tenant resources, you cannot directly adjust the original unit config. Instead, you must create a new unit config or replace the original unit config with a higher-level one.
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.
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).

Note

OceanBase Database V4.0 significantly improves the resource management feature based on extensive practices and experience in OceanBase Database V3.x.

You can manage resource items such as the CPU, memory, log disk space, and IOPS based on resource units. Other resource items such as the data disk space and session quantity cannot be managed based on resource units. To ensure compatibility with the O&M tools and test cases of OceanBase Database V3.x, the CREATE RESOURCE UNIT statement allows you to specify the MAX_DISK_SIZE and MAX_SESSION_NUM parameters, which do not take effect or return errors.
Overprovisioning of CPU resources is supported and controlled by using the resource_hard_limit parameter. In the GV$OB_SERVERS view, the CPU_CAPACITY and CPU_CAPACITY_MAX fields respectively indicate the total CPU capacity of nodes and the maximum CPU capacity that supports overprovisioning. The value of CPU_CAPACITY_MAX is calculated as follows: CPU_CAPACITY × resource_hard_limit.
Memory overprovisioning is no longer supported because it will cause a tenant to become unstable.
Log disk space isolation is supported between tenants. The system reserves specific log disk space for each tenant. This prevents the log disk from being exhausted by a large number of writes in a single tenant and thereby affects other tenants, which occurs in OceanBase Database V3.x.
IOPS isolation is supported between tenants. The system introduces three IOPS parameters: MIN_IOPS, MAX_IOPS, and IOPS_WEIGHT. These parameters do not need to be specified and are automatically calculated by the system based on the CPU specifications. If the sum of the MIN_IOPS values of all resource units on a node exceeds the maximum IOPS of the disk, IOPS resources are allocated based on the weight specified by IOPS_WEIGHT.
A meta tenant has no independent resource unit. By default, the system reserves resources for the corresponding meta tenant when a user tenant is created. The resources required by the meta tenant are deducted from those of the user tenant. The default resource settings are used for the meta tenant and cannot be modified.
When you create a unit config, the CPU specifications and memory size are required. Values of other parameters can be automatically calculated. The log disk space is calculated based on the memory size, and the IOPS size is calculated based on the CPU specifications.

Procedure

Log on to the sys tenant of the cluster as the root user.

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

Access the database named oceanbase.
```
USE oceanbase;
```

Query the DBA_OB_UNIT_CONFIGS view for information about existing unit configs.

obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_UNIT_CONFIGS;
+----------------+-------------------------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
| UNIT_CONFIG_ID | NAME                          | CREATE_TIME                | MODIFY_TIME                | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | MAX_IOPS | MIN_IOPS | IOPS_WEIGHT |
+----------------+-------------------------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
|              1 | sys_unit_config               | 2022-12-20 17:50:17.035504 | 2022-12-20 17:50:17.035504 |       1 |       1 | 14495514624 |   14495514624 |    10000 |    10000 |           1 |
|           1001 | config_mysql001_zone1_S1_okz  | 2022-12-20 18:04:31.547715 | 2022-12-20 18:04:31.547715 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
|           1002 | config_mysql001_zone2_S1_pme  | 2022-12-20 18:04:31.561335 | 2022-12-20 18:04:31.561335 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
|           1003 | config_mysql001_zone3_S1_jsu  | 2022-12-20 18:04:31.564510 | 2022-12-20 18:04:31.564510 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
|           1013 | config_oracle001_zone3_S1_exu | 2022-12-26 18:28:37.969047 | 2022-12-26 18:28:37.969047 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
|           1014 | config_oracle001_zone2_S1_hli | 2022-12-26 18:28:37.972194 | 2022-12-26 18:28:37.972194 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
|           1015 | config_oracle001_zone1_S1_owy | 2022-12-26 18:28:37.976446 | 2022-12-26 18:28:37.976446 |     1.5 |     1.5 |  6442450944 |   19327352832 |    15000 |    15000 |           1 |
+----------------+-------------------------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
7 rows in set

For more information about the DBA_OB_UNIT_CONFIGS view, see DBA_OB_UNIT_CONFIGS.

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,  
    [LOG_DISK_SIZE [=] 'size_value',]
    [MAX_IOPS [=] iops_num,]
    [MIN_CPU [=] cpu_num,]
    [MIN_IOPS [=] iops_num];
```
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.
  
  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.
- 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.
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;
```

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';
+----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
| UNIT_CONFIG_ID | NAME           | CREATE_TIME                | MODIFY_TIME                | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE | MAX_IOPS | MIN_IOPS | IOPS_WEIGHT |
+----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
|           1020 | S1_unit_config | 2023-01-10 22:31:38.805862 | 2023-01-10 22:31:38.805862 |       1 |       1 |  5368709120 |    6442450944 |    10000 |    10000 |           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

Log on to the sys tenant of the cluster as the root user.

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

Access the database named oceanbase.
```
obclient [(none)]> USE oceanbase;
```

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

obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_RESOURCE_POOLS;
+------------------+--------------------------+-----------+----------------------------+----------------------------+------------+----------------+-------------------+--------------+
| RESOURCE_POOL_ID | NAME                     | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST         | REPLICA_TYPE |
+------------------+--------------------------+-----------+----------------------------+----------------------------+------------+----------------+-------------------+--------------+
|                1 | sys_pool                 |         1 | 2022-12-20 17:50:17.038641 | 2022-12-20 17:50:17.045453 |          1 |              1 | zone1;zone2;zone3 | FULL         |
|             1001 | pool_mysql001_zone3_jsu  |      1002 | 2022-12-20 18:04:31.607227 | 2022-12-20 18:04:31.692836 |          1 |           1003 | zone3             | FULL         |
|             1002 | pool_mysql001_zone1_okz  |      1002 | 2022-12-20 18:04:31.617087 | 2022-12-20 18:04:31.691827 |          1 |           1001 | zone1             | FULL         |
|             1003 | pool_mysql001_zone2_pme  |      1002 | 2022-12-20 18:04:31.621327 | 2022-12-20 18:04:31.692836 |          1 |           1002 | zone2             | FULL         |
|             1013 | pool_oracle001_zone3_exu |      1010 | 2022-12-26 18:28:37.979539 | 2022-12-26 18:28:38.059505 |          1 |           1013 | zone3             | FULL         |
|             1014 | pool_oracle001_zone1_owy |      1010 | 2022-12-26 18:28:37.988964 | 2022-12-26 18:28:38.058440 |          1 |           1015 | zone1             | FULL         |
|             1015 | pool_oracle001_zone2_hli |      1010 | 2022-12-26 18:28:37.994241 | 2022-12-26 18:28:38.059505 |          1 |           1014 | zone2             | FULL         |
+------------------+--------------------------+-----------+----------------------------+----------------------------+------------+----------------+-------------------+--------------+
7 rows in set

For more information about the DBA_OB_RESOURCE_POOLS view, see DBA_OB_RESOURCE_POOLS.

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, a resource unit for each of zone1 and zone2, and a unit config named S1_unit_config for the resource units.
```
obclient [oceanbase]> CREATE RESOURCE POOL mq_pool_01
                UNIT='S1_unit_config',
                UNIT_NUM=1,
                ZONE_LIST=('zone1','zone2');
```

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

obclient [oceanbase]> SELECT * FROM DBA_OB_RESOURCE_POOLS WHERE NAME = 'mq_pool_01';
+------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-------------+--------------+
| RESOURCE_POOL_ID | NAME       | TENANT_ID | CREATE_TIME                | MODIFY_TIME                | UNIT_COUNT | UNIT_CONFIG_ID | ZONE_LIST   | REPLICA_TYPE |
+------------------+------------+-----------+----------------------------+----------------------------+------------+----------------+-------------+--------------+
|             1024 | mq_pool_01 |      NULL | 2023-01-10 22:37:08.212366 | 2023-01-10 22:37:08.212366 |          1 |           1020 | zone1;zone2 | 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

Procedure

Log on to the sys tenant of the cluster as the root user.

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

Access the database named oceanbase.
```
USE oceanbase;
```

Query the DBA_OB_TENANTS view for information about all tenants.

obclient [oceanbase]> SELECT * FROM oceanbase.DBA_OB_TENANTS;
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
| 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 |
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
|         1 | sys         | SYS         | 2023-05-17 18:10:19.940353 | 2023-05-17 18:10:19.940353 | RANDOM       | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |
|      1001 | META$1002   | META        | 2023-05-17 18:15:21.455549 | 2023-05-17 18:15:36.639479 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |
|      1002 | mysql001    | USER        | 2023-05-17 18:15:21.461276 | 2023-05-17 18:15:36.669988 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1684395321137516636 | 1684395321137516636 | 1684395321052204807 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |
|      1003 | META$1004   | META        | 2023-05-17 18:18:19.927859 | 2023-05-17 18:18:36.443233 | zone1        | FULL{1}@zone1 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 |                NULL |                NULL |                NULL |                NULL | NOARCHIVELOG | DISABLED                   |
|      1004 | oracle001   | USER        | 2023-05-17 18:18:19.928914 | 2023-05-17 18:18:36.471606 | zone1        | FULL{1}@zone1 | NULL              | ORACLE             | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1684395321137558760 | 1684395321137558760 | 1684395320951813345 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+---------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
5 rows in set

For more information about the DBA_OB_TENANTS view, see DBA_OB_TENANTS.

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 can contain at most 128 characters in length and only letters, digits, and underscores (_). It must start with a letter or underscore.
- PRIMARY_ZONE: the primary zone of the tenant. The primary zone modification feature provided in OceanBase Database V4.0 still needs improvement. It cannot implement the scaling of the read and write capabilities for existing tables or partitions in a tenant. We recommend that you properly set the PRIMARY_ZONE attribute when you create a 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 in uppercase to randomly select any zone with the highest priority as the primary zone.
- RESOURCE_POOL_LIST: the list of resource pools allocated to the tenant. This parameter is required. If multiple resource pools are specified, make sure that the UNIT_NUM parameter is set to the same value for the resource pools.
  
  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 topic applies only to OceanBase Database Enterprise Edition. At present, OceanBase Database Community Edition does not support the arbitration service feature.
- system_var_name: a system variable or parameter.
  - OB_TCP_INVITED_NODES: the allowlist of client IP addresses that are allowed to connect to this 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 modify the tenant allowlist.
  - OB_COMPATIBILITY_MODE: the compatibility mode of the tenant, which can be specified only when the tenant is created. Valid values: MySQL and Oracle. If OB_COMPATIBILITY_MODE is not specified, the default compatibility mode is MySQL.
For more information about the CREATE TENANT statement, see CREATE TENANT.

Here is an example:
- Create a tenant named mq_t1, which is a MySQL tenant by default. Set the number of replicas to 3, resource pool to mq_pool_01, and primary zone to zone1, and allow all IP addresses to connect to the tenant.
  
  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 specify 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';
```

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';
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+------------------------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
| 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 |
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+------------------------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
|      1006 | mq_t1       | USER        | 2023-05-18 15:48:57.447657 | 2023-05-18 15:49:12.857944 | zone1;zone2  | FULL{1}@zone1, FULL{1}@zone2 | NULL              | MYSQL              | NORMAL | NO            | NO     | PRIMARY     | NORMAL            |                0 | 1684396167132057328 | 1684396167132057328 | 1684396167051160964 | 4611686018427387903 | NOARCHIVELOG | DISABLED                   |
+-----------+-------------+-------------+----------------------------+----------------------------+--------------+------------------------------+-------------------+--------------------+--------+---------------+--------+-------------+-------------------+------------------+---------------------+---------------------+---------------------+---------------------+--------------+----------------------------+
1 row in set

After the tenant is created, try to log on to the tenant.

By default, the password of the administrator user is empty. The administrator user is named root in MySQL mode and SYS in Oracle mode. You must change its password as soon as possible.
- MySQL mode
  1. Log on as the root user to 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 [(none)]> ALTER USER root IDENTIFIED BY '****';
Query OK, 0 rows affected
```
- Oracle mode
  1. Log on as the SYS user to 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 [SYS]> ALTER USER sys IDENTIFIED BY ****;
Query OK, 0 rows affected
```

After the password is changed, log on to the tenant again.

MySQL mode

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

Oracle 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 on to the database as an administrator. For more information, see Database connection overview (MySQL mode) and Database connection overview (Oracle mode). To log on 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:

Customer Stories

Documentation

Create a tenant

Procedure

Resource planning

Considerations

Step 1: Create a unit config

Note

Step 2: Create a resource pool

Step 3: Create a tenant

Notice

Notice

Applicability

What to do next

References