# Banco de dados

> Rode o Nodaro self-hosted com o Supabase incluído ou com um projeto gerenciado no Supabase, aplique as migrações e proteja as chaves e as senhas do banco.

Source: https://nodaro.ai/pt-BR/docs/self-hosting/database

O Nodaro guarda o **banco de dados** no Supabase: o Postgres para os dados, o GoTrue para o login e o PostgREST para a API de dados que o editor lê e grava. A stack do Compose inclui os três e aplica as migrações do banco de dados para você. Em vez disso, você pode apontar o Nodaro para um projeto gerenciado no Supabase e aplicar as migrações você mesmo.

## A stack incluída
| Serviço | Imagem | O que faz |
| --- | --- | --- |
| `db` | Supabase Postgres | O banco de dados, no volume `db-data` |
| `auth` | GoTrue | Cadastro e login com e-mail e senha |
| `rest` | PostgREST | A API de dados |

O navegador e a API acessam o login e a API de dados pela própria origem do app, em `PUBLIC_URL/supabase`. O servidor web do contêiner do Nodaro encaminha `/supabase/auth/v1` para o GoTrue e `/supabase/rest/v1` para o PostgREST, então não é preciso nenhuma porta nem domínio extra.

A stack incluída não envia e-mails: as contas funcionam logo depois do cadastro.

### Migrações na stack incluída
O contêiner do app aplica todos os arquivos de `supabase/migrations/` antes de a API iniciar. Ele precisa de `RUN_MIGRATIONS_ON_BOOT=true` e de `DATABASE_URL`, que o arquivo do Compose define para você.

- **Os arquivos aplicados ficam registrados** e são pulados na inicialização seguinte.
- **Um banco de dados migrado pela metade nunca roda.** Quando uma migração falha, a API se recusa a iniciar, e o log do contêiner indica o arquivo.
- **Corrija e inicie de novo.** Depois de corrigir a causa, rode `docker compose -f docker-compose.community.yml up` de novo. Os arquivos já aplicados são pulados.

### Proteger o banco de dados incluído
As chaves e as senhas padrão são públicas. Antes de expor a stack a uma rede:

1. **Gere novas chaves de autenticação** com `node tools/generate-selfhost-keys.mjs >> .env`. O script imprime `SUPABASE_JWT_SECRET`, `SUPABASE_ANON_KEY` e `SUPABASE_SERVICE_ROLE_KEY`. Os três valores precisam vir da mesma execução: as chaves são assinadas com o segredo.
2. **Defina `POSTGRES_PASSWORD` e uma `DATABASE_URL` correspondente**, como `postgres://postgres:<new-password>@db:5432/postgres`.
3. **Aplique-as** com `docker compose -f docker-compose.community.yml up -d`.

O banco de dados só alinha as senhas das roles internas, como `supabase_auth_admin` e `authenticator`, com `POSTGRES_PASSWORD` na **primeira** inicialização dele. Se o volume `db-data` já existir, apague o volume, o que apaga os seus dados, ou altere as senhas das roles manualmente como `supabase_admin`. Caso contrário, o login falha com `password authentication failed for user "supabase_auth_admin"`.

## Usar um projeto gerenciado no Supabase
Um projeto no supabase.com substitui os serviços `db`, `auth` e `rest` incluídos. O plano gratuito é suficiente. Defina estas variáveis no `.env`:

```bash
SUPABASE_URL=https://YOUR-PROJECT.supabase.co
SUPABASE_ANON_KEY=eyJ...
SUPABASE_SERVICE_ROLE_KEY=eyJ...
FRONTEND_SUPABASE_URL=https://YOUR-PROJECT.supabase.co
RUN_MIGRATIONS_ON_BOOT=false
NODARO_ENCRYPTION_KEY=<64-character hex>
```

- **`FRONTEND_SUPABASE_URL`** é a cópia da URL do projeto que o navegador usa. A imagem publicada é compilada para a stack incluída e só fica sabendo de outra URL por esta variável, na inicialização.
- **`RUN_MIGRATIONS_ON_BOOT=false`** desativa o executor de migrações. Aplique as migrações você mesmo, como descrito abaixo.
- **`NODARO_ENCRYPTION_KEY`** precisa ser definida, por exemplo com `openssl rand -hex 32`. A stack só gera a chave para você enquanto o executor de migrações está ativado. Sem ela, colar chaves de provedor e conectar ao Nodaro Cloud falham com `EncryptionKeyMissingError`.

Se a instalação já rodou na stack incluída, reutilize a chave dela. Ela fica no volume `app-data`, em `/data/nodaro/encryption-key`. Uma chave nova não consegue ler o que a antiga criptografou.

### Aplicar as migrações em um projeto gerenciado
Aplique todos os arquivos de `supabase/migrations/` na **ordem dos nomes dos arquivos**. Os prefixos completados com zeros, como `001_` e `002_`, definem a ordem.

