0Pricing
Next.js 15 Fullstack (App Router + Server Actions) · 课时

行级租户数据隔离模式

通过行级安全策略和限定范围的数据访问层，在查询中强制执行租户边界。

行级租户数据隔离模式 是 CoddyKit 上的免费 Next.js 15 Fullstack (App Router + Server Actions) 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Next.js 15 Fullstack (App Router + Server Actions) 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Tenant Isolation Is a First-Class Concern

In a multi-tenant SaaS application, every user belongs to a tenant (an organisation, workspace, or account). Without explicit isolation, a single bug in a query can expose one tenant's data to another — a catastrophic security breach.

  • Logical isolation stores all tenants in shared tables, distinguished by a tenant_id column.
  • Physical isolation gives each tenant their own schema or database — simpler security, but far more expensive to operate.
  • Most SaaS products choose logical isolation and enforce boundaries in the application layer, the database layer, or both.

This lesson focuses on row-level isolation patterns inside a Next.js 15 App Router application backed by PostgreSQL, showing how to make tenant leakage structurally impossible rather than relying on developer discipline alone.

The Naive Approach and Its Risks

The most common mistake is sprinkling WHERE tenant_id = ? manually throughout the codebase. This pattern is fragile: any query that forgets the clause leaks data.

Consider this vulnerable Server Action:

'use server';
import { db } from '@/lib/db';

// DANGEROUS: tenant_id is never checked
export async function getInvoices() {
  // This returns ALL invoices from ALL tenants!
  const invoices = await db.query(
    'SELECT * FROM invoices ORDER BY created_at DESC'
  );
  return invoices.rows;
}

Resolving the Current Tenant in Next.js 15

Before we can scope any query, we need a reliable way to identify the current tenant. In Next.js 15, the idiomatic place is a server-side utility that reads the session from a cookie or JWT and resolves the tenant.

Key rules:

  • Never trust a tenant ID supplied by the client in a request body or query string — always derive it from the verified session.
  • Throw an error early if no valid session exists, so downstream code can never accidentally execute without a tenant context.
// lib/tenant.ts
import { cookies } from 'next/headers';
import { verifyJwt } from '@/lib/auth';

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

export async function requireTenantContext(): Promise<TenantContext> {
  const cookieStore = await cookies();
  const token = cookieStore.get('session')?.value;

  if (!token) {
    throw new Error('Unauthenticated');
  }

  const payload = await verifyJwt(token);

  if (!payload?.tenantId || !payload?.userId) {
    throw new Error('Invalid session: missing tenant context');
  }

  return {
    tenantId: payload.tenantId as string,
    userId: payload.userId as string,
  };
}

Building a Scoped Data Access Layer (DAL)

A scoped data access layer centralises tenant filtering so that no individual query can accidentally omit it. The idea is simple: create repository functions that require a TenantContext parameter, and always apply it.

This makes the tenant boundary visible in every function signature — if you call a data function without a context, TypeScript refuses to compile.

// lib/dal/invoices.ts
import { db } from '@/lib/db';
import type { TenantContext } from '@/lib/tenant';

export interface Invoice {
  id: string;
  tenantId: string;
  amount: number;
  status: string;
  createdAt: Date;
}

export async function listInvoices(
  ctx: TenantContext,
  page = 1,
  pageSize = 20
): Promise<Invoice[]> {
  const offset = (page - 1) * pageSize;

  const result = await db.query<Invoice>(
    `SELECT id, tenant_id AS "tenantId", amount, status, created_at AS "createdAt"
     FROM invoices
     WHERE tenant_id = $1
     ORDER BY created_at DESC
     LIMIT $2 OFFSET $3`,
    [ctx.tenantId, pageSize, offset]
  );

  return result.rows;
}

export async function getInvoiceById(
  ctx: TenantContext,
  invoiceId: string
): Promise<Invoice | null> {
  const result = await db.query<Invoice>(
    `SELECT id, tenant_id AS "tenantId", amount, status, created_at AS "createdAt"
     FROM invoices
     WHERE tenant_id = $1 AND id = $2`,
    [ctx.tenantId, invoiceId]
  );

  return result.rows[0] ?? null;
}

Using the DAL in Server Actions

With the DAL in place, Server Actions become thin orchestrators: resolve the tenant context, call the DAL, and return data. The tenant filter is enforced structurally, not by convention.

Notice that requireTenantContext() is called at the top of every action — if it throws, the action aborts before any data is touched.

'use server';
import { requireTenantContext } from '@/lib/tenant';
import { listInvoices, getInvoiceById } from '@/lib/dal/invoices';

export async function fetchInvoicesAction(page: number = 1) {
  const ctx = await requireTenantContext();
  return listInvoices(ctx, page);
}

