Multitenancy in Practice: A Production-Grade Implementation Guide

import { AsyncLocalStorage } from "node:async_hooks";

export interface TenantContext {
  tenantId: string;
  userId?: string;
}

// AsyncLocalStorage carries tenant context through the whole async call
// chain without threading it through every function signature.
export const tenantStorage = new AsyncLocalStorage<TenantContext>();

export function getTenantId(): string {
  const ctx = tenantStorage.getStore();
  if (!ctx?.tenantId) {
    // Failing closed is critical: never run an unscoped query by default.
    throw new Error("No tenant context — refusing to run an unscoped query");
  }
  return ctx.tenantId;
}

export function runWithTenant<T>(ctx: TenantContext, fn: () => T): T {
  return tenantStorage.run(ctx, fn);
}

import type { Request, Response, NextFunction } from "express";
import { runWithTenant } from "./tenant-context";
import { verifyJwt } from "../auth/jwt";

export async function tenantMiddleware(
  req: Request,
  res: Response,
  next: NextFunction,
) {
  try {
    // 1. Prefer the signed token claim — it cannot be forged.
    const token = req.headers.authorization?.replace("Bearer ", "");
    let tenantId: string | undefined;
    let userId: string | undefined;

    if (token) {
      const claims = await verifyJwt(token);
      tenantId = claims.tenantId;
      userId = claims.sub;
    }

    // 2. Fall back to subdomain for unauthenticated, tenant-scoped routes
    //    (e.g. a tenant's public login page).
    if (!tenantId) {
      const host = req.hostname;              // acme.app.com
      const sub = host.split(".")[0];
      if (sub && sub !== "app" && sub !== "www") {
        tenantId = await resolveTenantIdBySlug(sub);
      }
    }

    if (!tenantId) {
      return res.status(400).json({ error: "Unable to resolve tenant" });
    }

    // 3. Bind context for the remainder of the async request lifecycle.
    runWithTenant({ tenantId, userId }, () => next());
  } catch (err) {
    next(err);
  }
}

import {
  PrimaryGeneratedColumn,
  Column,
  Index,
  CreateDateColumn,
  UpdateDateColumn,
} from "typeorm";

export abstract class TenantBaseEntity {
  @PrimaryGeneratedColumn("uuid")
  id: string;

  // Every tenant-owned row carries this. Indexed because every query filters on it.
  @Index()
  @Column("uuid")
  tenantId: string;

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;
}

import { Entity, Column, Index } from "typeorm";
import { TenantBaseEntity } from "../common/tenant-base.entity";

@Entity("projects")
// Composite index: tenant-scoped lookups by status stay fast at scale.
@Index(["tenantId", "status"])
export class Project extends TenantBaseEntity {
  @Column()
  name: string;

  @Column({ default: "active" })
  status: "active" | "archived";
}

import {
  Repository,
  ObjectLiteral,
  FindManyOptions,
  FindOneOptions,
  DeepPartial,
} from "typeorm";
import { getTenantId } from "../tenant/tenant-context";

// Wraps a TypeORM repository so tenant scoping is automatic and unavoidable.
export class TenantRepository<T extends ObjectLiteral> {
  constructor(private readonly repo: Repository<T>) {}

  private scoped<O extends { where?: any }>(options: O = {} as O): O {
    const tenantId = getTenantId();
    const where = options.where;
    return {
      ...options,
      where: Array.isArray(where)
        ? where.map((w) => ({ ...w, tenantId }))
        : { ...(where ?? {}), tenantId },
    };
  }

  find(options?: FindManyOptions<T>) {
    return this.repo.find(this.scoped(options));
  }

  findOne(options: FindOneOptions<T>) {
    return this.repo.findOne(this.scoped(options));
  }

  async create(data: DeepPartial<T>) {
    const entity = this.repo.create({ ...data, tenantId: getTenantId() });
    return this.repo.save(entity);
  }

  async update(id: string, data: DeepPartial<T>) {
    // Scope the update so one tenant can never mutate another's row by id.
    return this.repo.update({ id, tenantId: getTenantId() } as any, data as any);
  }

  async delete(id: string) {
    return this.repo.delete({ id, tenantId: getTenantId() } as any);
  }
}

-- Enable RLS on the table
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
-- Force it even for the table owner (don't exempt the app's role)
ALTER TABLE projects FORCE ROW LEVEL SECURITY;

-- Rows are visible/writable only when they match the session's tenant.
CREATE POLICY tenant_isolation ON projects
  USING (tenant_id = current_setting('app.tenant_id', true)::uuid)
  WITH CHECK (tenant_id = current_setting('app.tenant_id', true)::uuid);

