Opções de modelo de dados multi-tenant para um backend sem código

O problema: manter tenants separados sem reduzir a velocidade

Multi-tenancy significa que um produto de software atende muitos clientes (tenants), e cada tenant só deve ver seus próprios dados. O difícil é fazer isso de forma consistente: não apenas numa tela, mas em toda chamada de API, painel administrativo, exportação e job em background.

Seu modelo de dados impacta as operações do dia a dia mais do que a maioria das equipes espera. Ele molda permissões, relatórios, velocidade de consulta conforme você cresce e o quão arriscado um bug “pequeno” pode ser. Esqueça um filtro e você pode vazar dados. Isole demais e o reporting vira um trabalho manual.

Existem três maneiras comuns de estruturar o modelo de dados multi-tenant em SaaS:

• Um banco de dados onde toda tabela inclui um tenant_id
• Schemas separados por tenant dentro de um mesmo banco
• Bancos de dados separados por tenant

Mesmo que você construa visualmente em um backend sem código, os mesmos trade-offs se aplicam. Ferramentas como AppMaster geram código de backend real e estruturas de banco de dados a partir do seu design, então decisões de modelagem cedo aparecem rápido no comportamento e na performance em produção.

Imagine uma ferramenta de helpdesk. Se cada linha de ticket tem tenant_id, é fácil consultar “todos os tickets abertos”, mas você precisa aplicar checagens de tenant em toda parte. Se cada tenant tiver seu próprio schema ou banco, o isolamento é mais forte por padrão, mas relatórios cross-tenant (como “tempo médio de fechamento entre clientes”) exigem mais trabalho.

O objetivo é separação em que você confie sem adicionar atrito para reporting, suporte e crescimento.

Maneira rápida de escolher: 4 perguntas que reduzem as opções

Não comece pela teoria do banco de dados. Comece por como o produto será usado e o que você precisará operar toda semana.

Quatro perguntas que geralmente deixam a resposta óbvia

1. Quão sensíveis são os dados, e você está sob regras rígidas? Saúde, finanças e contratos estritos costumam empurrar para isolamento mais forte (schema separado ou banco separado). Isso reduz risco e facilita auditorias.

2. Você precisa de reporting cross-tenant com frequência? Se você precisa regularmente de métricas “todos os clientes” (uso, receita, performance), um banco único com tenant_id costuma ser o mais simples. Bancos separados dificultam isso porque você precisa consultar muitos lugares e combinar resultados.

3. Quão diferentes os tenants serão entre si? Se tenants precisarem de campos customizados, workflows próprios ou integrações únicas, schemas ou bancos separados reduzem o risco de mudanças vazarem. Se a maioria dos tenants compartilha a mesma estrutura, tenant_id se mantém limpo.

4. O que sua equipe consegue operar realisticamente? Mais isolamento costuma significar mais trabalho: mais backups, mais migrações, mais peças em movimento e mais pontos para falhas.

Uma abordagem prática é prototipar suas duas principais escolhas e testar os pontos de dor reais: regras de permissão, queries de relatório e como mudanças são aplicadas conforme o modelo evolui.

Abordagem 1: um banco de dados com tenant_id em cada linha

Este é o setup mais comum: todos os clientes compartilham as mesmas tabelas, e todo registro pertencente a um tenant carrega um tenant_id. É operacionalmente simples porque você roda um único banco e um conjunto de migrações.

A regra é rígida: se uma linha pertence a um tenant, ela deve incluir tenant_id, e toda query deve filtrá-lo. Tabelas normalmente com escopo de tenant incluem users, roles, projetos, tickets, faturas, mensagens, metadados de arquivos e tabelas de join que conectam dados do tenant.

Para reduzir vazamentos, trate tenant_id como inegociável:

• Torne tenant_id obrigatório (NOT NULL) nas tabelas com escopo de tenant
• Adicione índices que comecem com tenant_id (por exemplo, tenant_id, created_at)
• Faça regras de unicidade incluírem tenant_id (como e-mail único por tenant)
• Passe tenant_id por toda API e fluxo de negócio, não apenas pelos formulários da UI
• Aplique a checagem no backend, não somente em filtros do cliente

