---
name: reddb
description: Use RedDB (the AI-first multi-model database) effectively. Covers the 7 data models on one engine, 6 query languages incl. SQL/Cypher/Gremlin/SPARQL/NL/ASK, HTTP/gRPC/embedded transports, AI providers, migrations, VCS-for-data, eventual consistency, vectors, and geo. Invoke when the user mentions RedDB, `red` CLI, `@reddb-io/*` packages, the `.rdb` file format, or asks "how do I X in RedDB".
---

# RedDB

RedDB is **one engine, 7 data models, 6 query languages**. The mental model that prevents 90% of mistakes:

> A **collection** is the named logical container. **Rows, documents, graph nodes/edges, vectors, KV entries, time-series points, queue messages** are *shapes* you store inside collections. `users` can be a row collection; `events` can be document; `config` can be KV. A collection is not a folder containing tables — it *is* the table (or doc store, or graph, …).

If you forget this, you'll write `CREATE DATABASE` / `USE foo` SQL that doesn't exist here.

<what-to-do>

When the user asks you to do something with RedDB:

1. **Identify the transport** before writing any code:
   - **Embedded** — Rust API `RedDB::open("data.rdb")`, or JS via `@reddb-io/sdk` (spawns a local `red` binary over stdio).
   - **Server** — HTTP on `:8080`, gRPC on `:5055`, RedWire (Postgres-compatible) on `:5050`. Hit via `curl`, `psql`, `@reddb-io/client`, or any Postgres driver.
   - **Agent / MCP** — `red mcp` exposes RedDB as an MCP tool to LLMs.

   Same `.rdb` file format across all three. The user's choice is usually implicit in what they already have running — don't migrate them unprompted.

2. **Pick the query language by user intent**, not by habit:
   - Tabular / aggregation / joins → **SQL**.
   - Path traversal, neighborhood queries → **Cypher** or **Gremlin**.
   - Semantic / "find similar" → `SEARCH SIMILAR TEXT` (vectors).
   - Cross-model entity lookup → `SEARCH CONTEXT` or `FROM ANY`.
   - Natural-language Q&A grounded in data → **`ASK`** (RAG built-in; cites sources).
   - The engine auto-detects the language from the first tokens — don't wrap it.

3. **Before recommending a feature, verify it exists in the user's version.** Run:
   - `red --version` (or `npx @reddb-io/cli@latest version`)
   - `curl -s localhost:8080/stats` to confirm the server is up and which features are compiled in.
   - For SQL grammar specifically, check `docs/reference/sql-1-0-x.md` in the reddb repo if the user has it cloned.

4. **Default to safe parameters**, not string interpolation:
   ```bash
   curl -X POST localhost:8080/query -d '{
     "query": "SELECT * FROM hosts WHERE critical = $1",
     "params": [true]
   }'
   ```
   In JS SDK: `db.query('SELECT * FROM users WHERE id = $1', userId)`. Never concatenate user input into SQL — RedDB supports `$1`-style positional binding everywhere.

5. **For "how do I do X" requests, consult the reference files in this skill:**
   - **`CHEATSHEET.md`** — one-screen reference for every model, every transport, every common operation. Read this first.
   - **`COLLECTIONS.md`** — deep dive on every user-facing model (Tables, Append-Only, Documents, KV, Cache, Graphs, Vectors, Time-Series, Hypertables, Continuous Aggregates, Queues WORK/FANOUT, Events, Metrics) plus indexes and probabilistic structures. Read when the user is choosing or combining models.
   - **`TYPES.md`** — the full type system, standard + native (network, geo, locale, **financial including `Money`/`AssetCode`**, identity, visual, **security: `Secret`/`Password`**, cross-model `*Ref` types). Read when designing a schema or whenever the user has fields like email/IP/money/passwords.
   - **`INFRASTRUCTURE.md`** — embedded, server, server-in-Docker, primary + replica. Includes bind contract, vault, maintenance scheduler, commit policies (`local`/`remote_wal`/`ack_n`/`quorum`), writer lease, replica state machine. Read when the user is deploying or operating RedDB.
   - **`AI.md`** — embeddings (`WITH AUTO EMBED` + `/ai/embeddings` with 3 modes), inferences (`/ai/prompt` with templates), `ASK` and every knob (`STRICT`, `STREAM`, `CACHE TTL`, `LIMIT`, `DEPTH`, fallback chains), credentials/vault (env vars, `/ai/credentials`, `red_config` layout, resolution chain), provider matrix incl. **Anthropic embeddings policy** and the in-progress **`local` provider** (candle, feature-gated by `local-models`). Read whenever AI or embeddings come up.
   - **`RECIPES.md`** — full end-to-end patterns (RAG, audit log, queue worker, vector search with filters, migrations, backups, CDC, …). Read when the cheatsheet line isn't enough.

