Multi-Tenancy Best Practices

Editor's note (2026-10-15): This 2025 post does not name an edition, and its SQL does not apply to every one. HeliosDB Lite combines row-level security policies with tenant management; confirm that policies apply on the client path you use before relying on them. In the stock HeliosDB Nano server, row-level security is enforced through the embedded API and the REPL; SQL CREATE POLICY and enforcement for REST and wire clients are planned. Row-level security for HeliosDB Full is planned. The overhead and scale figures below were published without an edition, version or fixture and have not been reproduced on current releases; measure on your own workload. See HeliosDB Lite and Nano row-level security.

Building a multi-tenant SaaS application on a shared database is one of the hardest architectural challenges in software engineering. You need data isolation, fair resource allocation, per-tenant performance guarantees, and cost-effective infrastructure — all without the operational burden of managing a database per tenant. HeliosDB's built-in multi-tenancy makes this dramatically simpler.

Isolation Modes

HeliosDB supports four isolation modes, each with different trade-offs:

| Mode     | Isolation Level | Overhead | Use Case                    |
|----------|----------------|----------|-----------------------------|
| Database | Full physical  | < 10%    | Regulated industries, large tenants |
| Schema   | Namespace-level| < 5%     | Medium tenants, compliance needs    |
| Row (RLS)| Logical        | < 2%     | Small tenants, maximum efficiency   |
| Branch   | Copy-on-write  | Minimal  | Development, testing, A/B testing   |

Row-Level Security (RLS)

RLS is the most lightweight isolation mode. In HeliosDB Lite, a policy adds the tenant filter to every query:

-- Enable RLS on a table
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Create a policy
CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_tenant());

-- current_tenant() returns the tenant bound to the session.
-- It is NULL when no tenant context is bound, and the
-- policy then denies the row.

-- With tenant 'acme-corp' bound, this query filters by tenant
SELECT * FROM orders;
-- Equivalent to: SELECT * FROM orders WHERE tenant_id = 'acme-corp'

Resource Quotas

Prevent noisy neighbors from impacting other tenants with per-tenant resource quotas:

-- Define quota policy for standard tenants
CREATE RESOURCE QUOTA standard_plan (
    max_storage = '100 GB',
    max_qps = 1000,
    max_concurrent_queries = 50,
    max_connections = 100,
    max_query_timeout = '300 seconds',
    max_cpu_time = '3600 seconds/hour',
    max_memory = '8 GB'
);

-- Assign quota to a tenant
ALTER TENANT 'acme-corp' SET QUOTA standard_plan;

Quota enforcement is an in-memory lookup on each query's execution path.

Tenant-Aware Connection Pooling

HeliosProxy's multi-tenancy routing automatically identifies tenants and routes connections:

# heliosproxy.toml
[multi_tenancy]
enabled = true
identification = "header"     # header | jwt_claim | schema | database
header_name = "X-Tenant-ID"
default_isolation = "rls"

# Automatic tenant context injection
[multi_tenancy.context]
set_on_connect = true
variable = "heliosdb.tenant_id"

Performance at Scale

| Metric                | Value         | Notes                    |
|-----------------------|---------------|--------------------------|
| Tenant registration   | < 100ms       | Per tenant               |
| RLS overhead          | < 5%          | Query latency impact     |
| Quota check           | < 1ms         | In-memory lookup         |
| Context switch        | < 50μs        | Per tenant switch        |
| Quota enforcement     | < 100μs       | Decision time            |
| Multi-tenant QPS      | 10K+          | Per tenant               |
| Concurrent tenants    | 100K+         | Per cluster              |

Best Practice: Tenant Onboarding Flow

-- 1. Register tenant
INSERT INTO tenants (id, name, plan) VALUES ('acme', 'Acme Corp', 'professional');

-- 2. Assign resource quota
ALTER TENANT 'acme' SET QUOTA professional_plan;

-- 3. Initialize tenant schema (if using schema isolation)
CREATE SCHEMA IF NOT EXISTS tenant_acme;

-- 4. Apply RLS policies (if using row isolation)
-- Policies are inherited from table definitions

-- 5. Provision API key
INSERT INTO api_keys (tenant_id, key_hash) VALUES ('acme', hash_key($1));

Monitoring Per-Tenant Metrics

-- View per-tenant resource usage
SELECT tenant_id,
       query_count,
       avg_latency_ms,
       storage_bytes,
       active_connections,
       quota_utilization_pct
FROM pg_tenant_metrics
ORDER BY query_count DESC;

Multi-tenancy is available in HeliosDB Lite (Professional+) and HeliosDB Full (all tiers). The 7-crate tenancy subsystem in Full provides enterprise features like cost management, automated onboarding, and tenant-aware connection pooling.

← Back to Blog