PolarDB:Multi-tenancy

Concepts

Tenant: In a multi-tenancy architecture, a tenant is a logical entity that represents a specific unit for data and resource allocation. A tenant is at a level below a cluster but above users and databases. Multiple accounts or databases can belong to a single tenant. A tenant is not the same as a user or a database. Tenants are divided into two categories:

• System tenant: This is a special administrative entity. A cluster typically has only one system tenant. The system tenant has priority access to resources and can use the resources of regular tenants. When a user of the system tenant connects to a database, if the user has the required cluster access permissions, they can access the resources of all tenants.

• Regular tenant: The resources of each regular tenant are completely isolated from other tenants. A regular tenant must be created in the context of the system tenant.

Resource configuration: This involves allocating specific resources, such as CPU and memory, to a particular tenant. This configuration method allows privileged accounts to specify resource limits for each tenant as needed.

The tenant resource configuration feature is designed to limit the amount of resources used by one or more processes. In PolarDB for PostgreSQL (Compatible with Oracle), a session corresponds to a single process, and within that session, only one user can log on to one database. The system lets you map any process, user, or database to a specified tenant. However, a process can belong to only one tenant. This prevents resource usage from being counted multiple times. The child processes of a parallel query belong to the tenant of the process that initiated the query. Therefore, resource limits can be divided into three dimensions based on process attributes:

• Process: A connection process (session process) actively initiated by a user. This includes related parallel query processes but excludes system auxiliary processes.

• User: All connection processes (session processes) initiated by the same user. This includes related parallel query processes but excludes system auxiliary processes.

• Database: All connection processes (session processes) that access the same database. This includes related parallel query processes but excludes system auxiliary processes.

Scope

The following versions of PolarDB for PostgreSQL (Compatible with Oracle) are supported: Oracle Syntax Compatibility 2.0 with minor engine version 2.0.14.12.24.0 or later.

Parameters

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

Usage

To use the multi-tenancy feature, you must install the polar_resource_manager extension in the database specified by the polar_resource_manager.database_name parameter.

CREATE EXTENSION polar_resource_manager;

Create a resource configuration

Use the polar_create_resource_config function to create a resource configuration.

SELECT polar_resource_manager.polar_create_resource_config('resource_config_name');

The resource_config_name parameter must comply with database object name limits. The name can be up to 64 bytes long and is automatically truncated if it exceeds this limit.

Delete a resource configuration

Use the polar_drop_resource_config function to delete a resource configuration.

SELECT polar_resource_manager.polar_drop_resource_config('resource_config_name');

Modify a resource configuration

You can use the polar_alter_resource_config function to modify a resource configuration.

SELECT polar_resource_manager.polar_alter_resource_config('resource_config_name', 'config_name', value);

config_name supports the following types:

• cpu_rate_limit: Specifies the CPU limit in cores.

• mem_limit: Specifies the memory limit in bytes.

Create a tenant

You can use the polar_create_tenant function to create a tenant.

SELECT polar_resource_manager.polar_create_tenant('tenant_name', 'resource_config_name');

Where:

• The tenant_name parameter must comply with the naming conventions for database objects. The name can be up to 64 bytes long and is automatically truncated if it exceeds this limit.

• You must first create a resource configuration for resource_config_name. Otherwise, you cannot create the tenant.

Delete a tenant

You can use the polar_drop_tenant function to delete a tenant. Deleting a tenant does not delete its resource configuration.

SELECT polar_resource_manager.polar_drop_tenant('tenant_name');

Modify a tenant

You can use the polar_alter_tenant function to modify a tenant.

SELECT polar_resource_manager.polar_alter_tenant('tenant_name', 'config_name', 'value');

The config_name parameter supports the following types:

• name: The name of the tenant.

• resource_config: The configuration of the resource.

Database tenant ownership

You can use the polar_tenant_add_database function to assign a database to a tenant. A database can be assigned to only one tenant. An attempt to assign the database to another tenant will fail.

SELECT polar_resource_manager.polar_tenant_add_database('tenant_name', 'database_name');

View databases and tenants

You can query the polar_tenants_dbs view to view databases and their assigned tenants.

SELECT dbsname, tenantname FROM polar_resource_manager.polar_tenants_dbs;

Assign a user to a tenant

You can use the polar_tenant_add_user function to assign a user to a tenant. A user can be assigned to only one tenant. If you attempt to assign the user to another tenant, the operation fails.

SELECT polar_resource_manager.polar_tenant_add_user('tenant_name', 'user_name');

View users and tenants

Use the polar_tenants_users view to check user-tenant assignments.

SELECT username, tenantname FROM polar_resource_manager.polar_tenants_users;

Assign a process to a tenant

You can use the polar_tenant_add_process function to assign a process to a tenant. A process can be assigned to only one tenant. If you assign a process to multiple tenants, only the last assignment takes effect.

SELECT polar_resource_manager.polar_tenant_add_process('tenant_name', pid);

View tenant resource information

You can view tenant resource information from the polar_all_resource_configs_detail view.

SELECT * FROM polar_resource_manager.polar_all_resource_configs_detail;

The view contains the following information:

CPU resource management

After you assign processes, users, or databases to a tenant, you can set CPU-related limits in the tenant's resource configuration. When a parallel query is initiated, its backend child processes are assigned to the tenant of the session that issued the query. This allows the backend child processes and the session process to share the resources limited by the tenant. When the parallel query finishes, the backend child processes are removed from the tenant. This mechanism dynamically applies and removes resource limits for parallel queries.

CPU usage limit

This limits the maximum CPU usage of a tenant. If the CPU usage of a tenant's assigned entities exceeds the configured limit, the cluster throttles the corresponding processes to enforce the limit.

You can set cpu_rate_limit using the polar_alter_resource_config function. The parameter value is of the float type.

Memory resource management

Because memory is a rigid resource (swap is disabled), it cannot be dynamically throttled in the same way as CPU. If the hard limit for memory is exceeded, processes are typically aborted to release resources. The memory management for a tenant is similar to the OOM handling policy of an operating system. However, it is an OOM process at the tenant level, not at the entire database level.

Memory usage limit

You can set mem_limit using the polar_alter_resource_config function. Similar to the CPU usage limit, this limits the maximum memory usage. The sum of the limits can be greater than or equal to the total available memory. It includes the following two policies:

• Active resource over-limit management: When the total memory usage exceeds the active eviction threshold (total_mem_request_rate, default 80%), if a tenant's memory usage exceeds the memory limit set in its resource configuration, the system terminates the corresponding session to release resources. A memory over-limit error is returned to the user. This continues until the total memory usage falls below the active eviction threshold.

• Forced resource over-limit management: To prevent excessive memory usage in the cluster from causing an OOM error, when the total memory usage exceeds the forced eviction threshold (total_mem_limit_rate, default 95%), the system traverses all processes and terminates their corresponding sessions to release resources. A memory over-limit error is returned to the user.

When memory limits trigger an eviction, the user session is aborted and its process resources are released. This is done by sending a SIGUSR2 signal, and a specified OOM error is returned to the user. If a background process for a parallel query exceeds the memory limit, the corresponding user process is aborted. Currently, only user processes are limited. System background processes belong to the system tenant and are not actively aborted to release resources.