Experience multi-tenancy and resource isolation

Multi-tenancy is a core capability that distinguishes OceanBase Database from traditional single-instance databases. OceanBase adopts a single-cluster, multi-tenant architecture, which pools instance resources at the cluster level. Each tenant is an instance (analogous to a MySQL instance). Data, permissions, and resources are completely isolated between tenants. Each tenant has its own user system and dedicated resources such as CPU and memory. Through the multi-tenancy mechanism, a single cluster can host multiple businesses simultaneously, efficiently utilize resources while ensuring availability and performance, and enable on-demand elastic scaling.

This topic covers the following experiences:

• Understand the multi-tenant architecture: Master the basic relationships between unit config, resource pool, unit, and tenant.
• Create different business tenants: Create mutually isolated tenants for different businesses and configure different resource specifications such as CPU, memory, and storage.
• Verify tenant isolation: Execute queries in different tenants to observe the boundaries of data and permissions.
• Adjust resource specifications online: Experience online scaling of tenant resources, which is transparent to the business during the change process.
• Stress test and observe tenant performance: Execute a standard stress test in a business tenant to verify that the tenant can handle business traffic normally and understand the isolation logic of resource quotas.

Prerequisites

Before you proceed, ensure the following conditions are met:

Overview of the multi-tenant architecture

OceanBase Database achieves resource isolation through tenants, ensuring that each instance of a database service is unaware of the existence of others. It also ensures tenant data security through permission control. A tenant is a logical concept that serves as both a container for various database objects and a container for resources (such as CPU, memory, and I/O). To some extent, it is equivalent to the "instance" concept in traditional databases.

OceanBase uses the following three concepts to manage the available resources for each tenant:

Due to its distributed architecture, an OceanBase tenant can be flexibly defined across dimensions such as resource specifications, resource pools, replica types, and replica distribution. Therefore, when creating a tenant, you must follow the sequence of resource configuration → resource pool → tenant:

Unit config ─────────────> Resource pool ─────────────> Tenant
Define the specifications   Combine resource units       Allocate to businesses

Create tenants for different businesses

The following example simulates a scenario where a cluster hosts two businesses simultaneously: create a smaller-specification tenant tenant1 for Business A and a larger-specification tenant tenant2 for Business B. Both share cluster resources but are isolated from each other.

Procedure

1. Log in to the sys tenant of the cluster as the root user (the password is randomly generated during deployment; see the prerequisites above for retrieval):

   obclient -h127.0.0.1 -uroot@sys -P2881 -p -A oceanbase
   

2. Create two resource configurations with unit specifications of 1C2G and 2C4G, respectively. Adjust them based on your actual machine configuration:

   obclient [oceanbase]> CREATE RESOURCE UNIT unit1 MAX_CPU=1, MIN_CPU=1, MEMORY_SIZE='2G';
   obclient [oceanbase]> CREATE RESOURCE UNIT unit2 MAX_CPU=2, MIN_CPU=2, MEMORY_SIZE='4G';
   

   Key parameters:

   Parameter	Description
   MAX_CPU	The upper limit of CPU that the resource unit can provide. Required.
   MIN_CPU	The lower limit of CPU that the resource unit can provide. Default equals MAX_CPU.
   MEMORY_SIZE	The memory specification that the resource unit can provide. Required.
   LOG_DISK_SIZE	Log disk space. Defaults to 3 times the memory size, with a minimum of 2 GB.
   MAX_IOPS / MIN_IOPS	The upper and lower limits of IOPS that the resource unit can provide. The minimum value is 1024 for both. If not specified, the default is INT64_MAX.

3. Create a resource pool and associate it with the resource configuration. For a single-node cluster, the ZONE_LIST is ('zone1'):

   obclient [oceanbase]> CREATE RESOURCE POOL pool1 UNIT='unit1', UNIT_NUM=1, ZONE_LIST=('zone1');
   obclient [oceanbase]> CREATE RESOURCE POOL pool2 UNIT='unit2', UNIT_NUM=1, ZONE_LIST=('zone1');
   

   Key parameters:

   Parameter	Description
   UNIT	Specifies the resource configuration for the resource pool. Each resource unit in the pool uses this specification.
   UNIT_NUM	The number of resource units created by the resource pool on each zone in ZONE_LIST.
   ZONE_LIST	The scope of use for the resource pool, specifying on which zones to create resource units.

