PolarDB:Multi-tenant data isolation solution for PolarDB Supabase

Architectural principles

This solution is based on four core principles:

• Data isolation: Each tenant's data is stored in a separate database schema, preventing data leakage at the logical level.

• Zero-trust access control: Every API request must pass through a mandatory, automated security checkpoint that verifies its identity and intent.

• Dynamic automation: Platform configurations, such as APIs for new tenants, are updated dynamically without service interruptions. Tenant and user lifecycle management is fully automated.

• Developer-friendly: All complex security logic is encapsulated in the backend, allowing frontend developers to focus on business logic and user experience.

Role-based three-layer defense system

The security model is built around three core roles, each with clear responsibilities and robust isolation boundaries.

Core components

The following are the core components of the multi-tenant architecture and their functions.

Architecture overview

Tenant creation and automatic API publishing

This workflow describes how to create a new tenant for instant and seamless onboarding.

1. The platform administrator initiates a command to create a new tenant through the SaaS backend.

2. The SaaS backend calls the Kong Gateway's tenant management endpoint, /auth/v1/admin/instances.

3. Kong Gateway forwards the request to Supabase Auth, which runs with service_role permissions.

4. Supabase Auth completes the following operations within a single transaction: writes the tenant record, creates the tenant's dedicated schema and role, and sends a "configuration update" notification.

5. After receiving the configuration update signal, Kong Gateway reloads its routes and service configurations to automatically publish the APIs for the new tenant.

Using the platform's internal real-time notification mechanism, this approach avoids service restarts during configuration changes, ensuring high platform availability.

User registration and automatic tenant assignment

The following workflow describes how a new user is automatically assigned to the correct tenant upon registration:

1. The user submits registration information through the frontend application.

2. The frontend calls the standard registration endpoint, including the tenant access identifier (UUID) as a declaration of tenancy.

3. Supabase Auth creates a user record that includes the tenant access identifier (UUID).

4. The database automatically resolves ownership by writing the tenant ID based on the tenant access UUID.

During registration, the frontend only needs to declare the current tenant by providing the tenant access identifier (UUID). The backend and database automatically handle the user-tenant binding. The actual security boundary is enforced by mechanisms such as email or phone verification and business approval workflows, rather than by the UUID itself.

Data access for authenticated users

When an authenticated user requests data, the system performs the following security checks:

1. The user initiates a data request through the frontend application (for example, by clicking "Refresh My Orders").

2. The request includes a JWT (the "digital passport"), which declares the intent to access a specific tenant's data.

3. The request is automatically routed to the automated security checkpoint.

