reddb-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-client = "0.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(())
# }

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