reddb

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.