No PostgreSQL, políticas de row-level security podem adicionar uma rede de segurança forte, especialmente quando queries são geradas dinamicamente.

Dados de referência geralmente caem em dois grupos: tabelas compartilhadas (como countries) sem tenant_id, e catálogos com escopo de tenant (como tags customizadas ou pipelines) que incluem tenant_id.

Se você está construindo com AppMaster, um hábito simples evita a maioria dos incidentes: defina tenant_id a partir do tenant do usuário autenticado antes de qualquer operação de leitura ou criação na lógica do Business Process, e mantenha esse padrão consistente.

Impacto nas permissões: o que muda com cada abordagem

Permissões são onde a multi-tenancy vence ou falha. O layout de dados que você escolher muda como você armazena usuários, como delimita queries e como evita momentos de “ops” em telas administrativas.

Com um banco único e tenant_id em cada linha, times frequentemente usam uma única tabela Users compartilhada e conectam cada usuário a um tenant e a um ou mais papéis. A grande regra permanece: toda leitura e escrita deve incluir o escopo do tenant, mesmo para tabelas “pequenas” como settings, tags ou logs.

Com schemas separados, você costuma manter uma camada de identidade compartilhada (login, senha, MFA) em um lugar, enquanto os dados do tenant vivem em um schema por tenant. Permissões viram em parte um problema de roteamento: a app precisa apontar queries para o schema correto antes da lógica de negócio rodar.

Com bancos separados, o isolamento é mais forte, mas a lógica de permissão se desloca para a infraestrutura: escolher a conexão certa, gerenciar credenciais e lidar com contas “globais” de staff.

Em todas as três abordagens, alguns padrões reduzem consistentemente o risco cross-tenant:

• Coloque tenant_id na sessão ou nas claims do token de autenticação e trate-o como obrigatório.
• Centralize as checagens de tenant em um único lugar (middleware ou um Business Process compartilhado), não espalhadas por endpoints.
• Em ferramentas administrativas, mostre o contexto do tenant claramente e exija uma troca explícita de tenant.
• Para acesso de suporte, use impersonação com log de auditoria.

No AppMaster, isso geralmente significa armazenar o contexto do tenant logo após a autenticação e reutilizá-lo em endpoints e Business Processes para que toda query permaneça com escopo. Um agente de suporte só deve ver pedidos depois que a app definiu o contexto do tenant, não porque a UI filtrou por acaso.

Relatórios e performance com o modelo tenant_id

Com a abordagem de banco único e tenant_id, o reporting costuma ser direto. Dashboards globais (MRR, signups, uso) podem rodar uma única query para todos, e relatórios por tenant são a mesma query com um filtro.

O trade-off é performance ao longo do tempo. À medida que as tabelas crescem, um tenant muito ativo pode se tornar um vizinho barulhento, gerando mais linhas, mais escritas e tornando queries comuns mais lentas se o banco tiver que varrer muitos dados.

Indexação mantém esse modelo saudável. A maioria das leituras com escopo de tenant deve usar um índice que comece com tenant_id, para que o banco possa saltar direto para a fatia daquele tenant.

Um bom baseline:

• Adicione índices compostos com tenant_id como primeira coluna (por exemplo, tenant_id + created_at, tenant_id + status, tenant_id + user_id)
• Mantenha índices verdadeiramente globais só quando precisar de queries cross-tenant
• Fique atento a joins e filtros que “esquecem” tenant_id, o que pode causar varreduras lentas

Retention e deleções também precisam de um plano, porque o histórico de um tenant pode inflar tabelas para todos. Se tenants têm políticas de retenção diferentes, considere soft deletes mais arquivamento agendado por tenant, ou mover linhas antigas para uma tabela de archive indexada por tenant_id.

Abordagem 2: schemas separados por tenant

Com schemas separados, você ainda usa um banco PostgreSQL, mas cada tenant recebe seu próprio schema (por exemplo, tenant_42). Tabelas dentro desse schema pertencem apenas a esse tenant. Dá a sensação de dar a cada cliente um “mini banco”, sem o overhead de rodar múltiplos bancos.

Um setup comum mantém serviços globais em um schema compartilhado e dados de tenant em schemas separados. A divisão costuma ser sobre o que deve ser compartilhado entre todos versus o que nunca deve se misturar.

