Create a tenant

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.

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

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 over-allocation parameter, specifies the over-allocation percentage of CPU resources. OceanBase Database supports the over-allocation of only CPU resources. CPU resources can be over-allocated 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 over-allocation 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 type. The tenant type cannot be modified after a tenant is created. Therefore, properly plan the tenant type 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 on 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_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.

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,  
       [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. The minimum value is 1 GB. OceanBase Database does not support memory over-allocation 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 minimum values of MAX_IOPS and MIN_IOPS are 1024, and the value of MAX_IOPS must be greater than or equal to that of MIN_IOPS. If you do not specify these parameters, the system automatically calculates the values based on the CPU specifications.

     The system automatically calculates the values for the IOPS parameters based on the following rules:

     • If both MIN_IOPS and MAX_IOPS are not specified, the system automatically calculates their values based on the value of MIN_CPU by using this rule: One CPU core corresponds to 10,000 IOPS, which means MAX_IOPS = MIN_IOPS = MIN_CPU * 10000.

       • 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, MIN_IOPS uses the value of MAX_IOPS. Similarly, if only MIN_IOPS is specified, MAX_IOPS uses the value of MIN_IOPS.

       • 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 consists of one CPU core, 2 GB of memory, and 6 GB of log disk space.

   obclient [oceanbase]> CREATE RESOURCE UNIT S1_unit_config
                   MEMORY_SIZE = '2G',
                   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';
   +----------------+----------------+----------------------------+----------------------------+---------+---------+-------------+---------------+----------+----------+-------------+
   | 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 |  2147483648 |    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

1. Log on 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;
   +------------------+--------------------------+-----------+----------------------------+----------------------------+------------+----------------+-------------------+--------------+
   | 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 |