Multi-Tenancy

ParticleDB supports namespace-based multi-tenancy where each tenant operates in an isolated namespace with configurable resource quotas. Namespaces provide schema-level isolation, usage tracking, and lifecycle management (suspend, resume, delete).

Namespaces

A namespace acts as an independent schema scope. Tables within a namespace are stored with a namespace.table_name prefix. The default namespace is public (PostgreSQL-compatible).

Create a Namespace

CREATE NAMESPACE tenant_acme;

Create a namespace with custom resource quotas:

CREATE NAMESPACE tenant_acme WITH (
  max_tables = 50,
  max_storage_gb = 5,
  max_connections = 100,
  max_rows_per_table = 10000000,
  max_queries_per_minute = 500
);

Set the Active Namespace

Switch the session’s default namespace. All unqualified table names resolve within this namespace:

SET NAMESPACE 'tenant_acme';

Show Namespaces

SHOW NAMESPACES;

Returns all namespaces with their status, owner, quotas, and current usage.

Alter Namespace Quotas

ALTER NAMESPACE tenant_acme SET (max_connections = 200, max_queries_per_minute = 1000);

Drop a Namespace

DROP NAMESPACE tenant_acme;

Dropping a namespace marks it as Deleted and removes all associated tables.

Resource Quotas

Each namespace enforces the following configurable quotas:

Quota	Default	Description
max_tables	100	Maximum number of tables in the namespace
max_storage_gb	10	Maximum total storage in GB
max_connections	50	Maximum concurrent connections
max_rows_per_table	100,000,000	Maximum rows per table
max_queries_per_minute	1,000	Rate limit (0 = unlimited)

When a quota is exceeded, the operation that would violate it is rejected with a descriptive error. Quotas are checked on every table creation, INSERT, and connection establishment.

Namespace Lifecycle

Namespaces have three lifecycle states:

State	Reads	Writes	Description
Active	Yes	Yes	Normal operation
Suspended	Yes	No	Reads allowed, writes blocked
Deleted	No	No	Marked for removal

Suspend and Resume

Temporarily block writes to a namespace (useful for billing holds or maintenance):

SUSPEND NAMESPACE tenant_acme;

Re-enable writes:

RESUME NAMESPACE tenant_acme;

Usage Tracking

The namespace manager tracks real-time resource consumption for each namespace:

Metric	Description
table_count	Current number of tables
storage_bytes_used	Total bytes consumed by table data
active_connections	Current concurrent connections
total_rows	Total rows across all tables
queries_this_minute	Queries executed in the current minute window

Usage events (table create/drop, row insert/delete, connection open/close, query execution) are recorded automatically and checked against quotas in real time.

Table Name Resolution

When a namespace is active, unqualified table names are prefixed with the namespace:

SET NAMESPACE 'tenant_acme';
CREATE TABLE orders (id BIGINT PRIMARY KEY, amount FLOAT64);
-- Internally stored as: tenant_acme.orders

-- Explicit cross-namespace reference
SELECT * FROM tenant_beta.orders;

Monitoring

Query the namespace metadata directly:

SELECT * FROM __pdb_stat_namespaces;

This virtual table exposes namespace name, owner, status, creation time, quotas, and current usage in a single row per namespace.