Skip to main content
ClaudeChatGPT

Multi-Tenancy

Use this guide to choose between project-based isolation and RLS-based isolation for multi-tenant Wren AI deployments.

Wren AI supports multiple approaches to building multi-tenant architectures, allowing teams to choose the model that best fits their security, scalability, and operational requirements.

This document outlines the two recommended patterns and provides guidance on when to use each.

Overview of Supported Approaches​

Wren AI supports two primary multi-tenancy models:

  1. Project-Based Multi-Tenancy
  2. Row-Level Security (RLS)-Based Multi-Tenancy

Both approaches are production-ready and can be used independently or combined depending on organizational needs.

1. Project-Based Multi-Tenancy​

Architecture​

In this model, each tenant is isolated into its own Wren AI project.

  • One project = one tenant
  • Each project has its own:
    • Context layer
    • Data source connections
    • Security configuration
    • Query history and metadata

How It Works​

  • A new project is created for each tenant using the Projects API
  • Tenant-specific users and credentials are assigned to that project
  • All queries and data access are fully isolated at the project boundary

Advantages​

  • Strong isolation between tenants
  • Clear separation of environments
  • Suitable for regulated or high-security use cases
  • Allows tenant-specific schema or data model customization

Trade-Offs​

  • Schema or semantic updates must be applied across all projects
  • Higher operational overhead at scale
  • Less efficient when managing a large number of tenants with identical schemas
  • Tenants require fully isolated environments
  • Data models differ significantly between tenants
  • Regulatory or compliance requirements mandate strict separation
  • The number of tenants is relatively small

Architecture​

In this model, all tenants share the same tables and schema, while access is controlled through row-level security policies.

  • Single project
  • Shared context layer
  • Tenant isolation enforced by data policies

How It Works​

  1. Your application passes session properties when calling the Wren AI API
  2. These session properties contain tenant context (e.g., organization ID, role, region)
  3. Wren AI applies data policies that filter rows dynamically based on those properties

Example​

If session_property.organization_id = "wrenai"
→ User can only access rows where organization_id = "wrenai"

Advantages​

  • Single source of truth for schema and context layer
  • Significantly easier to maintain at scale
  • No duplication of projects or models
  • Ideal for SaaS platforms with many tenants

Trade-Offs​

  • Requires careful design of RLS policies
  • Assumes a consistent schema across tenants
  • Tenant isolation depends on correct policy configuration
  • All tenants share the same schema structure
  • Tenant separation is based on attributes such as:
    • Organization ID
    • Account ID
    • User role or region
  • You operate a multi-tenant SaaS platform
  • Operational simplicity and scalability are priorities

Implementing RLS-Based Multi-Tenancy​

A typical RLS implementation with Wren AI includes the following steps:

1. Define Tenant Context​

Identify the attributes that determine tenant access, such as:

  • organization_id
  • account_id
  • user_role
  • region

2. Pass Session Properties​

Include tenant context in each API request to Wren AI:

  • Session properties are passed from your application
  • They represent the authenticated user’s context

3. Configure Data Policies​

Create data policies in Wren AI that:

  • Reference session properties
  • Filter rows dynamically based on tenant context
  • Enforce consistent access rules across all queries

4. Enforce Tenant Context at Query Time​

Ensure every request from your application includes the correct tenant session properties so Wren AI can enforce access control automatically.

Choosing the Right Approach​

RequirementRecommended Approach
Full tenant isolationProject-Based
Large number of tenantsRLS-Based
Shared schemaRLS-Based
Tenant-specific schemasProject-Based
Low operational overheadRLS-Based
Strict regulatory isolationProject-Based

Best Practices​

  • Prefer RLS-based multi-tenancy when schemas are consistent
  • Keep tenant identifiers explicit and immutable
  • Treat session properties as part of your security boundary
  • Regularly audit data policies to prevent unintended access
  • Start with RLS and move to project isolation only when required