4. Create tenants tenant1 and tenant2 respectively, and associate them with the corresponding resource pools:

   obclient [oceanbase]> CREATE TENANT IF NOT EXISTS tenant1 CHARSET='utf8mb4', PRIMARY_ZONE='zone1', RESOURCE_POOL_LIST=('pool1') SET ob_tcp_invited_nodes='%';
   
   obclient [oceanbase]> CREATE TENANT IF NOT EXISTS tenant2 CHARSET='utf8mb4', PRIMARY_ZONE='zone1', RESOURCE_POOL_LIST=('pool2') SET ob_tcp_invited_nodes='%';
   

   Key parameters:

   Parameter	Description
   CHARSET	The character set for the tenant. In this example, it is set to utf8mb4.
   PRIMARY_ZONE	The zone where leader replicas are preferentially distributed.
   RESOURCE_POOL_LIST	The list of resource pools associated with the tenant.
   ob_tcp_invited_nodes	The access allowlist for the tenant. '%' indicates any IP can access. This can be modified later.

5. Confirm that the tenants are created successfully:

   obclient [oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, STATUS, TENANT_ROLE
                       FROM DBA_OB_TENANTS WHERE TENANT_TYPE = 'USER';
   

   A sample return result is as follows. The STATUS for both tenant1 and tenant2 is NORMAL, indicating successful creation:

   +-----------+-------------+-------------+--------+-------------+
   | TENANT_ID | TENANT_NAME | TENANT_TYPE | STATUS | TENANT_ROLE |
   +-----------+-------------+-------------+--------+-------------+
   |         1 | sys         | SYS         | NORMAL | PRIMARY     |
   |      1002 | tenant1     | USER        | NORMAL | PRIMARY     |
   |      1004 | tenant2     | USER        | NORMAL | PRIMARY     |
   +-----------+-------------+-------------+--------+-------------+
   3 rows in set
   

   The TENANT_ID and other numbers are automatically assigned by the system and may vary by environment. When a user tenant is created, the system also automatically creates an internal tenant starting with META$ (TENANT_TYPE is META), used to manage tenant metadata. You can query full information using SELECT * FROM DBA_OB_TENANTS;, but you do not need to focus on this.

6. Log in to tenant1 as the root user. The default password for the newly created tenant root user is empty. When prompted to enter a password, just press Enter:

   obclient -h127.0.0.1 -uroot@tenant1 -P2881 -p -A test
   

   After logging in, execute SHOW DATABASES; to see that the new tenant has its own independent database list:

   +--------------------+
   | Database           |
   +--------------------+
   | information_schema |
   | mysql              |
   | oceanbase          |
   | test               |
   +--------------------+
   4 rows in set
   

   Similar to the sys tenant, tenant1 also contains three system databases: information_schema, mysql, and oceanbase, which store database system information and metadata. Do not store business data in these databases.

Experience tenant isolation

In a multi-tenant architecture, data and permissions are completely isolated between tenants: OceanBase does not allow cross-tenant data access, and each tenant has its own independent user system. This section verifies isolation through two sets of operations.

Data isolation

1. Create a test table in tenant1 and insert data:

   obclient -h127.0.0.1 -uroot@tenant1 -P2881 -p -A test
   

   obclient [test]> CREATE TABLE business_a_order (id INT PRIMARY KEY, item VARCHAR(50), amount DECIMAL(10,2));
   Query OK, 0 rows affected
   
   obclient [test]> INSERT INTO business_a_order VALUES (1, 'keyboard', 149.00);
   Query OK, 1 row affected
   
   obclient [test]> SHOW TABLES;
   +------------------+
   | Tables_in_test   |
   +------------------+
   | business_a_order |
   +------------------+
   1 row in set
   

2. Log in to tenant2 as the root user and check the tables in the test database:

   obclient -h127.0.0.1 -uroot@tenant2 -P2881 -p -A test
   

   obclient [test]> SHOW TABLES;
   Empty set
   

   No tables created in tenant1 are visible in tenant2. The two tenants have their own independent test databases, with data being completely isolated.

Permission isolation

Each tenant has its own independent user system. Users created in one tenant cannot log in to another tenant.

1. Create a business user in tenant1:

   obclient [test]> CREATE USER app_user IDENTIFIED BY '******';
   Query OK, 0 rows affected
   

2. Try to connect to tenant2 using app_user (enter the password for app_user when prompted):

   obclient -h127.0.0.1 -uapp_user@tenant2 -P2881 -p -A test
   Enter password:
   ERROR 1045 (42000): Access denied for user 'app_user'@'xxx.xxx.xxx.xxx' (using password: NO)
   

   The connection fails with the error ERROR 1045 Access denied because app_user only exists in the user system of tenant1, and tenant2 cannot recognize this user. The using password: NO at the end of the error indicates that this user does not exist in tenant2, not that you did not enter a password. Similarly, the root user of tenant1 and the root user of tenant2 are also two completely independent accounts.

Online adjustment of tenant resource specifications

OceanBase Database allows you to flexibly adjust the CPU and memory resources of a tenant, and the adjustments take effect online and are transparent to the business. To change the CPU and memory allocated to a tenant, you only need to modify the resource configuration that the tenant uses; the resource pool and the tenant itself do not need to be changed.

Procedure

1. View the current resource configuration in the sys tenant:

   obclient [oceanbase]> SELECT UNIT_CONFIG_ID, NAME, MAX_CPU, MIN_CPU, MEMORY_SIZE, LOG_DISK_SIZE
                       FROM oceanbase.DBA_OB_UNIT_CONFIGS WHERE NAME IN ('unit1', 'unit2');
   

   An example of the return result is as follows:

   +----------------+-------+---------+---------+-------------+---------------+
   | UNIT_CONFIG_ID | NAME  | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE |
   +----------------+-------+---------+---------+-------------+---------------+
   |           1006 | unit1 |       1 |       1 |  2147483648 |    6442450944 |
   |           1007 | unit2 |       2 |       2 |  4294967296 |   12884901888 |
   +----------------+-------+---------+---------+-------------+---------------+
   2 rows in set
   

   The result shows that the unit1 resource unit provides 1C of CPU and 2G of memory, and that its log disk space is 6G (by default, three times the memory size). UNIT_CONFIG_ID is assigned automatically by the system and varies by environment. MEMORY_SIZE and LOG_DISK_SIZE are expressed in bytes, and 1G equals 1073741824 bytes.

2. Adjust the specification of unit1 to 2C4G online to simulate a resource expansion for Business A:

   obclient [oceanbase]> ALTER RESOURCE UNIT unit1 MAX_CPU=2, MIN_CPU=2, MEMORY_SIZE='4G';
   Query OK, 0 rows affected
   

3. Query the resource configuration again to confirm the adjustment has taken effect (repeat the query statement from step 1):

   obclient [oceanbase]> SELECT UNIT_CONFIG_ID, NAME, MAX_CPU, MIN_CPU, MEMORY_SIZE, LOG_DISK_SIZE
                       FROM oceanbase.DBA_OB_UNIT_CONFIGS WHERE NAME IN ('unit1', 'unit2');
   

   In the returned result, unit1's MAX_CPU and MIN_CPU have changed to 2, and MEMORY_SIZE has changed to 4294967296 (i.e., 4G). LOG_DISK_SIZE remains unchanged. The ALTER statement only adjusts explicitly specified options. If you need to adjust the log disk specification at the same time, you can specify LOG_DISK_SIZE in the statement:

   +----------------+-------+---------+---------+-------------+---------------+
   | UNIT_CONFIG_ID | NAME  | MAX_CPU | MIN_CPU | MEMORY_SIZE | LOG_DISK_SIZE |
   +----------------+-------+---------+---------+-------------+---------------+
   |           1006 | unit1 |       2 |       2 |  4294967296 |    6442450944 |
   |           1007 | unit2 |       2 |       2 |  4294967296 |   12884901888 |
   +----------------+-------+---------+---------+-------------+---------------+
   2 rows in set
   

4. View the distribution of resource units on nodes and their actual effective status through the GV$OB_UNITS view:

   obclient [oceanbase]> SELECT SVR_IP, UNIT_ID, TENANT_ID, ZONE, MAX_CPU, MIN_CPU, MEMORY_SIZE, STATUS
                       FROM oceanbase.GV$OB_UNITS;
   

   A sample return result is as follows (10.10.10.1 is an example IP address; in your environment it is the IP address of your own host. UNIT_ID and TENANT_ID vary by environment and can be matched with the TENANT_ID values queried in the "Confirm that the tenants are created successfully" step above):

   +------------+---------+-----------+-------+---------+---------+-------------+--------+
   | SVR_IP     | UNIT_ID | TENANT_ID | ZONE  | MAX_CPU | MIN_CPU | MEMORY_SIZE | STATUS |
   +------------+---------+-----------+-------+---------+---------+-------------+--------+
   | 10.10.10.1 |       1 |         1 | zone1 |       2 |       2 |  1073741824 | NORMAL |
   | 10.10.10.1 |    1002 |      1001 | zone1 |    NULL |    NULL |  1073741824 | NORMAL |
   | 10.10.10.1 |    1002 |      1002 | zone1 |       2 |       2 |  3221225472 | NORMAL |
   | 10.10.10.1 |    1003 |      1003 | zone1 |    NULL |    NULL |  1073741824 | NORMAL |
   | 10.10.10.1 |    1003 |      1004 | zone1 |       2 |       2 |  3221225472 | NORMAL |
   +------------+---------+-----------+-------+---------+---------+-------------+--------+
   5 rows in set
   

   In the result, each resource unit corresponds to one row. The row whose TENANT_ID is 1 is the resource unit of the sys tenant; the row whose MAX_CPU is NULL records the resources of the internal Meta tenant; the remaining two rows are the resource units of tenant1 and tenant2, and STATUS of NORMAL means that the resource unit is running normally. MEMORY_SIZE in the view is the quota that actually takes effect after the system reservation is deducted, so it is less than the configured value (for example, a 4G specification is displayed as 3221225472, which is about 3G).

Comparison of resource change methods

In addition to directly modifying resource configurations, OceanBase also supports changing tenant resources by switching resource configurations, adjusting UNIT_NUM, and modifying ZONE_LIST. These methods apply to different scaling scenarios (the last two apply only to multi-zone, multi-node clusters and cannot be demonstrated in a single-node environment):

Observe tenant performance under stress testing

After you complete the operations in the preceding two sections, the two business tenants tenant1 (1C2G) and tenant2 (2C4G) are ready. This section uses sysbench to run a standard point query stress test against the tenants, to verify that the new tenants can handle business traffic normally, and to help you understand the resource isolation logic of OceanBase from the results.

Procedure

1. Run a point query stress test against the smaller tenant tenant1 (if you have already adjusted unit1 to 2C4G as described in the preceding section, first run ALTER RESOURCE UNIT unit1 MAX_CPU=1, MIN_CPU=1, MEMORY_SIZE='2G'; to revert the change):

   obd test sysbench demo --tenant=tenant1 --script-name=oltp_point_select.lua --table-size=100000 --threads=16 --rand-type=uniform
   

   On the first run, obd automatically generates the test data, loads the data, and runs the stress test. When the run finishes, it outputs statistics such as QPS and latency; note down the QPS and the 95th percentile latency.

2. Run a stress test with exactly the same parameters against the larger tenant tenant2 (2C4G):

   obd test sysbench demo --tenant=tenant2 --script-name=oltp_point_select.lua --table-size=100000 --threads=16 --rand-type=uniform
   

3. Compare the results of the two rounds and focus on the following:

   • Both rounds finish normally and output statistics, which shows that each tenant can handle business traffic independently.
   • Test data is generated independently in each tenant; the stress test on tenant1 leaves no data in tenant2.

Interpretation

The QPS values of the two rounds differ considerably depending on machine specifications, data volume, and concurrency parameters, so focus on the following phenomena rather than on the absolute values:

Next steps

After you complete the experiences in this topic, you can explore the following:

1. Experience high availability and failover: Learn about core concepts in OceanBase such as replicas, zones, Leaders/Followers, observe replica and Leader distribution, and experience service continuity under fault scenarios. See Experience high availability and failover.
2. Experience horizontal scaling and elastic scaling: Explore the scalability at the compute, storage, and tenant resource levels, and observe resource changes and business capacity impacts before and after scaling. See Experience horizontal scaling and elastic scaling.
3. Experience resource isolation within a tenant: Isolate TP and AP workloads within the same tenant using resource groups. See Experience HTAP hybrid workload scenarios.

References

• For basic concepts of the multi-tenant architecture, see Multi-tenant architecture overview.
• For detailed descriptions of tenant resource management (resource configuration, resource pools, and resource units), see Resource management of tenants.
• For information about how to view tenant resource configurations, see View resource specifications.
• For the syntax of dropping a tenant, see DROP TENANT.
• For information about how to configure resource isolation within a tenant (using resource groups), see Configure resource isolation within a tenant.
• For detailed parameters of OBD test commands, see Test commands.