PolarDB:Multi-tenancy

Concepts

Tenant: In multi-tenancy, a tenant is a logical entity that represents a specific unit of data and resource allocation. The hierarchy of a tenant is positioned below the cluster and above users and databases. The correspondence between them is many-to-one: multiple accounts or databases correspond to one tenant. A tenant is not equivalent to a user or a database. Tenants are divided into two categories:

• System tenant: This is a special management entity, and there is usually only one. The system tenant has priority access to resources and can occupy the resources of regular tenants. When you connect to a database as a user of the system tenant, if the user has the corresponding cluster access permissions, the user can access the cluster under all tenants.

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

Resource configuration: A resource configuration involves allocating specific resources (such as CPU and memory) to a specific tenant. This configuration method allows privileged accounts to specify resource limits for each tenant according to business requirements.

The tenant resource configuration feature aims to limit the amount of resources used by one or more processes. In PolarDB for PostgreSQL, one session corresponds to one process, and one session can be logged in to only one database by one user. Therefore, processes, users, and databases constitute the basic elements of a process. The system allows mapping any process, user, or database to a specified tenant, but one process can belong to only one tenant, thereby avoiding duplicate statistics of resource usage. The child processes of a background parallel query belong to the tenant of the process that initiated the query. Therefore, based on the attributes of processes, resource limits can be divided into three dimensions:

• Process: refers to the account connection processes (session processes) actively initiated by users, including the parallel query processes related to the process, but excluding system auxiliary processes.

• User: refers to all user connection processes (session processes) initiated by the same user, including the parallel query processes related to the process, but excluding system auxiliary processes.

• Database: refers to all user connection processes (session processes) that access the same database, including the parallel query processes related to the process, but excluding system auxiliary processes.

Scope of application

The supported versions of PolarDB for PostgreSQL are as follows:PostgreSQL 14, and the minor engine version must be 2.0.14.12.24.0 or later.

Parameter description

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

SELECT pg_reload_conf();

Usage notes

When using multi-tenancy, you need to, in the database specified by the polar_resource_manager.database_name parameter, install the polar_resource_manager extension.

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 the database object name restrictions. Only names within 64 bytes are supported. Names longer than 64 bytes are automatically truncated.

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

Use the polar_alter_resource_config function to modify the resource settings of a resource configuration.

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

The supported config_name types are as follows:

• cpu_rate_limit: the CPU limit value, in number of cores.

• mem_limit: the memory limit value, in bytes.

Create a tenant

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 database object name restrictions. Only names within 64 bytes are supported. Names longer than 64 bytes are automatically truncated.

• The resource_config_name resource configuration must be created first. Otherwise, the tenant cannot be created.

Delete a tenant

Use the polar_drop_tenant function to delete a tenant. Deleting a tenant does not delete the resource configuration.

SELECT polar_resource_manager.polar_drop_tenant('tenant_name');

Modify a tenant

Use the polar_alter_tenant function to modify a tenant.

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

The supported config_name types are as follows:

• name: the tenant name.

• resource_config: the resource configuration.

Assign a database to a tenant

Use the polar_tenant_add_database function to assign a database to a tenant. A database can be assigned to only one tenant. Otherwise, the assignment fails.

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

View databases and tenants

Use the polar_tenants_dbs view to view databases and the tenants they belong to.

SELECT dbsname, tenantname FROM polar_resource_manager.polar_tenants_dbs;

Assign a user to a tenant

Use the polar_tenant_add_user function to assign a user to a tenant. A user can be assigned to only one tenant. Otherwise, the assignment fails.

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

View users and tenants

Use the polar_tenants_users view to view users and the tenants they belong to.

SELECT username, tenantname FROM polar_resource_manager.polar_tenants_users;

Assign a process to a tenant

Use the polar_tenant_add_process function to assign a process to a tenant. A process can be assigned to only one tenant. When a process is assigned to multiple tenants, the last assignment takes effect.

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

View tenant resource status

Use the polar_all_resource_configs_detail view to view the tenant resource status.

SELECT * FROM polar_resource_manager.polar_all_resource_configs_detail;

The view information is as follows:

CPU resource management

After adding processes, users, or databases to the corresponding tenant, you can set the CPU-related limit values of the tenant resource configuration. If there are allocatable backend child processes, the backend child processes are added to the tenant of the session connection that issues the parallel query, so that the backend child processes and the session process share the resources limited by the tenant. When the parallel query of the session finishes execution, the backend child processes are removed from the tenant. This is a process of dynamically adding and removing resource limits.

CPU usage limit

Used to limit the maximum CPU usage of objects within a tenant. When the CPU usage of an object within a tenant is too high, the cluster restricts it and reduces the CPU usage to below the limit value.

Use polar_resource_manager.polar_alter_resource_config to set cpu_rate_limit. The parameter value is of the float type.

Memory resource management

Because memory resources are rigid resources (swap off), they cannot be dynamically limited like CPU. If memory resources exceed the hard limit, resources are generally released by aborting processes. Tenant memory management is similar to the OOM handling strategy of an operating system. Compared with the database-level OOM handling of the system, this is only tenant-level OOM handling.

Memory usage limit

Use polar_resource_manager.polar_alter_resource_config to set mem_limit. The parameter value is of the float type. Similar to the CPU usage limit, it is used to limit the maximum value of memory usage. The total limit value can be greater than or equal to the specification quota. The following two strategies are included:

• Active resource over-limit management: When the total memory usage is greater than the active eviction threshold (total_mem_request_rate, default value 80%), if a tenant's memory usage is greater than the memory limit of this tenant's resource configuration, the resources of the corresponding session are released and a memory over-limit error is returned to the user. This continues until the memory usage is less than the active eviction threshold.

• Forced resource over-limit management: To avoid excessive use of cluster memory that causes cluster OOM, when the total memory usage is greater than the forced eviction threshold (total_mem_limit_rate, default value 95%), all processes are traversed, the resources of the corresponding sessions are released, and a memory over-limit error is returned to the user.

When memory limits perform eviction, user sessions are aborted and process resources are released. This can be implemented by sending SIGUSR2 to return the specified OOM error to the user. If the memory of a background process of a parallel query exceeds the limit, the corresponding user process is aborted. Currently, only user processes are limited. System background processes currently belong to the system tenant and are not actively aborted to release resources.