Divisão típica:

• Schema compartilhado: tabela tenants, planos, registros de billing, feature flags, configurações de auditoria
• Schema do tenant: tabelas de negócio como orders, tickets, inventário, projetos, campos customizados
• Um ou outro (depende do produto): users e roles, especialmente se usuários podem acessar múltiplos tenants

Esse modelo reduz o risco de joins cross-tenant porque as tabelas vivem em namespaces diferentes. Também pode facilitar backups ou restores de um tenant ao mirar apenas um schema.

Migrações são o que surpreende times. Quando você adiciona uma nova tabela ou coluna, precisa aplicar a mudança em cada schema de tenant. Com 10 tenants isso é gerenciável. Com 1.000, você precisa de processo: rastrear versões de schema, rodar migrações em lotes e falhar de forma segura para que um tenant quebrado não trave os demais.

Serviços compartilhados como auth e billing geralmente vivem fora dos schemas de tenant. Um padrão prático é auth compartilhada (uma tabela de users com uma tabela de membership por tenant) e billing compartilhado (IDs de cliente Stripe, invoices), enquanto schemas de tenant armazenam dados de negócio do tenant.

Se estiver usando AppMaster, planeje cedo como os modelos do Data Designer mapeiam para schemas compartilhados vs de tenant, e mantenha serviços globais estáveis para que schemas de tenant possam evoluir sem quebrar login ou pagamentos.

Relatórios e performance com schemas separados

Schemas separados oferecem separação mais forte por padrão do que um simples filtro tenant_id, porque tabelas são fisicamente distintas e permissões podem ser aplicadas por schema.

Reporting é ótimo quando a maioria dos relatórios é por tenant. As queries permanecem simples porque você lê das tabelas do tenant sem filtrar constantemente tabelas compartilhadas. Esse modelo também suporta tenants “especiais” que precisam de tabelas extras ou colunas customizadas sem obrigar todo mundo a carregá-las.

Agregação cross-tenant é onde schemas começam a incomodar. Você precisa de uma camada de reporting que consulte muitos schemas, ou mantêm tabelas de resumo compartilhadas em um schema comum.

Padrões comuns:

• Dashboards por tenant que consultam só o schema daquele tenant
• Um schema central de analytics com rollups noturnos de cada tenant
• Jobs de export que copiam dados do tenant para um formato amigável ao data warehouse

A performance costuma ser sólida para workloads por tenant. Índices são menores por tenant, e escritas pesadas em um schema tendem a afetar menos os outros. O trade-off é overhead operacional: provisionar um novo tenant significa criar um schema, rodar migrações e manter todos os schemas alinhados quando o modelo muda.

Schemas são uma boa escolha quando você quer isolamento mais estrito sem o custo de vários bancos, ou quando espera customização por tenant.

Abordagem 3: banco de dados separado por tenant

Com um banco separado por tenant, cada cliente recebe seu próprio banco (ou seu próprio database no mesmo servidor). Esta é a opção mais isolada: se os dados de um tenant são corrompidos, mal configurados ou sob grande carga, é muito menos provável que isso afete outros.

É um bom ajuste para ambientes regulados (saúde, finanças, governo) ou clientes enterprise que exigem separação rígida, regras de retenção customizadas ou desempenho dedicado.

Onboarding vira um workflow de provisionamento. Quando um novo tenant se cadastra, seu sistema precisa criar ou clonar um banco, aplicar o schema base (tabelas, índices, constraints), criar e armazenar credenciais com segurança e rotear requests para o banco correto.

Se você estiver construindo com AppMaster, a escolha de design chave é onde manter o diretório de tenants (um mapa central de tenant para conexão de banco) e como garantir que cada request use a conexão certa.

Upgrades e migrações são o principal trade-off. Uma mudança de schema deixa de ser “rodar uma vez” para ser “rodar para cada tenant”. Isso adiciona trabalho operacional e risco, então times costumam versionar schemas e executar migrações como jobs controlados que rastreiam progresso por tenant.

A vantagem é controle. Você pode migrar tenants grandes primeiro, observar a performance e então liberar mudanças gradualmente.