4. The security checkpoint performs a mandatory check: it decodes the user's identity from the JWT and compares it with the request's intent (which tenant's resource is being accessed).

5. If the identity and intent match, the request is executed within the corresponding tenant's schema sandbox, and the data is returned.

If a user attempts to access another tenant's data by tampering with the request, the security checkpoint immediately intercepts it upon detecting a mismatch between intent and identity. This ensures the request never reaches the database.

Anonymous access to public tenant data

For unauthenticated, anonymous access, the security checkpoint verifies the request's tenancy by checking the tenant access identifier (UUID). This ensures that anonymous traffic is also strictly confined within the authorized tenant's scope.

Any anonymous user with a tenant's access UUID can access that tenant's public data (subject to RLS policies), providing a security level equivalent to standard Supabase anonymous access. Actual access control is still provided by the database's RLS (Row Level Security) policies and business permission design.

Supabase Auth: Bind identities to tenants

• Unified tenant identifier: The platform generates a unique tenant ID (Instance ID) when a tenant is created and establishes an independent configuration space for that tenant within Supabase Auth.

• Tenant assignment during registration and login: During registration or login, the frontend includes the current tenant's ID. Supabase Auth writes this ID to the user's profile and encodes it into the JWT upon issuance.

• Automatic isolation during sessions: For all subsequent requests, an authenticated user only needs to include the JWT. The authentication layer parses the tenant ID from the token, and the database hook matches it against the request's intent.

PostgREST: Isolate REST APIs for multi-tenancy

• Request-level tenant context injection: When PostgREST receives a request, it extracts the tenant identifier from the request headers (such as X-Instance-ID or JWT claims) and automatically switches to the corresponding tenant's schema to execute the query.

• Automated tenant routing: Each API request is automatically routed to the correct tenant's data sandbox, so developers do not need to manually specify schema names in their business SQL.

• Collaboration with RLS policies: SQL queries generated by PostgREST are automatically constrained by row-level security (RLS) policies. This provides defense-in-depth, as RLS will filter data at the row level even if a request attempts to bypass tenant schema restrictions.

Edge Functions: Multi-tenant logic and extensibility

• Layering of global and tenant functions: The platform can implement "global functions" for logic shared by all tenants and "tenant functions" for custom requirements of individual tenants. The two are distinguished by the tenant ID.

• Tenant context propagation in the call chain: When calling an Edge Function, the current tenant's identifier is passed along. The function uses this context internally to access the corresponding schema, secrets, and external services.

Postgres Meta: Tenant-level metadata and custom SQL

• Metadata view isolation: When viewing table structures or function lists through Postgres Meta, you must explicitly specify the target tenant. Postgres Meta switches to that tenant's corresponding database role and search_path before executing the query, returning only objects visible to that tenant.

• Secure channel for custom SQL: When the SaaS backend needs to execute a one-time SQL script for a specific tenant, it does so through Postgres Meta within that tenant's sandbox. This prevents accidental operations from affecting other tenants' data.

Prerequisites: Enable multi-tenant mode

To begin, enable the multi-tenant feature in your PolarDB Supabase application. On the Supabase application details page, go to the Configure section and set the following parameter:

studio.MULTI_TENANT_ENABLED=true

This setting enables multi-tenant mode, allowing components like PostgREST, Auth, and Meta to recognize and handle tenant isolation logic.

For platform developers: SaaS backend integration

As a SaaS platform developer, your core tasks include:

• Manage the tenant lifecycle: Create, query, update, and delete tenants.

• Initialize the tenant data structure: Create the necessary database tables, views, functions, and RLS policies for new tenants.

You accomplish both of these tasks using the standard RESTful APIs provided by Supabase without direct database manipulation.

Authorization: Bearer <SERVICE_ROLE_KEY>
apikey: <SERVICE_ROLE_KEY>

async function createNewTenant(id: string, name: string) {
  const response = await fetch('https://<your-supabase-url>/auth/v1/admin/instances', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.SERVICE_ROLE_KEY}`,
      'apikey': process.env.SERVICE_ROLE_KEY
    },
    body: JSON.stringify({ id, name })
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Failed to create tenant: ${error.message}`);
  }

  return await response.json();
}

For tenant developers: Application building

As a tenant developer, your development process is nearly identical to building a standard single-tenant Supabase application.

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  global: {
    headers: {
      'X-Instance-ID': INSTANCE_ID
    }
  }
});

async function handleSignUp(email: string, password: string) {
  const { data, error } = await supabase.auth.signUp({
    email,
    password
  });
  // ... handle the result
}

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  global: {
    headers: {
      'X-Instance-ID': INSTANCE_ID
    }
  }
});

async function getProducts() {
  const { data: products, error } = await supabase
    .from('products')
    .select('*');

  // The 'products' array only contains data belonging to the current tenant.
}

import { createClient } from '@supabase/supabase-js';

const INSTANCE_ID = 'your-instance-uuid';

const publicSupabaseClient = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
  global: {
    headers: {
      'X-Instance-ID': INSTANCE_ID
    }
  }
});

async function getPublicPosts() {
  const { data, error } = await publicSupabaseClient
    .from('public_posts')
    .select('*');
}