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

# Databases

> Provision and operate Jelou-managed databases (Datum): collections, API keys with granular abilities, and webhook triggers, from the CLI.

`jelou databases` provisions and operates Jelou's managed databases. The
`jelou datum` alias works everywhere `jelou databases` works:
same subcommands, same flags, same exit codes.

<Note>
  There are **two products named "Datum"**. The `jelou datum` alias points to the
  current **Jelou Databases** product (the one this CLI manages). There's
  a separate legacy database product, accessible only from the Studio,
  that this CLI cannot manage.
</Note>

## Databases

| Subcommand                 | Description                                           |
| -------------------------- | ----------------------------------------------------- |
| `list`                     | Lists the organization's databases                    |
| `create --name "<n>"`      | Provisions a new database                             |
| `show <id>`                | Details, URLs, and status (accepts id, slug, or name) |
| `update <id> --name "<n>"` | Renames the database                                  |
| `delete <id> --yes`        | Deletes the database (irreversible)                   |
| `plans`                    | Lists available machine and storage plans             |

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

<Warning>
  `databases delete` is **irreversible**: every collection, record, and file
  disappears, with no trash bin and no rollback. Run `databases show` first and
  confirm the count with the user.
</Warning>

## Collections

| Subcommand                                         | Description                 |
| -------------------------------------------------- | --------------------------- |
| `collections list <db-id>`                         | Lists the collections       |
| `collections show <db-id> <col-id>`                | Shows a collection's schema |
| `collections create <db-id> --name "<n>"`          | Creates a collection        |
| `collections update <db-id> <col-id> --name "<n>"` | Renames                     |
| `collections delete <db-id> <col-id> --yes`        | Deletes (irreversible)      |

`collections create` accepts `--field "<name>:<type>"` (repeatable, defines
columns) and `--type base|view` (collection type; defaults to `base`).

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

<Note>
  `collections create` is *get-or-create*: if a collection with that name and
  the same schema already exists, it's reused and the response reports
  `reused: true` instead of failing. If one exists with that name but a
  **different** schema, the operation is rejected with exit code 2 and a
  field-by-field diff — it never mutates it silently.
</Note>

## API keys

Each key is created with **granular abilities**, combinable with commas:
`records:read`, `records:write`, `records:delete`, `files:read`, `files:write`.
Common presets: `read_only`, `read_write`, `all`.

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

<Note>
  Retrying `api-keys create` with a name that already exists **doesn't mint a
  second key**: it fails with exit code 2 and `ALREADY_EXISTS`, including
  `details.never_used` so you know whether the existing key was ever used —
  that tells you whether rotating it with `api-keys regenerate` is safe.
</Note>

<Warning>
  `files:write` requires `records:write` (files live inside
  records) — the CLI rejects the combination locally. Tokens carry the prefix
  `db_` and are shown **only once** when created: save them right away.
  `api-keys regenerate` rotates the token immediately; any service with the old
  token will get a 401 on its next request. That's why it prompts for
  confirmation before running; in CI or under `--agent` you must pass `--yes`
  explicitly.
</Warning>

## Triggers

Webhooks that fire on a collection's events
(`create`, `update`, `delete`).

| Subcommand                                 | Description                     |
| ------------------------------------------ | ------------------------------- |
| `triggers list <db-id>`                    | Lists the triggers              |
| `triggers create <db-id> …`                | Creates a webhook trigger       |
| `triggers show <db-id> <id>`               | Trigger details                 |
| `triggers update <db-id> <id> --url "<u>"` | Updates the trigger             |
| `triggers delete <db-id> <id> --yes`       | Deletes the trigger             |
| `triggers pause <db-id> <id>`              | Pauses (stops sending webhooks) |
| `triggers resume <db-id> <id>`             | Resumes a paused trigger        |

`triggers create`/`update` also accept `--method "<verb>"` (HTTP verb,
defaults to `POST`) and, for `update` events, `--update-scope fields --columns "<col1,col2>"` to fire only when those columns change (the default
scope is `all`).

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

jelou databases triggers create 01H2XCEJQTG2H5V5NKCYW3J7Z2 \
  --name "plan-changed-webhook" \
  --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` causes **silent data loss**: the destination stops
  receiving events without any error reported upstream. Always mention
  `resume` as the recovery path.
</Warning>