import { DataSource } from "typeorm";
import { getTenantId } from "../tenant/tenant-context";

// Runs work in a transaction with the Postgres session bound to the tenant,
// so RLS policies apply to every statement inside.
export async function withTenantTransaction<T>(
  dataSource: DataSource,
  work: (manager: import("typeorm").EntityManager) => Promise<T>,
): Promise<T> {
  const tenantId = getTenantId();
  return dataSource.transaction(async (manager) => {
    // set_config(..., true) = scoped to this transaction only.
    await manager.query("SELECT set_config('app.tenant_id', $1, true)", [tenantId]);
    return work(manager);
  });
}

import { AppDataSource } from "../src/data-source";

async function migrateAllSchemas() {
  await AppDataSource.initialize();

  const tenants: { schema: string }[] = await AppDataSource.query(
    "SELECT schema_name AS schema FROM information_schema.schemata WHERE schema_name LIKE 'tenant_%'",
  );

  for (const { schema } of tenants) {
    const runner = AppDataSource.createQueryRunner();
    try {
      await runner.connect();
      await runner.startTransaction();
      await runner.query(`SET search_path TO "${schema}"`);
      // Run pending migrations against this schema's search_path.
      await AppDataSource.runMigrations({ transaction: "none" });
      await runner.commitTransaction();
      console.log(`✓ migrated ${schema}`);
    } catch (err) {
      await runner.rollbackTransaction();
      console.error(`✗ failed ${schema}:`, err);
      // Keep going so one bad tenant doesn't block the rest.
    } finally {
      await runner.release();
    }
  }
  await AppDataSource.destroy();
}

migrateAllSchemas();

import { DataSource } from "typeorm";
import { getTenantId } from "./tenant-context";

const pool = new Map<string, DataSource>();

async function lookupTenantDbConfig(tenantId: string) {
  // Fetch connection details from a central "control plane" database.
  // Cache this lookup in production to avoid a round-trip per request.
  return getControlPlaneConnection(tenantId); // { host, database, ... }
}

export async function getTenantDataSource(): Promise<DataSource> {
  const tenantId = getTenantId();

  const existing = pool.get(tenantId);
  if (existing?.isInitialized) return existing;

  const config = await lookupTenantDbConfig(tenantId);
  const ds = new DataSource({
    type: "postgres",
    host: config.host,
    database: config.database,
    username: config.username,
    password: config.password,
    entities: ["dist/**/*.entity.js"],
    // Keep pools small per tenant; you may have many tenants per process.
    extra: { max: 5 },
  });

  await ds.initialize();
  pool.set(tenantId, ds);
  return ds;
}

import { getTenantId } from "../tenant/tenant-context";

// A shared Redis cache MUST namespace keys, or tenant A reads tenant B's value.
function tenantKey(key: string): string {
  return `t:${getTenantId()}:${key}`;
}

export async function cacheGet(redis: Redis, key: string) {
  return redis.get(tenantKey(key));
}

export async function cacheSet(redis: Redis, key: string, value: string, ttl = 300) {
  return redis.set(tenantKey(key), value, "EX", ttl);
}

import { Worker } from "bullmq";
import { runWithTenant } from "../tenant/tenant-context";

// When enqueueing: always include the tenant.
//   await emailQueue.add("welcome", { tenantId: getTenantId(), userId });

new Worker("email", async (job) => {
  const { tenantId, userId } = job.data;
  if (!tenantId) throw new Error("Job missing tenantId — refusing to process");

  // Re-establish context so downstream queries are correctly scoped.
  await runWithTenant({ tenantId, userId }, async () => {
    await sendWelcomeEmail(userId);
  });
});

import { runWithTenant } from "../src/tenant/tenant-context";

describe("tenant isolation", () => {
  it("never returns another tenant's rows", async () => {
    // Seed a project for tenant A.
    const project = await runWithTenant({ tenantId: "tenant-a" }, () =>
      projects.create({ name: "Secret Plan" }),
    );

    // Tenant B must not see it.
    const leaked = await runWithTenant({ tenantId: "tenant-b" }, () =>
      projects.findOne({ where: { id: project.id } }),
    );
    expect(leaked).toBeNull();

    // Tenant B must not be able to update it.
    const result = await runWithTenant({ tenantId: "tenant-b" }, () =>
      projects.update(project.id, { name: "Hijacked" }),
    );
    expect(result.affected).toBe(0);
  });

  it("refuses to run without tenant context", async () => {
    await expect(projects.find()).rejects.toThrow(/No tenant context/);
  });
});