Help Center/ TaurusDB/ Kernel/ Common Kernel Functions/ Multi-tenancy/ Overview
Updated on 2025-07-07 GMT+08:00
View PDF
Share

Overview

What Is Multi-tenancy?

TaurusDB provides multi-tenancy to maximize database resource utilization. Data is isolated among tenants. Different tenants can only access their own data. There are tenant-level resource isolation and user-level resource isolation to avoid resource wastes and improve performance. Resources can be dynamically adjusted to process workload peaks and troughs of different tenants or users in a timely manner.

The following figure shows the principle of multi-tenancy.

Figure 1 Principle diagram

The figure shows the overall process of multi-tenancy. There are system tenants and common tenants.

There are a database (DB_1) and a user (User_1) under the system tenant, two databases (DB_1 and DB_2) and two users (User_1 and User_2) under common tenant Tenant_1, and two databases (DB_1 and DB_2) and two users (User_1 and User_2) under common tenant Tenant_2.

The system tenant has access to the entire DB instance. That is, the system tenant can access and manage its own database and user, and can also access and manage the databases and users under Tenant_1 or Tenant_2. Data is isolated between different common tenants. Tenant_1 can only access and manage only its own databases and users. It cannot access the databases and users under Tenant_2 or the database and user under the system tenant.

In addition to data isolation, multi-tenancy also ensures vCPU isolation. The figure shows the total vCPUs of the current instance. You can adjust resource settings for the system tenant and common tenants, and then allocate these resources to specific users under a tenant.

Basic Concepts

Tenant-level

  • Tenant: Tenants are under a DB instance and above databases and users. Tenants are used for data isolation and resource isolation. However, databases can be accessed as a user.
    • There are system tenants and common tenants based on data isolation.
      • System tenant (sys_tenant): System tenants are designed to accommodate users that exist before the implementation of multi-tenancy. By default, these existing users belong to system tenants and are also referred to as system users. If a user under a system tenant can connect to and access a DB instance, the user can access the databases of all tenants.
      • Common tenant (user_tenant): You can create common tenants as a system tenant. The users and databases of each common tenant are completely isolated from those of other common tenants. In addition, common tenants cannot access databases of the system tenants.
    • There are dedicated tenants and shared tenants based on resource isolation. The resources available to tenants, currently limited to vCPUs, are determined by tenant-level resource configurations.
      • Dedicated tenant: The value of min_cpu in the resource configuration associated with the tenant is greater than 0. Ensure that vCPUs allocated to dedicated tenants at any time are not less than the value of min_cpu.
      • Shared tenant: tenants associated with the specific resource configuration shared_tenants_config. The value of min_cpu in the resource configuration is 0. The system preferentially ensures the resource requests of dedicated tenants and then allocates the remaining resources to shared tenants. In addition, the system reserves some vCPUs (specified by the mt_shared_cpu_reserved parameter) for shared tenants to ensure that shared tenants can obtain resources during vCPU contention. You can modify associated resource configurations to change the roles between dedicated and shared tenants.
  • Tenant-level resource configuration (resource_config): A resource configuration indicates the resources available to a tenant, enabling tenant-level resource isolation. Currently, vCPU resources can only be limited by setting min_cpu and max_cpu. The following resource configurations are built in:
    • RDS_SYS_CONFIG: resource configuration of the system tenant. The default value of min_cpu is 0.1 (unit: vCPUs), and the default value of max_cpu is the vCPUs in the instance specifications.
    • shared_tenants_config: resource configuration of the shared tenant. The value of min_cpu is fixed to 0, and the default value of max_cpu is the vCPUs in the instance specifications.
Figure 2 Tenant-level data isolation and resource configuration

As shown in the figure, when a user logs in to the instance as the system tenant and creates DB1, DB3, and USER1, the names of these databases and user displayed to the system tenant remain unchanged. The system tenant can view all databases and users under common tenants, but the names of the databases and users displayed to the system tenant change. For example, DB1, USER1, and USER2 of tenant1 will be displayed as DB1@tenant1, USER1@tenant1, and USER2@tenant1. DB1, DB2, and USER1 of tenant2 will be displayed as DB1@tenant2, DB2@tenant2, and USER1@tenant2.

TaurusDB uses different tenant name suffixes to distinguish databases and users of different tenants. When a user logs in to the instance as tenant1, the databases and users are displayed as DB1, DB2, USER1, and USER2. The same rule applies to tenant2. If DB2 exists before multi-tenancy is enabled, DB2 will belong to the system tenant by default after multi-tenancy is enabled. You can also assign DB2 to other tenants using the syntax provided by TaurusDB. For details, see the following sections.

When it comes to resource isolation, system tenants can use default resource configurations or customize ones. In the preceding figure, the system tenant can use a minimum of 1 vCPU and a maximum of 2 vCPUs. tenant1 can use a minimum of 0 vCPUs (which indicates that it is a shared tenant) and a maximum of 4 vCPUs. tenant2 can use a minimum of 3 vCPUs (which indicates that it is a dedicated tenant) and a maximum of 4 vCPUs.

