Pular para o conteúdo
🏭 GROUPS

Groups — SaaS Factory.

Provisione um banco Postgres isolado por cliente em uma chamada de API. Feito para ISVs B2B que precisam de isolamento real de dados.

O que é um Group

Um Group é um par de (template + conjunto de tenants). Você define uma vez o schema do banco — tabelas, funções, políticas RLS — e o SuperDB replica isso para cada novo tenant que você provisiona via API.

Cada tenant recebe:

  • Um banco Postgres próprio, com o schema do tenant dentro (ex: proj_acme)
  • Um JWT secret próprio — tokens de um tenant não funcionam em outro
  • Um par de API keys (anon + service role) únicas
  • As 5 tabelas de auth clonadas do template
  • Um role Postgres dedicado com GRANTs corretos
💡

Analogia: pense num Group como um molde de bolo. Você cria o molde uma vez (template) e usa para fazer quantos bolos quiser (tenants). Cada bolo é idêntico na estrutura, mas completamente separado na massa.

Quando usar Groups

Use Groups quando você é um ISV (Independent Software Vendor) que vende um SaaS B2B onde:

  • Cada cliente (empresa, escola, clínica, escritório) tem dados que nunca podem se misturar com os de outro cliente
  • Você precisa de conformidade com LGPD em nível de armazenamento — não apenas via RLS
  • Seus clientes exigem poder demonstrar isolamento físico de dados (auditoria, saúde, financeiro, jurídico)
  • Você quer provisionar novos clientes programaticamente, sem intervenção manual

Quando NÃO usar Groups

Groups não são a solução para todos os casos. Use um projeto único com RLS quando:

  • Você tem um app B2C onde todos os usuários compartilham o mesmo produto (rede social, marketplace, e-commerce)
  • A separação de dados por Row Level Security é suficiente para seus requisitos de compliance
  • Você não precisa dar aos clientes a garantia de isolamento físico de banco
  • O trabalho de manter vários projetos não justifica o benefício
⚠️

RLS vs Groups: RLS é uma política de segurança em nível de linha dentro de um mesmo schema. Um bug no RLS pode expor dados de outros usuários. Com Groups, cada cliente fica num banco próprio: um bug de aplicação não atravessa de um banco para outro.

Arquitetura: um banco por tenant

Cada tenant é um projeto com banco Postgres próprio no servidor da plataforma. O tenant nasce com o schema clonado do template e é transferido sozinho para o banco dele logo depois:

estrutura no Postgres
-- Projeto template (você modela aqui)
proj_erp_template
  ├── pacientes
  ├── medicos
  ├── atendimentos
  ├── auth_users
  └── auth_sessions

-- Tenant A (provisionado automaticamente)
proj_clinica_sao_paulo
  ├── pacientes       ← cópia exata do template
  ├── medicos
  ├── atendimentos
  ├── auth_users      ← usuários ISOLADOS do tenant A
  └── auth_sessions

-- Tenant B (provisionado automaticamente)
proj_clinica_campinas
  ├── pacientes       ← dados COMPLETAMENTE separados do tenant A
  ├── medicos
  └── ...

Não há consulta entre tenants: o papel de banco de um tenant só se conecta ao banco dele.

LGPD-friendly por design

Um banco por tenant facilita a conformidade com a LGPD em pontos críticos:

  • Art. 46 (segurança): dados de clientes diferentes ficam em bancos de dados separados
  • Art. 18 (exclusão): apagar o tenant apaga o banco dele inteiro, sem tocar os outros
  • Art. 37 — Registro de operações: logs de acesso por schema são naturalmente segregados
  • Portabilidade: os dados de um cliente saem sozinhos, sem tocar os outros

Ciclo de vida: Group → Tenants → Deploy

fluxo completo
1. Você cria um projeto template no dashboard
   └── Modela as tabelas no SQL Editor
   └── Define as policies RLS
   └── Testa localmente

2. Você cria um Group no painel (Groups)
   └── Seleciona o projeto template
   └── Gera a API Key do Group (guarde! só aparece uma vez)

3. Seu backend chama POST /groups/v1/:id/tenants
   └── quando um novo cliente se cadastra no SEU SaaS

