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.

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:

   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.

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.