User-level

Users are under DB instances and tenants. A tenant can have multiple users. Multi-tenancy does not change how user data is isolated, but it does provide a way to manage resources at the user level.

  • Resource consumer group (consumer_group)

    Multiple users can belong to a given resource consumer group to share the resources associated with the group.

  • Resource plan directive (plan_directive)

    A resource plan directive corresponds to only one resource consumer group and describes the specific resource configuration of the resource consumer group. A resource consumer group can be associated with multiple resource plan directives, but only one can be enabled at a time.

  • Resource plan (plan)

    A resource plan controls whether to enable or disable a resource plan directive. Each resource plan is associated with one or more resource plan directives. Enabling or disabling a resource plan will activate or deactivate the resource plan directives. Only one resource plan can be enabled per tenant.

    Figure 3 User-level resource configuration relationship

    As shown in the figure, there are an instance with 4 vCPUs and a dedicated tenant (Tenant_1). The tenant can use a minimum of 1 vCPU and a maximum of 4 vCPUs. All users under the tenant share the tenant resources. There are two resource plans (plan1 and plan2). plan1 has one plan directive (plan_directive1), and plan2 has two plan directives (plan_directive2 and plan_directive3).

    • plan_directive2: states that consumer_group1 can use a minimum of 60% and a maximum of 100% of Tenant_1's vCPUs.
    • plan_directive3: states that consumer_group2 can use a minimum of 40% and a maximum of 100% of Tenant_1's vCPUs.

    When plan2 is enabled, the user-level vCPU limits specified by plan_directive2 and plan_directive3 take effect. user_1 belongs to consumer_group1, so its vCPU limits are determined by plan_directive2. The same rule applies to user_2 and user_3.

Constraints

  • If the kernel version of your TaurusDB instance is 2.0.60.241200 or later, the new multi-tenant views (including MT_RESOURCE_CONFIG, MT_TENANT, MT_TENANT_DB, MT_RESOURCE_PLAN, MT_CONSUMER_GROUP, MT_GROUP_MAPPING_RULE, and MT_PLAN_DIRECTIVE) will replace the old DBA_RSRC_* views.
  • Binlog: If common tenants pull binlogs, data among tenants will not be isolated. Users of common tenants are not allowed to pull binlogs.
  • Proxy instance: HTAP (Standard Edition) does not support databases whose name contains at signs (@). When a database of a common tenant is migrated to an HTAP instance, the destination database name will be changed. After Auto Assign Requests to Column Store or Row Store Nodes is enabled, the proxy instance requires that the source and destination database names be the same, so this function must be disabled for migrating databases of common tenants.
  • Backup and restoration:

    If the source instance has multi-tenancy enabled and its kernel version is earlier than 2.0.60.241200, and the destination instance's kernel version is 2.0.60.241200 or later, data of the source instance cannot be restored to the destination instance using backups. In such a case, the __taurus_sys__ database may be cleared, and multi-tenancy cannot function properly.

    If multi-tenancy is disabled for the destination instance, you cannot create users, databases, and tablespaces with at signs (@) in their names for that instance.

  • Upgrade and downgrade:
    • If the kernel version of your TaurusDB instance with multi-tenancy enabled is downgraded from 2.0.60.241200 or later to a version earlier than 2.0.60.241200, multi-tenancy will be disabled. To re-enable the function, you need to reboot the instance.
    • If the kernel version of your TaurusDB instance is downgraded from 2.0.60.241200 or later to a version earlier than 2.0.60.241200, the new multi-tenant views (including MT_RESOURCE_CONFIG, MT_TENANT, MT_TENANT_DB, MT_RESOURCE_PLAN, MT_CONSUMER_GROUP, MT_GROUP_MAPPING_RULE, and MT_PLAN_DIRECTIVE) may still be displayed when you run the show tables command in information_schema, but cannot be accessed. To clear the residual multi-tenant view metadata, you need to reboot the instance.
    • If the kernel version of your TaurusDB instance is upgraded to 2.0.60.241200 or later, the new multi-tenant views may fail to be displayed when you run the show tables command in information_schema, but can be accessed. To display the multi-tenant views, you need to reboot the instance.
  • Compatibility:
    • If multi-tenancy is enabled and then disabled, the names of databases, users, or tablespaces cannot contain at signs (@).
    • For a common tenant, the maximum length of a database name is reduced from 64 characters to 50 characters, and the maximum length of a user name is reduced from 32 characters to 20 characters.
    • The system databases mysql and sys are not available to common tenants.
    • For a common tenant, fuzzy search is required when a username or database name is used to query tables in the system database performance_schema.
    • User root under a system tenant can kill sessions of other users. Users under a common tenant can only kill their own sessions.
    • Instances with multi-tenancy enabled do not support full-text indexes.
Parent Topic: Multi-tenancy