BoilerShelf

Part 10 · Building AI products

Multi-Tenant RAG Data Isolation

Follow tenant permissions through retrieval, PostgreSQL, files, caches, background jobs, and conversation memory.

B

BoilerShelf Team

November 16, 2026 · 5 min read

Three stacks of teal document tiles in separate ivory compartments.

Short answer: Multi-tenant RAG data isolation means every request, job and session carries a tenant ID that the server has verified, and every retrieval query, cache, file link and background job uses it. Enforce the scope in the database with row-level security as well as in application filters, and test it with two synthetic workspaces.

How do you establish a trusted tenant context?

Every RAG request, job and session needs a trusted tenant context. A route may identify which workspace the user wants, but the server must verify current membership and the requested permission before turning that selection into an authorized tenant ID. Apply tenant and document permissions inside vector and lexical candidate selection. Use the same scope for reranking inputs, citations and document reads.

Choose among shared tables with enforced policies, separate schemas or collections with managed credentials, and separate deployments where stronger operational separation is required. Collections and namespaces organize data. Their use as a security boundary depends on service-side access controls and credential scope. In a shared Qdrant collection, derive the tenant filter from trusted context and apply it to every search and mutation.

Sources: OWASP multi-tenant security · Qdrant multitenancy

How do you enforce tenant isolation with PostgreSQL row-level security?

A policy needs both clauses: USING controls which rows are visible, and WITH CHECK controls the values of new and updated rows. Use a non-owner runtime role without superuser or BYPASSRLS privileges, including through role memberships. Keep migration credentials separate and grant the runtime only operation-specific permissions. The sample uses a NOLOGIN role to group grants. The application login needs the intended privileges through role membership. FORCE ROW LEVEL SECURITY applies policies to the table owner during normal access, while superusers and BYPASSRLS roles bypass them.

-- Run as the deployment owner. The application uses a separate role.
CREATE ROLE rag_runtime NOLOGIN NOSUPERUSER NOBYPASSRLS;

CREATE TABLE chunks (
    id uuid PRIMARY KEY,
    tenant_id uuid NOT NULL,
    content text NOT NULL
);
CREATE INDEX chunks_tenant_idx ON chunks (tenant_id);

ALTER TABLE chunks ENABLE ROW LEVEL SECURITY;
ALTER TABLE chunks FORCE ROW LEVEL SECURITY;

CREATE POLICY chunks_by_tenant ON chunks
    FOR ALL TO rag_runtime
    USING (
        tenant_id = NULLIF(current_setting('app.tenant_id', true), '')::uuid
    )
    WITH CHECK (
        tenant_id = NULLIF(current_setting('app.tenant_id', true), '')::uuid
    );

GRANT SELECT, INSERT, UPDATE, DELETE ON chunks TO rag_runtime;

Open a database transaction. Within it, set the validated tenant using a parameterized SELECT set_config('app.tenant_id', $1::text, true), then run the scoped reads and writes on the same connection before commit or rollback. With the sample policy, missing or empty context yields no visible rows and rejects writes. A malformed UUID causes an error. PostgreSQL restores the prior value at transaction end, so avoid setting tenant context at session scope and test the actual pool integration.

A custom setting is trusted application context, so keep it behind server-side authorization and parameterized queries. It is a guard against missed filters under those assumptions. Extend authorization to document-level roles where needed. Where chunks reference documents, a tenant-aware foreign key on tenant_id and document_id can prevent cross-tenant associations.

Sources: PostgreSQL RLS · PostgreSQL configuration functions

Where else does the tenant scope have to apply?

SurfaceControl to document
Vector and searchApply server-derived tenant and document filters in vector and text queries. Preserve the same scope when fetching by ID or resolving source links.
Files and citationsPrivate objects, membership and document checks before issuing short-lived links. Treat each presigned URL like a bearer credential.
Caches and embeddingsScope answer, retrieval and embedding caches by tenant. Where document access differs, include the effective grant scope or validate permissions on lookup. Invalidate after grant, document or corpus changes. Treat private embeddings as sensitive derived data.
Jobs and memoryCarry verified tenant and resource IDs in trusted job records, recheck the target before changing data, and set database context inside each transaction. Scope checkpoints and conversation IDs to tenant and authorized users.
Logs and lifecycleMinimize stored content and restrict trace access. Define export authorization and deletion steps for files, vectors, caches, checkpoints, traces and retained backups.

Sources: LangGraph persistence · S3 presigned URLs

How do you test tenant isolation?

The runnable SQL passed tests on PostgreSQL 18.6 (PGlite) for scoped reads and writes, write checks, absent context and transaction reset. Integration coverage still needs the deployed pool, configured roles and service boundaries. Use two synthetic workspaces and a restricted document in one of them. Drive the real app entry points and assert that unauthorized data is neither retrieved nor included in the prompt, response, citations, exports or logs.

Add cases for members with different permissions inside one tenant, identical search terms in different workspaces, a permission change after caching, reused connections after rollback, and a background job that becomes unauthorized before it runs. Verify denial at object download, conversation or checkpoint access, and support tools. Keep real client data out of these tests.

Frequently asked questions

Is a tenant_id column enough to separate clients?

Only if every query filters on it, and one forgotten condition leaks data. Row-level security moves the rule into the database, so a forgotten filter returns nothing instead of everything.

Should each tenant get its own vector collection?

It works for tens of tenants and makes isolation easy to reason about. For many small tenants, a shared table with an enforced filter is easier to operate. Choose by tenant count and by what each client's contract requires.

What should happen when a client asks for their data to be deleted?

Delete the rows, vectors, files, caches and conversation history for that tenant, and state in advance how long backups are kept. Write the procedure before the first request arrives.

Where to go next

If you deliver RAG applications to several clients, the For agencies page explains how BoilerShelf agency editions are licensed, and the RAG starter kits page lists the kits.

The idea in short

The tenant comes from the authenticated session. It is set for the database transaction, applied inside every retrieval query, carried explicitly into background jobs, and included in storage paths and cache keys, so no step can read another tenant's documents.

Patterns covered: Tenant filter in the query · Row-level security · Scoped caches · Cross-tenant tests

  • RAG
  • Multi tenancy
  • Security
  • PostgreSQL
  • Architecture

New guides and boilerplates, by email

Leave your email and we will tell you when a new guide or boilerplate is published.

All guides