Pular para o conteúdo
⚙️ HOW-TO

Provisionar um tenant no Group

Crie um schema Postgres isolado para um novo cliente em segundos, pelo dashboard ou API.

O que é provisioning

Provisioning cria automaticamente toda a infraestrutura de banco de dados para um novo tenant:

  1. Clona o schema template do Group para um novo schema isolado (clone_schema_to_tenant)
  2. Cria a role Postgres exclusiva do tenant (proj_<group>_<tenant>_service)
  3. Aplica os GRANTs corretos (a role do tenant só acessa seu próprio schema)
  4. Registra o tenant em proj_management.group_tenants

Tempo médio: 1–3 segundos. O processo é idempotente — chamar duas vezes com o mesmo slug não duplica o schema.

Pelo dashboard

  1. Ainda não há tela de Groups no dashboard — o caminho self-serve é a API abaixo.
  2. Clique em + Novo Tenant.
  3. Preencha:
    • Slug: identificador do tenant (ex: empresa-xyz). Usado no nome do schema.
    • Nome: nome legível (ex: "Empresa XYZ Ltda").
    • Email do owner: email do administrador do tenant (opcional).
  4. Clique em Provisionar.
  5. Aguarde o status Ativo. O schema proj_<group>_<tenant> está pronto.

Via API (o caminho da automação)

Autentique com a Group API Key (sdb_gk_…) gerada no group — não com a sua sessão do dashboard. Assim o seu backend provisiona sozinho, no cadastro do cliente.

bash — provisionar tenant
curl -X POST \
  https://auth.superdb.com.br/groups/v1/$GROUP_ID/tenants \
  -H "Authorization: Bearer $SUPERDB_GROUP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "empresa_xyz", "external_id": "cliente-42" }'
json — resposta (201 novo, 200 se já existia)
{
  "tenant": { "id": "...", "slug": "empresa_xyz", "schema_name": "proj_empresa_xyz" },
  "anon_key": "eyJ...",
  "service_role_key": "eyJ...",
  "already_existed": false
}
⚠️

Slug só aceita [a-z][a-z0-9_]{2,30} — letra minúscula no começo, sem hífen (ele vira nome de schema Postgres). Omita o campo e a plataforma gera um. Guarde o external_id para amarrar o tenant ao cliente no seu sistema; repetir a chamada com o mesmo slug devolve 200 + already_existed: true em vez de duplicar (é idempotente).

Erros esperados: 409 slug_taken (o slug está em uso, ou pertenceu a um tenant excluído em definitivo, que não volta a ser usado), 400 invalid_slug, 402 tenant_quota_exceeded (o plano do template não inclui mais tenants), 402 tenant_limit_reached (o teto de 100 tenants por grupo) e 409 template_indisponivel (o projeto template foi excluído, ou o template roda num banco dedicado e precisa ser alinhado pelo suporte antes de gerar tenants; nada é criado, e repetir a chamada não resolve).

Troubleshooting

Timeout durante provisioning

O schema template é clonado com todas as tabelas. Se o template for muito grande (>500 tabelas), o processo pode demorar mais. Se estourar o tempo limite, o provisionamento é revertido e você pode repetir a chamada com o mesmo slug — ela é idempotente. Templates muito grandes: fale com o suporte para ajustar o limite.

Erro: 409 slug_taken

O slug está em uso, inclusive por um tenant só excluído (sem a exclusão definitiva), ou pertenceu a um tenant excluído em definitivo, e esse não volta a ser usado. Escolha outro slug; o external_id do cliente pode continuar o mesmo.

Erro: 409 template_indisponivel com o template excluído

O projeto que servia de template foi excluído, e o group não gera tenant a partir dele. Publique uma versão nova do template a partir da fonte, ou aponte o group para outro template; depois, a mesma chamada funciona. Enquanto for template ou fonte de um group ativo, um projeto não pode ser excluído: a exclusão responde 409 com o nome do group.

O tenant foi criado mas o app não enxerga as tabelas

Confira se está usando as chaves daquele tenant (a resposta do provisionamento traz anon_key e service_role_key próprias) e se o project passado ao SDK é o slug do tenant, não o do projeto template.

Se retornar false, re-execute a migration de GRANTs ou contate o suporte.

Essa página ajudou?