6. **Never invent SQL.** If a user asks for syntax you're unsure about, say so and either (a) point them to the docs, or (b) try the simplest valid form and verify against `red` output. RedDB extends SQL in specific places (`WITH TTL`, `WITH CONTEXT INDEX`, `WITH EXPAND GRAPH`, `DOCUMENT`, `EDGE`, `APPEND ONLY`, `HYPERTABLE`, `MIGRATION`, `ASK`) — don't paste Postgres-isms that don't apply (`CREATE EXTENSION`, `SCHEMA`, `RETURNING *` may or may not exist on the user's version).

7. **Respect destructive-action rules.** `ROLLBACK MIGRATION`, `DROP COLLECTION`, `red restore`, anything against a `file://` or production server — confirm with the user before running. RedDB's VCS-for-data makes most things reversible, but only if the user knows you ran them.

</what-to-do>

<supporting-info>

## Killer features worth knowing about

- **`ASK 'question'`** — one statement, full RAG. Searches every model, builds context, calls an LLM, returns a cited answer. `USING <provider>` to swap, `STRICT ON` to refuse uncited answers, `CACHE TTL '5m'` to memoize.
- **`SEARCH CONTEXT 'value' FIELD field DEPTH n`** — find every row/doc/node/vector that mentions a value, across models.
- **`FROM ANY`** — SQL pseudo-table that returns the cross-model union ranked by `_score`.
- **VCS-for-data** — every migration is a commit; `ROLLBACK MIGRATION` is a revert. Don't write rollback scripts.
- **`WITH TTL <n> <unit>`** — auto-expire rows (`s`, `m`, `h`, `d`). Works on `INSERT`.
- **`WITH AUTO EMBED (col) USING <provider>`** — auto-vectorize on insert.
- **6 reducers for eventual consistency** — `Sum/Max/Min/Count/Average/Last` with async consolidation. POST to `/ec/<collection>/<field>/add`.
- **Postgres-wire compatible** on `:5050` — you can connect with `psql`, `pgx`, `node-postgres`, etc. Useful when the user already has a Postgres driver.

## When to *not* reach for RedDB features

- The user already has Postgres + a working extension (PostGIS, pgvector). Don't propose a migration unless asked.
- They need ACID-tight multi-statement transactions across replicas — RedDB has transactions but the durability story for distributed setups is younger than Postgres'. Verify guarantees in `docs/operations/rto-rpo.md`.
- High-cardinality OLAP with windowing functions all day — RedDB does it, but ClickHouse is purpose-built.

## File layout when you're poking around a user's install

- `data.rdb` — main store
- `data.rdb-dwb` — double-write buffer (don't delete)
- `data.rdb-hdr` / `data.rdb-meta` — shadow copies for crash recovery
- `wal.log` — write-ahead log
- `~/.config/reddb/` — credentials, default provider, named connections (see `red connect`)

## Reference files in this skill

- `CHEATSHEET.md` — fast lookup of every model & syntax shape.
- `COLLECTIONS.md` — deep dive on every user-facing model + indexes + probabilistic structures.
- `TYPES.md` — full type system, standard + native (incl. `Money`, `Secret`, `Password`, `*Ref`).
- `INFRASTRUCTURE.md` — embedded, server, Docker, primary + replica, commit policies, writer lease.
- `AI.md` — embeddings, inferences, ASK, credentials/vault, provider matrix, local-model status.
- `RECIPES.md` — end-to-end patterns.
- `recipes/` — one file per recipe when they're long enough to deserve it.

When you cite something to the user, link to the file under `plugins/reddb/skills/reddb/` so they can read more.

</supporting-info>