# 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](/pt-BR/docs/dados/modelo) + 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](/pt-BR/docs/tutorial/05-dados-reais-com-supabase).

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.

{% callout type="info" %}
**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.
{% /callout %}

## 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.

```bash
# 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:

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

{% callout type="tip" %}
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.
{% /callout %}

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:

```bash
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:

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

E valide:

```bash
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](/pt-BR/docs/dados/modelo).

---

Próximo: como o isolamento entre tenants é garantido em [RLS e multi-tenant](/pt-BR/docs/dados/rls).