- **Com o SQL editor.** No painel do Supabase, abra o **SQL editor** e execute os arquivos, um de cada vez.
- **Com a CLI do Supabase.** É mais rápido:

```bash
supabase link --project-ref YOUR-REF
supabase db push
```

As migrações podem rodar de novo em um banco de dados já migrado, exceto quando um arquivo diz o contrário, por exemplo no caso de dados iniciais (seed). Rodá-las em um banco de dados novo nunca é um problema.

A cada atualização, aplique os novos arquivos na ordem dos nomes **antes** de reiniciar com a nova imagem. Uma migração que falta normalmente não impede a API de rodar, mas os recursos que dependem dela respondem `500` até as tabelas deles existirem.

## Servir um projeto gerenciado pela sua própria origem
Algumas redes filtram todas as requisições do navegador pelo nome de host e bloqueiam o domínio do Supabase. Para elas, o servidor web do contêiner do Nodaro pode encaminhar um projeto gerenciado pela própria origem do app. Defina as três variáveis juntas:

```bash
SUPABASE_MANAGED_PROXY=true
FRONTEND_SUPABASE_URL=/supabase
SUPABASE_PROXY_UPSTREAM=https://YOUR-PROJECT.supabase.co
```

- `SUPABASE_PROXY_UPSTREAM` é uma origem sem caminho.
- Mantenha `SUPABASE_URL` definida com a URL HTTPS do projeto. A API continua se conectando diretamente a ela.
- O navegador resolve `/supabase` em relação à origem da página. O servidor web encaminha ao projeto as requisições de login, REST, armazenamento e realtime, inclusive os upgrades para WebSocket.
- Os tokens e as chaves de API passam sem alterações. O proxy não acrescenta nenhuma credencial privilegiada.
- Vários domínios podem usar a mesma configuração, sem outro domínio personalizado no Supabase.

O arquivo do Compose não repassa `SUPABASE_MANAGED_PROXY` nem `SUPABASE_PROXY_UPSTREAM` do `.env`: adicione-as em `environment:` do serviço `nodaro`. Sem elas, o proxy fica desativado, e as rotas incluídas se comportam como antes.

## Quando o banco de dados fica indisponível
Se o Postgres cair, para uma migração ou uma recuperação, a API reinicia em loop até o banco de dados voltar a ficar acessível. Isso é esperado. Quando o Postgres voltar, reinicie o contêiner do Nodaro:

```bash
docker compose -f docker-compose.community.yml restart nodaro
```

## O que o banco de dados guarda
Workflows e projetos, perfis de usuário, execuções e o progresso delas, jobs, os registros da mídia gerada, tokens de API e apps OAuth, e as chaves de provedor e os tokens de login das redes sociais, criptografados. Todas as tabelas aplicam segurança em nível de linha (row-level security), então os usuários só veem as próprias linhas. Os arquivos de mídia em si ficam no armazenamento de objetos, e o Redis só guarda o estado de curta duração dos jobs.

Faça backup do banco de dados junto com a chave de criptografia: veja [Backup e restauração](https://nodaro.ai/docs/self-hosting/backups). Para rodar duas instalações em um único banco de dados, veja [Escalonamento](https://nodaro.ai/docs/self-hosting/scaling#two-installs-one-database).

## Frequently asked questions

### Qual banco de dados o Nodaro usa?

O Supabase, que é o Postgres com o serviço de login GoTrue e a API de dados PostgREST. A stack do Compose inclui os três, ou você pode apontar o Nodaro para um projeto gerenciado no supabase.com.

### Preciso aplicar as migrações do banco de dados eu mesmo?

Não na stack incluída, que as aplica a cada inicialização e pula as que já foram aplicadas. Com um projeto gerenciado no Supabase, defina RUN_MIGRATIONS_ON_BOOT=false e aplique supabase/migrations/ na ordem dos nomes dos arquivos, com o SQL editor ou com supabase db push.

### Por que as chaves coladas falham com EncryptionKeyMissingError em um projeto gerenciado no Supabase?

A stack só gera a chave de criptografia da instância enquanto o executor de migrações está ativado. Com RUN_MIGRATIONS_ON_BOOT=false, defina NODARO_ENCRYPTION_KEY você mesmo, ou reutilize a chave que uma instalação anterior com a stack incluída guardou no volume app-data dela.

### Posso mudar a POSTGRES_PASSWORD depois da primeira inicialização?

Só manualmente. O banco de dados só alinha as senhas das roles internas com POSTGRES_PASSWORD na primeira inicialização dele. Apague o volume db-data, o que apaga os seus dados, ou altere as senhas das roles como supabase_admin.

### As migrações podem ser revertidas?

Não. As migrações só avançam. Para voltar a uma versão anterior, restaure o backup que você fez antes da atualização.