Relatórios e performance com bancos separados

Bancos separados são os mais simples de raciocinar. Leitura acidental cross-tenant é muito menos provável, e um erro de permissão tende a afetar apenas um tenant.

Performance é também um ponto forte. Consultas pesadas, grandes imports ou um relatório fora de controle no Tenant A não vão deixar o Tenant B lento. Isso protege contra vizinhos barulhentos e permite ajustar recursos por tenant.

O trade-off aparece no reporting. Análises globais ficam mais difíceis porque os dados estão fisicamente separados. Padrões que funcionam na prática incluem copiar eventos-chave ou tabelas para um banco central de reporting, enviar eventos para um dataset estilo warehouse, rodar relatórios por tenant e agregar resultados (quando a contagem de tenants é pequena) e manter métricas de produto separadas dos dados dos clientes.

O custo operacional é outro fator grande. Mais bancos significa mais backups, upgrades, monitoramento e resposta a incidentes. Você também pode atingir limites de conexões mais rápido porque cada tenant pode precisar do seu próprio pool de conexões.

Erros comuns que causam vazamentos de dados ou dor depois

A maioria dos problemas multi-tenant não é uma falha de “grande design”. São omissões pequenas que viram bugs de segurança, reporting bagunçado e limpezas caras. Multi-tenancy funciona quando a separação de tenants é um hábito, não um recurso que você coloca depois.

Um vazamento comum é esquecer o campo de tenant em uma tabela, especialmente tabelas de join como user_roles, invoice_items ou tags. Tudo parece certo até um relatório ou busca juntar por essa tabela e puxar linhas de outro tenant.

Outro problema frequente são dashboards admin que contornam filtros de tenant. Muitas vezes começa como “só para suporte” e depois é reutilizado. Ferramentas no-code não mudam esse risco: toda query, business process e endpoint que lê dados de tenant precisa do mesmo escopo de tenant.

IDs também dão dor de cabeça. Se você compartilhar IDs legíveis por humanos entre tenants (como order_number = 1001) e assumir que são globalmente únicos, ferramentas de suporte e integrações vão misturar registros. Mantenha identificadores com escopo de tenant separados das chaves primárias internas e inclua contexto de tenant nas lookups.

Por fim, times subestimam migrações e backups conforme escalam. O que é fácil com 10 tenants pode ser lento e arriscado com 1.000.

Checagens rápidas que evitam a maioria dos problemas:

• Torne a propriedade por tenant explícita em todas as tabelas, inclusive nas de join.
• Use um padrão único de scoping de tenant e reaplique-o em toda parte.
• Garanta que relatórios e exports não rodem sem escopo de tenant (a menos que sejam realmente globais).
• Evite identificadores ambíguos por tenant em APIs e ferramentas de suporte.
• Pratique restore e passos de migração cedo, não depois do crescimento.

Exemplo: um agente de suporte busca por “invoice 1001” e puxa o tenant errado porque a lookup pulou o escopo de tenant. É um bug pequeno com grande impacto.

Um checklist rápido antes de se comprometer

Antes de fechar um modelo de dados multi-tenant, rode alguns testes. O objetivo é pegar vazamentos cedo e confirmar que sua escolha ainda funciona quando as tabelas crescerem.

Checagens rápidas que você faz em um dia

• Prova de isolamento de dados: crie dois tenants (A e B), adicione registros similares e verifique se toda leitura e atualização está com escopo do tenant ativo. Não confie só em filtros da UI.
• Teste de quebra de permissão: faça login como um usuário do Tenant A e tente abrir, editar ou deletar um registro do Tenant B mudando apenas o ID do registro. Se algo der certo, trate como blocker de release.
• Segurança no caminho de escrita: confirme que novos registros sempre recebem o tenant_id correto (ou caem no schema/banco correto), mesmo quando criados por jobs em background, imports ou automações.
• Teste de reporting: confirme que você consegue fazer relatórios apenas por tenant e relatórios “todos os tenants” (para equipe interna), com regras claras sobre quem vê a visão global.
• Checagem de performance: adicione uma estratégia de índices agora (especialmente para (tenant_id, created_at) e outros filtros comuns) e meça ao menos uma query lenta de propósito para saber como é o caso “ruim”.

