Supabase

Dados reais no Fayz seguem o modelo BYOS — traga o seu próprio Supabase: você cria o projeto, aponta o app para ele, e o fayz db apply provisiona nele a mesma forma de schema que a plataforma usa (a biblioteca core + os módulos versionados de cada plugin + os seus incubator). Sair do modo mock para dados reais é, no fim, um comando. Esta página é a referência do fluxo; o passo a passo guiado está no tutorial 05.

O caminho tem quatro passos: crie o projeto → preencha o .env → rode fayz db apply → vire o provider. O db apply lê os pacotes instalados, monta a ordem de migração (core → módulos de plugin versionados → incubator) e a aplica no seu projeto via Management API.

Arquitetura em transição. Esta documentação descreve a forma-alvo — a biblioteca core e as tabelas de plugin com prefixo plg_ — que está sendo lançada com a wave de industry pools. A wave de pacotes publicada hoje ainda embarca a nomenclatura anterior (o CLI, por exemplo, rotula o primeiro passo do plano como spine, que vira core). O comando e o fluxo já são estes; só os rótulos internos migram junto com a wave. Onde o texto mostra saída real do CLI, ela aparece com o rótulo atual.

As quatro credenciais

Um projeto Supabase te dá quatro valores, com papéis diferentes:

Project URL e anon key (Project Settings → API) — vão para o navegador, são públicos.
Project ref (Project Settings → General) — o identificador do projeto.
Personal access token / PAT (Account → Access Tokens) — segredo de máquina; nunca vai para o navegador nem para o Git.

No .env.local (git-ignored) eles se separam por prefixo: VITE_ para o que é público, sem prefixo para o que é ferramenta.

# Runtime (vão para o navegador — só valores públicos)
VITE_SUPABASE_URL=https://SEU-REF.supabase.co
VITE_SUPABASE_ANON_KEY=sua-anon-key

# Tooling (usados pelo `fayz db apply` — NÃO vão para o navegador)
SUPABASE_PROJECT_REF=seu-project-ref
SUPABASE_PAT=seu-personal-access-token

O CLI também aceita os aliases SUPABASE_REF e SUPABASE_ACCESS_TOKEN, e lê primeiro do ambiente do processo, depois de <app>/.env.local, depois de <app>/.env (os arquivos nunca sobrescrevem o ambiente).

Planeje antes de aplicar (dry-run)

O --dry-run não faz nenhuma chamada de rede e não lê o seu PAT — é seguro rodar sempre:

npx @fayz-ai/cli db apply --dry-run

O --dry-run pressupõe que você já rodou npm install: ele lê os pacotes @fayz-ai/* do seu node_modules para montar o plano. Sem o @fayz-ai/db instalado, o comando erra em vez de imprimir o plano — instale as dependências antes.

Ele imprime o plano ordenado e para. A ordem é sempre a mesma: o core primeiro, depois as migrations versionadas de cada plugin, e por fim os seus incubator. Na saída atual do CLI isso aparece com os rótulos:

spine → drizzle → seed → plugins → incubator

onde spine/drizzle/seed são os passos do core (o rótulo migra para core na wave de industry pools), plugins são os módulos versionados de cada plugin, e incubator são as suas tabelas. Cada passo só entra se o pacote correspondente trouxer arquivos SQL. Com as versões atuais dos pacotes o plano ainda é enxuto — conforme os plugins passam a trazer migrations, novos passos aparecem aqui. Não estranhe um aviso de "core vazio" no dry-run: o @fayz-ai/db publicado ainda não embarca migrations nessa geração, e o próprio comando avisa qual versão resolve isso.

Aplique de verdade

Quando o plano estiver como você quer, aplique. Este comando roda com as suas credenciais e escreve no banco:

npx @fayz-ai/cli db apply

Ele pede confirmação antes de aplicar; use --yes para pular o prompt em CI. Sem SUPABASE_PROJECT_REF e SUPABASE_PAT definidos, ele para com um erro claro — de propósito, para nunca aplicar contra o projeto errado. Flags úteis para aplicar em pedaços:

Flag	Efeito
`--dry-run`	Só imprime o plano ordenado; nenhuma chamada de rede.
`--yes`, `-y`	Pula a confirmação (obrigatório em shells não interativos).
`--spine-only`	Aplica só o core do `@fayz-ai/db` (a flag mantém o rótulo `spine` na wave atual).
`--plugins-only`	Aplica só as migrations de plugins + incubator.
`--only-plugins a,b`	Restringe o passo de plugins aos ids nomeados.

Vire a chave

Com o esquema no lugar, troque o backend no app.manifest.json de mock para supabase e informe o ref:

{
  "backend": {
    "provider": "supabase",
    "projectRef": "seu-project-ref"
  }
}

E valide:

npx @fayz-ai/cli doctor

O fayz db apply cuida da ordem das camadas por você — core, depois os módulos de plugin, depois os seus incubator — no seu próprio Supabase. Você não escreve o SQL do core à mão. Para entender o que está sendo criado, veja Modelo de dados.

Próximo: como o isolamento entre tenants é garantido em RLS e multi-tenant.