PolarDB:Multi-tenancy

Tenant hierarchy

A tenant is a logical resource boundary within a cluster — sitting above users and databases, but below the cluster itself. Multiple users and databases can belong to a single tenant.

There are two tenant types:

Resource configuration

A resource configuration defines the CPU and memory limits applied to a tenant. You create a resource configuration separately, then attach it to a tenant. Detaching or deleting the tenant does not delete the resource configuration.

Resource tracking dimensions

Every session in PolarDB for PostgreSQL corresponds to a single process. Each process belongs to exactly one tenant, which prevents double-counting. The system maps processes to tenants along three dimensions:

Parallel query child processes automatically join the tenant of the session that issued the query, and are removed from the tenant when the query finishes.

System processes have no resource limits by default.

Resource limit enforcement

CPU and memory use different enforcement mechanisms:

Before you begin

• A PolarDB for PostgreSQL (Compatible with Oracle) cluster running Oracle Syntax Compatibility 2.0, minor engine version 2.0.14.12.24.0 or later

Step 1: Install the extension

Install the polar_resource_manager extension in the database specified by polar_resource_manager.database_name (default: polardb_admin):

CREATE EXTENSION polar_resource_manager;

Step 2: Create a resource configuration

SELECT polar_resource_manager.polar_create_resource_config('resource_config_name');

resource_config_name follows database object naming rules. Names longer than 64 bytes are truncated automatically.

Step 3: Set resource limits

Set the CPU limit (in cores) and the memory limit (in bytes) on the resource configuration:

-- Set CPU limit: 0.3 = 30% of one CPU core; 2 = two full CPU cores
SELECT polar_resource_manager.polar_alter_resource_config('resource_config_name', 'cpu_rate_limit', 2);

-- Set memory limit in bytes
SELECT polar_resource_manager.polar_alter_resource_config('resource_config_name', 'mem_limit', value);

cpu_rate_limit is measured in cores (float). A value of 0.3 limits usage to 30% of one core; a value of 2 allows up to two full cores. The sum of cpu_rate_limit values across all tenants can exceed the cluster's total physical CPU capacity — the system throttles processes when individual limits are reached.

mem_limit is in bytes. For enforcement behavior when a tenant exceeds its memory limit, see Memory resource management.

Step 4: Create a tenant

A resource configuration must exist before you create a tenant.

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

tenant_name follows database object naming rules. Names longer than 64 bytes are truncated automatically.

To modify an existing tenant:

-- Rename the tenant
SELECT polar_resource_manager.polar_alter_tenant('tenant_name', 'name', 'new_tenant_name');

-- Switch the resource configuration
SELECT polar_resource_manager.polar_alter_tenant('tenant_name', 'resource_config', 'new_resource_config_name');

To delete a tenant (this does not delete the attached resource configuration):

SELECT polar_resource_manager.polar_drop_tenant('tenant_name');

To delete a resource configuration:

SELECT polar_resource_manager.polar_drop_resource_config('resource_config_name');

Step 5: Assign databases, users, or processes

Assign at least one database, user, or process to the tenant so that sessions are tracked against its resource limits.

Assign a database

A database can belong to only one tenant. Assigning it to another tenant fails.

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

To view current database-to-tenant assignments:

SELECT dbsname, tenantname FROM polar_resource_manager.polar_tenants_dbs;

Assign a user

A user can belong to only one tenant. Assigning them to another tenant fails.

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

To view current user-to-tenant assignments:

SELECT username, tenantname FROM polar_resource_manager.polar_tenants_users;

Assign a process

A process can belong 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);

Step 6: View resource usage

Query the polar_all_resource_configs_detail view for a snapshot of all tenants' resource usage:

SELECT * FROM polar_resource_manager.polar_all_resource_configs_detail;