Multi-Tenancy Best Practices

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 efficient isolation mode, adding under 2% overhead to queries. HeliosDB automatically injects tenant filters into 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_id());

-- Set tenant context (done automatically by HeliosProxy)
SET heliosdb.tenant_id = 'acme-corp';

-- This query automatically 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 sub-millisecond (in-memory lookup) and adds less than 100μs to 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