Para tornar o teste de reporting concreto, escolha duas perguntas que você sabe que vai precisar (uma com escopo de tenant, outra global) e rode-as contra dados de amostra.

-- Tenant-only: últimos 30 dias, um tenant
SELECT count(*)
FROM tickets
WHERE tenant_id = :tenant_id
  AND created_at >= now() - interval '30 days';

-- Global (admin): comparar tenants
SELECT tenant_id, count(*)
FROM tickets
WHERE created_at >= now() - interval '30 days'
GROUP BY tenant_id;

Se você estiver prototipando no AppMaster, construa essas checagens nos seus Business Processes (read, write, delete) e semeie dois tenants no Data Designer. Quando esses testes passarem com volume de dados realista, você pode se comprometer com mais confiança.

Cenário exemplo: dos primeiros clientes ao scale

Uma empresa de 20 pessoas está lançando um portal do cliente: faturas, tickets e um dashboard simples. Esperam 10 tenants no primeiro mês, com plano de chegar a 1.000 no ano seguinte.

No começo, o modelo mais simples geralmente é um banco de dados onde toda tabela que armazena dados do cliente inclui um tenant_id. É rápido de construir, fácil para reporting e evita setups duplicados.

Com 10 tenants, o maior risco não é performance. É permissões. Um filtro esquecido (por exemplo, uma query “listar faturas” que esquece tenant_id) pode vazar dados. A equipe deve aplicar checagens de tenant em um lugar consistente (lógica de negócio compartilhada ou padrões reutilizáveis de API) e tratar o scoping como inegociável.

Ao passar de 10 para 1.000 tenants, as necessidades mudam. Reporting fica mais pesado, suporte pede “exportar tudo para este tenant” e alguns tenants grandes começam a dominar tráfego e deixar tabelas compartilhadas lentas.

Um caminho prático de evolução costuma ser:

1. Mantenha a mesma lógica de app e regras de permissão, mas mova tenants de alto volume para schemas separados.
2. Para os maiores tenants (ou clientes que exigem compliance), mova-os para bancos separados.
3. Mantenha uma camada de reporting compartilhada que leia todos os tenants e agende relatórios pesados fora do pico.

Escolha o modelo mais simples que mantém os dados seguros hoje e planeje uma migração para o problema “alguns tenants gigantes” em vez de otimizar para isso no dia um.

Próximos passos: escolha um modelo e prototipe em um backend sem código

Escolha com base no que você precisa proteger primeiro: isolamento de dados, simplicidade operacional ou escalabilidade por tenant. Confiança vem de construir um pequeno protótipo e tentar quebrá-lo com casos reais de permissão e reporting.

Um guia inicial simples:

• Se a maioria dos tenants é pequena e você precisa de reporting cross-tenant simples, comece com um banco único e tenant_id em cada linha.
• Se você precisa de separação mais forte mas ainda quer gerenciar um banco, considere schemas separados por tenant.
• Se tenants exigem isolamento rígido (compliance, backups dedicados, risco de vizinho barulhento), considere um banco separado por tenant.

Antes de construir, escreva os limites de tenant em linguagem simples. Defina papéis (owner, admin, agent, viewer), o que cada um pode fazer e o que é “global” (planos, templates, logs de auditoria). Decida como o reporting deve funcionar: apenas por tenant ou “todos os tenants” para equipe interna.

Se você está usando AppMaster, pode prototipar esses padrões rapidamente: modele tabelas no Data Designer (incluindo tenant_id, constraints únicas e os índices que suas queries vão precisar) e então aplique regras na Business Process Editor para que toda leitura e escrita fique com escopo de tenant. Se quiser um ponto de referência da plataforma, AppMaster está disponível em appmaster.io.

Um teste final prático: crie dois tenants (A e B), adicione usuários e pedidos similares e rode os mesmos fluxos para ambos. Tente exportar um relatório para o tenant A e, intencionalmente, passe IDs do tenant B nos mesmos endpoints. Seu protótipo só é “suficientemente seguro” quando essas tentativas falham sempre e seus relatórios-chave continuam rápidos com volumes realistas de dados.