> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bancos de dados

> Provisione e opere bancos de dados gerenciados pela Jelou (Datum): coleções, API keys com habilidades granulares e triggers webhook, pela CLI.

`jelou databases` provisiona e opera os bancos de dados gerenciados da Jelou. O
alias `jelou datum` funciona em todos os lugares onde `jelou databases` funciona:
mesmos subcomandos, mesmas flags, mesmos exit codes.

<Note>
  Existem **dois produtos com o nome "Datum"**. O alias `jelou datum` aponta para o
  produto atual de **Bancos de dados da Jelou** (o que esta CLI gerencia). Há
  um produto de banco de dados legado separado, acessível apenas pelo Studio,
  que esta CLI não pode administrar.
</Note>

## Bancos de dados

| Subcomando                 | Descrição                                              |
| -------------------------- | ------------------------------------------------------ |
| `list`                     | Lista os bancos de dados da organização                |
| `create --name "<n>"`      | Provisiona um banco de dados novo                      |
| `show <id>`                | Detalhes, URLs e estado (aceita id, slug ou nome)      |
| `update <id> --name "<n>"` | Renomeia o banco de dados                              |
| `delete <id> --yes`        | Exclui o banco de dados (irreversível)                 |
| `plans`                    | Lista os planos de máquina e armazenamento disponíveis |

```bash theme={null}
jelou databases plans
jelou databases list --json
jelou databases create --name "ordenes"
jelou databases show 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou databases update 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "ordenes-v2"
jelou databases delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 --yes
```

<Warning>
  `databases delete` é **irreversível**: cada coleção, registro e arquivo
  desaparece, sem lixeira nem rollback. Execute `databases show` primeiro e
  confirme a contagem com o usuário.
</Warning>

## Coleções

| Subcomando                                         | Descrição                       |
| -------------------------------------------------- | ------------------------------- |
| `collections list <db-id>`                         | Lista as coleções               |
| `collections show <db-id> <col-id>`                | Mostra o esquema de uma coleção |
| `collections create <db-id> --name "<n>"`          | Cria uma coleção                |
| `collections update <db-id> <col-id> --name "<n>"` | Renomeia                        |
| `collections delete <db-id> <col-id> --yes`        | Exclui (irreversível)           |

`collections create` aceita `--field "<nome>:<tipo>"` (repetível, define as
colunas) e `--type base|view` (tipo de coleção; o padrão é `base`).

```bash theme={null}
jelou databases collections list 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou databases collections create 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "ordenes" \
  --field "total:number" --field "status:select:values=pendente|pago"
```

<Note>
  `collections create` é *get-or-create*: se já existir uma coleção com esse
  nome e o mesmo esquema, ela é reutilizada e a resposta traz `reused: true`
  em vez de falhar. Se existir uma com esse nome mas um esquema **diferente**,
  a operação é rejeitada com exit code 2 e um diff campo a campo — ela nunca é
  modificada silenciosamente.
</Note>

## API keys

Cada key é criada com **habilidades granulares**, combináveis por vírgula:
`records:read`, `records:write`, `records:delete`, `files:read`, `files:write`.
Presets comuns: `read_only`, `read_write`, `all`.

```bash theme={null}
jelou databases api-keys list 01H2XCEJQTG2H5V5NKCYW3J7Z2
jelou databases api-keys create 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "solo-lectura" --abilities "records:read,files:read"
jelou databases api-keys create 01H2XCEJQTG2H5V5NKCYW3J7Z2 --name "completo" --abilities "all"
jelou databases api-keys regenerate 01H2XCEJQTG2H5V5NKCYW3J7Z2 key_01H2XCEJQ --yes
jelou databases api-keys delete 01H2XCEJQTG2H5V5NKCYW3J7Z2 key_01H2XCEJQ --yes
```

<Note>
  Repetir `api-keys create` com um nome que já existe **não cria uma segunda
  key**: falha com exit code 2 e `ALREADY_EXISTS`, incluindo
  `details.never_used` para você saber se a key existente já foi usada — isso
  indica se rotacioná-la com `api-keys regenerate` é seguro.
</Note>

<Warning>
  `files:write` requer `records:write` (os arquivos vivem dentro de
  registros) — a CLI rejeita a combinação localmente. Os tokens levam o prefixo
  `db_` e são exibidos **uma única vez** ao serem criados: guarde-os imediatamente.
  `api-keys regenerate` rotaciona o token imediatamente; qualquer serviço com o token
  antigo receberá 401 na próxima requisição. Por isso ela pede confirmação antes
  de executar; em CI ou com `--agent` é preciso passar `--yes` explicitamente.
</Warning>

## Triggers

Webhooks que disparam diante de eventos de uma coleção
(`create`, `update`, `delete`).

| Subcomando                                 | Descrição                        |
| ------------------------------------------ | -------------------------------- |
| `triggers list <db-id>`                    | Lista os triggers                |
| `triggers create <db-id> …`                | Cria um trigger webhook          |
| `triggers show <db-id> <id>`               | Detalhes do trigger              |
| `triggers update <db-id> <id> --url "<u>"` | Atualiza o trigger               |
| `triggers delete <db-id> <id> --yes`       | Exclui o trigger                 |
| `triggers pause <db-id> <id>`              | Pausa (deixa de enviar webhooks) |
| `triggers resume <db-id> <id>`             | Retoma um trigger pausado        |

`triggers create`/`update` também aceitam `--method "<verbo>"` (verbo HTTP,
padrão `POST`) e, para eventos `update`, `--update-scope fields --columns
"<col1,col2>"` para disparar somente quando essas colunas mudarem (o escopo
padrão é `all`).

```bash theme={null}
jelou databases triggers create 01H2XCEJQTG2H5V5NKCYW3J7Z2 \
  --name "webhook-ordenes" \
  --collection-id col_01H2XCEJQ \
  --url "https://example.com/webhook" \
  --events "create,update,delete"

jelou databases triggers create 01H2XCEJQTG2H5V5NKCYW3J7Z2 \
  --name "webhook-plano-alterado" \
  --collection-id col_01H2XCEJQ \
  --url "https://example.com/webhook" \
  --events "update" \
  --update-scope fields --columns "plan,email"

jelou databases triggers pause 01H2XCEJQTG2H5V5NKCYW3J7Z2 trig_01H2XCEJQ
jelou databases triggers resume 01H2XCEJQTG2H5V5NKCYW3J7Z2 trig_01H2XCEJQ
```

<Warning>
  `triggers pause` causa **perda de dados silenciosa**: o destino deixa de
  receber eventos sem que um erro seja reportado a montante. Sempre mencione
  `resume` como caminho de recuperação.
</Warning>