Arquitetura Multi-Tenant para SaaS

Quando Usar Esta Habilidade

• O usuário está construindo um aplicativo SaaS onde vários clientes compartilham o mesmo banco de dados
• O usuário pergunta sobre isolamento de tenant, segurança em nível de linha ou prevenção de vazamento de dados
• O usuário precisa delimitar todas as consultas ao banco de dados para um tenant específico sem cláusulas WHERE manuais
• O usuário pergunta sobre as compensações entre schema compartilhado vs schema por tenant vs banco de dados por tenant
• O usuário está implementando endpoints de administrador que devem acessar dados entre tenants
• O usuário precisa adicionar colunas tenant_id a um aplicativo existente de tenant único
• O usuário pergunta sobre políticas de RLS (Row-Level Security) do PostgreSQL para isolamento de tenant
• O usuário está construindo middleware ciente de tenant em rotas de API Express, Fastify ou Next.js

NÃO use esta habilidade quando:

• O usuário está construindo um aplicativo para um único usuário sem infraestrutura compartilhada
• O usuário pergunta apenas sobre autenticação sem escopo de tenant (use uma habilidade de autenticação em vez disso)
• O usuário precisa de design geral de schema de banco de dados sem requisitos de multi-tenancy

Fluxo de Trabalho Principal

1. Determine o modelo de tenancy. Pergunte ao usuário sobre suas expectativas de escala e requisitos de isolamento. Para a maioria dos aplicativos SaaS com menos de 1000 tenants, schema compartilhado com uma coluna tenant_id em cada tabela é o padrão correto. Schema por tenant adiciona sobrecarga operacional (migrações executadas N vezes). Banco de dados por tenant só é justificado quando os tenants têm requisitos regulatórios de residência de dados.

2. Adicione tenant_id a todas as tabelas com escopo de tenant. A coluna deve ser NOT NULL, do tipo UUID ou TEXT, e incluída em todos os índices compostos. Nunca permita que uma tabela com escopo de tenant exista sem esta coluna — uma tenant_id ausente é um vazamento de dados iminente.

3. Configure o Row-Level Security (RLS) do PostgreSQL. Crie uma política em cada tabela com escopo de tenant que filtre linhas por current_setting('app.current_tenant_id'). Isso funciona como uma rede de segurança em nível de banco de dados — mesmo que o código do aplicativo esqueça uma cláusula WHERE, o RLS bloqueia leituras entre tenants.

4. Construa middleware ciente de tenant. No início de cada requisição, extraia o tenant_id da sessão autenticada ou das declarações JWT. Defina-o na conexão do banco de dados usando SET LOCAL app.current_tenant_id = '...' dentro de uma transação. Todas as consultas subsequentes nessa requisição herdarão o escopo do tenant automaticamente.

5. Escopo de todas as consultas ORM por tenant. Se estiver usando Prisma, aplique um middleware global que injete where: { tenantId } em cada chamada findMany, findFirst, update e delete. Se estiver usando Drizzle, crie um construtor de consulta base que inclua o filtro de tenant. Nunca confie que os desenvolvedores se lembrem de adicionar o filtro manualmente.

6. Lide com migrações cientes de tenant. Cada migração de nova tabela deve incluir tenant_id como uma coluna. Escreva uma regra de linting ou verificação de CI que rejeite qualquer migração que crie uma tabela sem tenant_id, a menos que a tabela seja explicitamente marcada como global (por exemplo, plans, feature_flags).

7. Construa rotas de administrador entre tenants separadamente. Endpoints de administrador que agregam dados entre tenants devem ignorar o RLS explicitamente usando SET LOCAL role = 'admin_bypass' ou uma função de banco de dados dedicada. Essas rotas devem ser protegidas por um fluxo de autenticação de administrador separado — nunca reutilize sessões de usuário de tenant para acesso de administrador.

8. Implemente o provisionamento de tenant. Quando um novo cliente se inscreve, crie seu registro de tenant, semeie dados padrão (funções, configurações, estado de onboarding) e atribua o usuário fundador. Envolva isso em uma transação de banco de dados para que o provisionamento parcial nunca deixe registros órfãos.

Exemplos

Exemplo 1: Política RLS do PostgreSQL para Isolamento de Tenant

-- Enable RLS on the table
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
ALTER TABLE projects FORCE ROW LEVEL SECURITY;

-- Policy: users can only see rows where tenant_id matches the session variable
CREATE POLICY tenant_isolation ON projects
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

-- Policy for INSERT: new rows must match the current tenant
CREATE POLICY tenant_insert ON projects
  FOR INSERT
  WITH CHECK (tenant_id = current_setting('app.current_tenant_id')::uuid);

Exemplo 2: Middleware Express que Define o Contexto do Tenant por Requisição

import { Pool } from "pg";

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

async function tenantMiddleware(req, res, next) {
  const tenantId = req.auth?.tenantId; // extraído do JWT durante a autenticação
  if (!tenantId) return res.status(403).json({ error: "No tenant context" });


…