export async function fetchInvoiceAction(invoiceId: string) {
  const ctx = await requireTenantContext();

  const invoice = await getInvoiceById(ctx, invoiceId);

  if (!invoice) {
    // Could be not found OR a cross-tenant access attempt —
    // return the same error to avoid leaking existence information.
    throw new Error('Invoice not found');
  }

  return invoice;
}

PostgreSQL Row-Level Security (RLS)

The application-layer DAL is a strong first line of defence, but a second line exists at the database level: PostgreSQL Row-Level Security (RLS). With RLS enabled, the database itself rejects any query that touches rows belonging to a different tenant — even if the application forgets to filter.

The pattern works by:

  • Enabling RLS on every multi-tenant table.
  • Creating a policy that compares tenant_id against a session variable set by the application before each query.
  • Setting the variable via SET LOCAL app.current_tenant_id = '...' inside a transaction.
-- Run once per table during migrations
ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

-- Deny all access by default (belt-and-suspenders)
ALTER TABLE invoices FORCE ROW LEVEL SECURITY;

-- Allow SELECT/INSERT/UPDATE/DELETE only for the current tenant
CREATE POLICY tenant_isolation ON invoices
  USING (tenant_id = current_setting('app.current_tenant_id', true))
  WITH CHECK (tenant_id = current_setting('app.current_tenant_id', true));

-- The app sets this variable in every transaction:
-- SET LOCAL app.current_tenant_id = '<uuid>';

Wiring RLS into the Database Client

To make RLS work automatically, wrap every database operation in a transaction that first sets the app.current_tenant_id session variable. This can be done with a single helper that wraps pg's PoolClient.

This ensures the tenant variable is always set before any query runs, and is automatically cleared when the transaction ends.

// lib/db.ts
import { Pool, PoolClient } from 'pg';

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

export async function withTenantTransaction<T>(
  tenantId: string,
  fn: (client: PoolClient) => Promise<T>
): Promise<T> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    // Scope this setting to the current transaction only
    await client.query(
      `SET LOCAL app.current_tenant_id = $1`,
      [tenantId]
    );
    const result = await fn(client);
    await client.query('COMMIT');
    return result;
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

Updating the DAL to Use RLS Transactions

Now update the DAL functions to use withTenantTransaction. The application-level WHERE tenant_id = $1 filter is kept for clarity and performance (index utilisation), while RLS provides a safety net at the database level.

This defence-in-depth strategy means tenant leakage requires two independent failures simultaneously — significantly reducing risk.

// lib/dal/invoices.ts (updated)
import { withTenantTransaction } from '@/lib/db';
import type { TenantContext } from '@/lib/tenant';
import type { Invoice } from './types';

export async function listInvoices(
  ctx: TenantContext,
  page = 1,
  pageSize = 20
): Promise<Invoice[]> {
  const offset = (page - 1) * pageSize;

  return withTenantTransaction(ctx.tenantId, async (client) => {
    const result = await client.query<Invoice>(
      `SELECT id, tenant_id AS "tenantId", amount, status, created_at AS "createdAt"
       FROM invoices
       WHERE tenant_id = $1
       ORDER BY created_at DESC
       LIMIT $2 OFFSET $3`,
      [ctx.tenantId, pageSize, offset]
    );
    return result.rows;
  });
}

Schema-Per-Tenant Isolation with Prisma

For applications requiring stronger guarantees, a schema-per-tenant approach assigns each tenant their own PostgreSQL schema (e.g., tenant_abc.invoices). This eliminates cross-tenant leakage at the structural level — policies and filters are unnecessary because the data is physically separate.

With Prisma, you can achieve this by dynamically constructing a client that uses a different schema for each request:

// lib/tenant-db.ts
import { PrismaClient } from '@prisma/client';

const clientCache = new Map<string, PrismaClient>();

export function getTenantPrismaClient(tenantId: string): PrismaClient {
  const safeSchema = tenantId.replace(/[^a-z0-9_]/gi, '_');

  if (clientCache.has(safeSchema)) {
    return clientCache.get(safeSchema)!;
  }

  const client = new PrismaClient({
    datasources: {
      db: {
        url: `${process.env.DATABASE_URL}?schema=${safeSchema}`,
      },
    },
  });

  clientCache.set(safeSchema, client);
  return client;
}

// Usage in a Server Action:
// const db = getTenantPrismaClient(ctx.tenantId);
// const invoices = await db.invoice.findMany();

Preventing Insecure Direct Object Reference (IDOR)

Tenant isolation must extend beyond list queries. A common vulnerability called Insecure Direct Object Reference (IDOR) occurs when an attacker changes a resource ID in the URL or request body to access another tenant's record.

The getInvoiceById DAL function already handles this correctly by including AND tenant_id = $1. If the invoice belongs to a different tenant, the query returns zero rows — the same response as a genuinely missing record. This prevents existence leakage.

Always verify ownership via the tenant context, never by trusting that the client-supplied ID is one the current user is allowed to see.

