reddb-io-client

Official Rust client for RedDB. One connection-string API across embedded, gRPC, HTTP, and RedWire transports. Also hosts the red_client binary and the workspace-internal connector used by red's REPL and reddb-server's rpc_stdio mode.

Quickstart (library)

[dependencies]
reddb-io-client = "1.2"

use reddb_client::{Reddb, JsonValue};

# async fn run() -> reddb_client::Result<()> {
let db = Reddb::connect("memory://").await?;
db.insert("users", &JsonValue::object([("name", JsonValue::string("Alice"))])).await?;
let result = db.query("SELECT * FROM users").await?;
println!("{} rows", result.rows.len());
db.close().await?;
# Ok(())
# }

Rich helpers

The Rust client is the reference implementation of the SDK Helper Spec v1.0. The exact spec version this driver tracks is exported as a constant (spec §14):

assert_eq!(reddb_client::HELPER_SPEC_VERSION, "1.0");

documents.*, kv.*, queues.*, and tx.* are first-class; patch is a top-level merge, an empty patch returns INVALID_ARGUMENT, an empty query returns INVALID_ARGUMENT, and documents.delete / kv.delete of a missing item return { affected: 0, deleted: false } without raising.

Transaction support: imperative only — db.begin(), db.commit(), db.rollback() (spec §7.1). There is no callback tx.run form (§7.2); callers wanting savepoints issue them directly via db.query.

Return envelopes (spec §2.4)

Conformance matrix (spec §12)

Every case ID below is wired in tests/conformance.rs and runs against both transports the helper surface targets — embedded (memory://, always) and a live client (red:// gRPC, gated):

Out-of-scope in v1.0 (reach via raw query / query_with)

• Vectors / Graph / Time-series / Probabilistic — no first-class helpers; the wire SQL surface is stable (spec §§8–11). First-class helpers land in v1.1.
• kv.expire / TTL helper — reach via WITH TTL on the underlying put.
• Queue consumer groups / dead-letter — reach via raw QUEUE READ, QUEUE ACK, and QUEUE NACK statements.
• Callback tx.run, isolation-level begin, cross-shard tx — deferred.

Running the conformance harness

# Embedded transport (memory://) — always runs:
cargo test -p reddb-io-client --test conformance

# Add the live client transport (red:// over gRPC):
RED_SMOKE=1 RED_BIN=/path/to/red \
  cargo test -p reddb-io-client --features grpc --test conformance

# Embedded helper tour (runnable example):
cargo run -p reddb-io-client --example embedded_helpers

use reddb_client::{JsonValue, ListOptions, QueuePushOptions, Reddb};

# async fn run() -> reddb_client::Result<()> {
let db = Reddb::connect("memory://").await?;

let doc = db
    .documents()
    .insert(
        "events",
        &JsonValue::object([
            ("event_type", JsonValue::string("login")),
            ("attempts", JsonValue::number(1.0)),
        ]),
    )
    .await?;
let _same_doc = db.documents().get("events", &doc.rid).await?;
let _recent = db
    .documents()
    .list("events", ListOptions::new().filter("event_type = 'login'").limit(10))
    .await?;

let kv = db.kv_collection("settings");
kv.set("characters:hansel", JsonValue::string("trail")).await?;
let _value = kv.get("characters:hansel").await?;

let queue = db.queue();
queue.create("jobs").await?;
queue
    .push(
        "jobs",
        &JsonValue::object([("kind", JsonValue::string("email"))]),
        QueuePushOptions::new().dedup("outbox:email:42"),
    )
    .await?;
queue
    .push(
        "jobs",
        &JsonValue::object([
            ("kind", JsonValue::string("rebuild_account")),
            ("account_id", JsonValue::string("acct_123")),
        ]),
        QueuePushOptions::new().key("acct_123"),
    )
    .await?;
let _jobs = queue.pop("jobs").await?;
# Ok(())
# }

Parameterized queries

query_with(sql, &[params]) binds positional $N placeholders. SQL literals never carry untrusted values — vector / int / text params travel through the same engine binder the prepared-statement path uses, so injection-by-string is structurally impossible.

use reddb_client::{Reddb, Value};

# async fn run() -> reddb_client::Result<()> {
let db = Reddb::connect("memory://").await?;

// Scalars use IntoValue conversions:
let rows = db
    .query_with(
        "SELECT * FROM users WHERE id = $1 AND name = $2",
        &[1i64.into(), "Alice".into()],
    )
    .await?;

// Vector params route through `Value::Vector` (no string-formatting):
let hits = db
    .query_with(
        "SEARCH SIMILAR $1 COLLECTION embeddings LIMIT $2",
        &[Value::Vector(vec![0.1, 0.2, 0.3]), Value::Int64(5)],
    )
    .await?;
# let _ = (rows, hits);
# Ok(())
# }

The native RedWire client uses the same parameter API when the crate is built with --features redwire:

use reddb_client::redwire::{Auth, ConnectOptions, RedWireClient};
use reddb_client::Value;

# async fn run() -> reddb_client::Result<()> {
let mut client = RedWireClient::connect(
    ConnectOptions::new("127.0.0.1", 5050).with_auth(Auth::Anonymous),
)
.await?;

let rows = client
    .query_with("SELECT $1", &[Value::Int64(42)])
    .await?;
# let _ = rows;
# Ok(())
# }

Native Rust → engine Value mapping:

Today the embedded, http, and Rust grpc transports carry parameters end-to-end. The native Rust RedWire client also carries parameters end-to-end with QueryWithParams and depends on the server advertising FEATURE_PARAMS.

Cargo features

• embedded (default) — pulls the engine in-process for memory:// / file:/// URIs.
• grpc — async tonic client for grpc:// / red://.
• http — REST client over reqwest+rustls for http:// / https://.
• redwire — native RedWire TCP client (no engine).
• redwire-tls — adds TLS / mTLS to the RedWire transport.

Disable defaults to drop the engine: default-features = false.

red_client binary

The crate also hosts the red_client binary (built with cargo build -p reddb-io-client --bin red_client --no-default-features). It is the thin remote-only client used by ops tooling — no engine, no embedded backend, just transports:

red_client is guarded by SIZE_BUDGET (stripped release bytes); CI runs ./scripts/check-red-client-size.sh on every PR to catch accidental engine re-linkage.

Module layout

• crate::Reddb / JsonValue / ClientError — published high-level API.
• crate::connect::{Target, parse} — back-compat shim over reddb-wire's connection-string parser.
• crate::connector::{RedDBClient, repl, http, redwire} — workspace-internal connector consumed by the red REPL, red_client bin, and reddb-server's rpc_stdio mode. The gRPC connector type itself lives in the reddb-client-connector sibling crate to break a path-dependency cycle.

References

• Connection strings
• ADR 0001 — RedWire
• Workspace migration guide

Public-surface support

Generated from docs/conformance/public-surface-contract-matrix.json by scripts/gen-docs-from-matrix.mjs. Do not edit between the markers by hand — run node scripts/gen-docs-from-matrix.mjs --write. The matrix is the source of truth; this block can never claim more than it, and CI (docs-matrix) fails on drift.

Driver-helper (SDK Helper Spec v1.0) support for every public promise. A helper not marked supported here is not promised by this driver.

Status legend: ✅ supported · ⚠️ partial (known gaps) · ❌ unsupported.