4. SuperDB responde em ~1-2s com:
   └── tenant.id + tenant.slug
   └── anon_key do tenant (vai pro frontend do cliente)
   └── service_role_key do tenant (fica no seu backend)

5. Você guarda as keys no banco do SEU app
   └── e usa elas nas queries desse cliente específico

As três chaves — qual usar em cada lugar

Esta é a parte que mais confunde, porque um Group envolve três credenciais diferentes e só uma delas provisiona tenant.

ChaveOnde ficaPara quê
sdb_gk_…
Group API Key		 No backend do seu app — uma só, para o grupo inteiro Criar, listar e remover tenants do grupo. É a única que provisiona.
sdb_pmk_…
Management Key		 Uma por projeto (e é a que o MCP usa) Rodar SQL e migrations naquele projeto. A group key minta uma para cada tenant novo: é com ela que você aplica no tenant o que o clone não leva. O clone leva as tabelas, os enums, as políticas de RLS e as funções que elas usam; não leva gatilhos, views, funções que só o app chama (RPC) nem dados.
anon e service role Devolvidas na resposta que cria o tenant O dia a dia do app daquele cliente: a anon vai para o frontend, a service role fica no seu servidor.

Não existe uma management key "de grupo": a management key é sempre de um projeto. Quem manda no grupo é a Group API Key.

Limites e controle

Se o seu ERP tem a Group API Key, ele consegue criar tenants sozinho. O que segura isso hoje:

  • Cota pelo plano do template. O group herda o plano do projeto que serve de template, e os tenants inclusos são o mesmo número de projetos daquele plano — Grátis 2, Site 3, Pro 10, Escala 40. No grátis, passar disso para o provisionamento com 402 tenant_quota_exceeded; nos pagos, segue provisionando e cada tenant acima custa R$ 5,00/mês.
  • Teto de 100 tenants por grupo, independente do plano. É limite de infraestrutura: cada tenant tem um banco Postgres próprio. Devolve 402 tenant_limit_reached, e subir de plano não destrava.
  • A chave só enxerga o próprio grupo. Apontar para o id de outro grupo devolve 403, mesmo com uma chave válida.
  • Idempotência por external_id. Reenviar a criação do mesmo cliente devolve 200 com o tenant que já existe, em vez de criar um segundo. É o que protege contra retry de fila e clique duplo.
  • A chave é revogável e o grupo pode ter mais de uma — dá para girar a credencial sem parar o provisionamento.
  • O group é seu. Você cria em /groups no painel, escolhendo um dos seus projetos como template — projeto de outra conta não aparece e é recusado pela API.
  • O template fica protegido. Excluir o projeto que é template (ou fonte) de um group ativo é recusado com 409, com o nome do group na resposta: aponte o group para outro template, ou exclua o group, antes.
  • Template excluído não gera tenant. Se o template de um group já foi excluído, o provisionamento responde 409 template_indisponivel sem criar nada, até você publicar uma versão nova do template ou apontar o group para outro.

O que ainda NÃO existe: não há limite por hora nem por minuto. A cota do plano e o teto de 100 são os freios; entre um provisionamento e outro nada segura o ritmo. Se você vai abrir a Group API Key para um sistema que provisiona sozinho, o controle de quantos clientes entram por dia é do seu lado.

Modelo de billing

O group herda o plano do projeto template, e esse plano já inclui um número de tenants (Grátis 2, Site 3, Pro 10, Escala 40). Cada tenant acima disso custa R$ 5,00/mês, somado à sua fatura — no plano Grátis não há excedente: o provisionamento simplesmente para.

São R$ 5,00 porque o consumo do tenant já é cobrado à parte: banco, arquivos, banda e usuários ativos dele entram nas suas quotas e têm excedente próprio. Esta linha paga o que o tenant é além de consumo — schema isolado, JWT secret próprio, par de chaves e roles.

Groups é auto-atendimento desde 04/08/2026: você cria o group e gera a Group API Key em /groups, no painel, sem falar com ninguém. Antes disso era operação da nossa equipe a cada cliente novo.

Próximos passos

Essa página ajudou?