'use server';
import { requireTenantContext } from '@/lib/tenant';
import { withTenantTransaction } from '@/lib/db';

export async function deleteInvoiceAction(invoiceId: string) {
  const ctx = await requireTenantContext();

  await withTenantTransaction(ctx.tenantId, async (client) => {
    const result = await client.query(
      `DELETE FROM invoices
       WHERE id = $1 AND tenant_id = $2`,
      [invoiceId, ctx.tenantId]
    );

    // If rowCount is 0 the invoice either doesn't exist
    // or belongs to another tenant — treat both identically.
    if ((result.rowCount ?? 0) === 0) {
      throw new Error('Invoice not found');
    }
  });
}

Testing Tenant Isolation

Tenant isolation logic must be covered by automated tests. The key scenarios to test are:

  • Happy path: Tenant A can read their own data.
  • Cross-tenant read: Tenant A cannot read Tenant B's records (returns null or empty array).
  • Cross-tenant delete/write: Tenant A's mutation on Tenant B's ID silently does nothing (rowCount = 0).

Use a test database and real SQL to catch regressions that mocks would miss. The following shows a Vitest integration test pattern:

// tests/dal/invoices.test.ts
import { describe, it, expect, beforeAll } from 'vitest';
import { listInvoices, getInvoiceById } from '@/lib/dal/invoices';
import { seedTestData, cleanTestData } from '../helpers/db';

const tenantA = { tenantId: 'tenant-aaa', userId: 'user-1' };
const tenantB = { tenantId: 'tenant-bbb', userId: 'user-2' };

beforeAll(async () => {
  await cleanTestData();
  await seedTestData([
    { id: 'inv-1', tenantId: 'tenant-aaa', amount: 100, status: 'paid' },
    { id: 'inv-2', tenantId: 'tenant-bbb', amount: 200, status: 'pending' },
  ]);
});

describe('listInvoices', () => {
  it('returns only the requesting tenant\'s invoices', async () => {
    const invoices = await listInvoices(tenantA);
    expect(invoices).toHaveLength(1);
    expect(invoices[0].id).toBe('inv-1');
  });
});

describe('getInvoiceById', () => {
  it('returns null when the invoice belongs to a different tenant', async () => {
    // Tenant A tries to fetch Tenant B's invoice
    const invoice = await getInvoiceById(tenantA, 'inv-2');
    expect(invoice).toBeNull();
  });
});

Knowledge Check: Tenant Isolation Strategy

Test your understanding of the key design decisions covered in this lesson.

Recap: Row-Level Tenant Data Isolation Patterns

This lesson established a layered approach to enforcing tenant boundaries in a Next.js 15 App Router application:

  • Session-derived tenant context — always resolve tenantId from a server-verified JWT or session cookie, never from client-supplied input.
  • Scoped Data Access Layer (DAL) — require a TenantContext parameter in every repository function and apply WHERE tenant_id = $1 at the SQL level, making omission a compile-time or code-review error.
  • PostgreSQL Row-Level Security (RLS) — enable RLS as a database-enforced safety net using SET LOCAL app.current_tenant_id inside transactions, so even a buggy query cannot leak data.
  • IDOR prevention — include the tenant check in all single-record lookups and mutations; return identical errors for not-found and cross-tenant access to avoid existence leakage.
  • Schema-per-tenant — an alternative pattern using separate PostgreSQL schemas for stronger structural isolation, at the cost of operational complexity.
  • Integration tests — validate cross-tenant isolation with real queries against a test database, covering both read and write scenarios.

Combining application-layer filtering, database-layer RLS, and typed function signatures creates a multi-layered defence that makes tenant leakage structurally difficult even as the codebase grows.

常见问题解答

「行级租户数据隔离模式」课时是免费的吗？

是的 — 「行级租户数据隔离模式」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Next.js 15 Fullstack (App Router + Server Actions) 课程的其余内容，请升级到 CoddyKit PRO。 Next.js 15 Fullstack (App Router + Server Actions) 课程共包含 4 节课。

「行级租户数据隔离模式」这节课中我会学到什么？

通过行级安全策略和限定范围的数据访问层，在查询中强制执行租户边界。 你通过在浏览器中直接运行的动手代码来练习 Next.js 15 Fullstack (App Router + Server Actions)，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Next.js 15 Fullstack (App Router + Server Actions) 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Next.js 15 Fullstack (App Router + Server Actions) 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。

「行级租户数据隔离模式」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Next.js 15 Fullstack (App Router + Server Actions) 课中编写并运行代码吗？

能。每节 Next.js 15 Fullstack (App Router + Server Actions) 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

  1. 基于子域名与路径的租户解析
  2. 行级租户数据隔离模式
  3. 按租户设置主题与功能开关
  4. 用量计量与订阅限制执行
← 返回 Next.js 15 Fullstack (App Router + Server Actions)