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

# Bases de datos

> Provisiona y opera bases de datos gestionadas por Jelou (Datum): colecciones, API keys con habilidades granulares y triggers webhook, desde el CLI.

`jelou databases` provisiona y opera las bases de datos gestionadas de Jelou. El
alias `jelou datum` funciona en todos lados donde funciona `jelou databases`:
mismos subcomandos, mismos flags, mismos exit codes.

<Note>
  Existen **dos productos con el nombre "Datum"**. El alias `jelou datum` apunta al
  producto actual de **Bases de datos de Jelou** (el que gestiona este CLI). Hay
  un producto de base de datos legacy separado, accesible solo desde el Studio,
  que este CLI no puede administrar.
</Note>

## Bases de datos

| Subcomando                 | Descripción                                              |
| -------------------------- | -------------------------------------------------------- |
| `list`                     | Lista las bases de datos de la organización              |
| `create --name "<n>"`      | Provisiona una base de datos nueva                       |
| `show <id>`                | Detalles, URLs y estado (acepta id, slug o nombre)       |
| `update <id> --name "<n>"` | Renombra la base de datos                                |
| `delete <id> --yes`        | Elimina la base de datos (irreversible)                  |
| `plans`                    | Lista los planes de máquina y almacenamiento disponibles |

```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` es **irreversible**: cada colección, registro y archivo
  desaparece, sin papelera ni rollback. Ejecuta `databases show` primero y
  confirma el conteo con el usuario.
</Warning>

## Colecciones

| Subcomando                                         | Descripción                         |
| -------------------------------------------------- | ----------------------------------- |
| `collections list <db-id>`                         | Lista las colecciones               |
| `collections show <db-id> <col-id>`                | Muestra el esquema de una colección |
| `collections create <db-id> --name "<n>"`          | Crea una colección                  |
| `collections update <db-id> <col-id> --name "<n>"` | Renombra                            |
| `collections delete <db-id> <col-id> --yes`        | Elimina (irreversible)              |

`collections create` acepta `--field "<nombre>:<tipo>"` (repetible, define las
columnas) y `--type base|view` (tipo de colección; por defecto `base`).

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

<Note>
  `collections create` es *get-or-create*: si ya existe una colección con ese
  nombre y el mismo esquema, la reutiliza y responde con `reused: true` en vez
  de fallar. Si existe una con ese nombre pero un esquema **distinto**, rechaza
  la operación con exit code 2 y un diff campo por campo — nunca la modifica en
  silencio.
</Note>

## API keys

Cada key se crea con **habilidades granulares**, combinables por coma:
`records:read`, `records:write`, `records:delete`, `files:read`, `files:write`.
Presets comunes: `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` con un nombre que ya existe **no crea una segunda
  key**: falla con exit code 2 y `ALREADY_EXISTS`, e incluye
  `details.never_used` para saber si la key existente se llegó a usar — así
  sabes si rotarla con `api-keys regenerate` es seguro.
</Note>

<Warning>
  `files:write` requiere `records:write` (los archivos viven dentro de
  registros) — el CLI rechaza la combinación localmente. Los tokens llevan prefijo
  `db_` y se muestran **una sola vez** al crearse: guárdalos enseguida.
  `api-keys regenerate` rota el token de inmediato; cualquier servicio con el token
  viejo recibirá 401 en la siguiente petición. Por eso pide confirmación antes de
  ejecutarse; en CI o con `--agent` hay que pasar `--yes` explícitamente.
</Warning>

## Triggers

Webhooks que se disparan ante eventos de una colección
(`create`, `update`, `delete`).

| Subcomando                                 | Descripción                     |
| ------------------------------------------ | ------------------------------- |
| `triggers list <db-id>`                    | Lista los triggers              |
| `triggers create <db-id> …`                | Crea un trigger webhook         |
| `triggers show <db-id> <id>`               | Detalles del trigger            |
| `triggers update <db-id> <id> --url "<u>"` | Actualiza el trigger            |
| `triggers delete <db-id> <id> --yes`       | Elimina el trigger              |
| `triggers pause <db-id> <id>`              | Pausa (deja de enviar webhooks) |
| `triggers resume <db-id> <id>`             | Reanuda un trigger pausado      |

`triggers create`/`update` también aceptan `--method "<verbo>"` (verbo HTTP,
por defecto `POST`) y, para eventos `update`, `--update-scope fields --columns
"<col1,col2>"` para disparar solo cuando cambian esas columnas (el scope por
defecto es `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-plan-cambiado" \
  --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 **pérdida de datos silenciosa**: el destino deja de
  recibir eventos sin que se reporte error aguas arriba. Menciona siempre
  `resume` como ruta de recuperación.
</Warning>