Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command cookbook

This cookbook connects redis-tower’s typed command categories to the client or session that should execute them. Command structs remain available from redis_tower::commands::*; the same structs are also grouped into browsable category modules such as commands::strings, commands::streams, and commands::search.

Use the repository examples when you want a complete runnable program. The snippets here focus on the contract that is easy to miss when choosing a command, response type, or connection shape.

The Rust snippets require an external Redis server/topology, so mdBook marks them ignore instead of trying to execute them. Their matching functions live in examples/command_cookbook.rs, which CI compiles with the advertised workspace crates and features.

Pick ownership before commands

WorkRecommended ownerImportant constraint
Concurrent independent requestsMultiplexedClientOne shared auto-pipelined socket; do not run blocking or stateful multi-call sequences on it
One exclusive sequenceRedisConnectionMutable, single-owner socket; required for WATCH/read/build retries
Blocking requests spread across socketsConnectionPoolDispatches each command to an independent member, but exposes no checkout/lease API
Cluster or Sentinel trafficTheir multiplexed clientsRouting/failover is topology-aware; Cluster multi-key atomic work must stay in one slot
Subscription streamPubSubConnection / BinaryPubSubConnectionConsumes a dedicated connection and owns subscription state
MONITOR streamMonitorStreamPermanently changes its dedicated socket until it is dropped

See Production tuning for queueing, deadlines, reconnection, and shutdown. See Cloud and rotating credentials and Client-side caching for those specialized lifecycles.

Typed commands and response shapes

Command types declare their response at compile time. Nil, empty, integer, and server-error replies are not interchangeable:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use bytes::Bytes;
use redis_tower::{
    MultiplexedClient,
    commands::{Get, Incr, Set, SetOutcome, SetPreviousValue},
};

let client = MultiplexedClient::connect("127.0.0.1:6379").await?;

let missing_or_value: Option<Bytes> = client.execute(Get::new("profile:1")).await?;
let next: i64 = client.execute(Incr::new("visits")).await?;

// Finish with `with_outcome()` when conditional code needs to know whether
// Redis applied the write independently from the previous value.
let outcome: SetOutcome = client
    .execute(Set::new("profile:1", "ready").nx().get().with_outcome())
    .await?;
match &outcome.previous {
    SetPreviousValue::NotRequested => unreachable!("GET was requested"),
    SetPreviousValue::Missing => println!("the key did not exist"),
    SetPreviousValue::Value(value) => println!("previous bytes: {value:?}"),
}
let _ = (missing_or_value, next, outcome);
Ok(())
}

Get distinguishes a missing key (None) from an empty value (Some(Bytes::new())). Collection commands similarly preserve their documented ordering and optional entries. Redis command errors remain RedisError::Redis; they are not converted into an empty success value.

Set needs extra care because its options alter the wire reply. The base command keeps its original Option<Bytes> response for compatibility: ordinary OK and a rejected conditional write both become None. Conditional code should call with_outcome() after all other builder methods. Its SetOutcome separates SetStatus::{Applied, NotApplied} from SetPreviousValue::{NotRequested, Missing, Value}; an empty value is Value(Bytes::new()), not Missing.

Builder modestatusprevious
ordinary SETAppliedNotRequested
NX / XX without GETApplied or NotApplied from OK / nullNotRequested
ordinary SET GETalways AppliedMissing or Value
NX GETApplied when missing; otherwise NotAppliedMissing or Value
XX GETNotApplied when missing; otherwise AppliedMissing or Value

The strings, hashes, lists, sets, and sorted-set pages summarize their main result shapes.

Binary keys and values

Redis keys, fields, members, and stored values are byte strings. Typed builders accept byte slices, Vec<u8>, and Bytes through CommandArg; replies that represent Redis byte strings remain Bytes.

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use bytes::Bytes;
use redis_tower::{MultiplexedClient, commands::{Get, HSet, Set}};

let client = MultiplexedClient::connect("127.0.0.1:6379").await?;
let key = b"user:\xff".as_slice();

client.execute(Set::new(key, b"\x00\xfe\xff".as_slice())).await?;
client.execute(HSet::new(key, b"field".as_slice(), b"value\xff".as_slice())).await?;
let value: Option<Bytes> = client.execute(Get::new(key)).await?;
let _ = value;
Ok(())
}

Grammar remains typed or textual: cursors, stream IDs, JSON paths, Search queries, addresses, and SHA-1 digests are not arbitrary payload bytes. See Binary data and typed arguments for ownership and the exact per-family inventory.

Cursor iteration

SCAN is a cursor protocol, not a one-shot snapshot. Process every returned page, including pages with zero results, and stop only at cursor 0. A changing keyspace can produce duplicates.

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::{MultiplexedClient, commands::Scan};

let client = MultiplexedClient::connect("127.0.0.1:6379").await?;
let mut cursor = "0".to_string();
loop {
    let page = client
        .execute(Scan::new().cursor(cursor).match_pattern("user:*").count(100))
        .await?;
    let finished = page.is_finished();
    let next_cursor = page.cursor.clone();
    for key in page.results {
        println!("{key:?}");
    }
    if finished {
        break;
    }
    cursor = next_cursor;
}
Ok(())
}

On Redis Cluster, a keyless SCAN routed normally visits only one node. Use redis_tower_cluster::ScanClusterStream / ClusterScan for a cluster-wide walk and account for resharding semantics documented on that type.

Pipelines, transactions, and Cluster slots

A Pipeline batches network I/O but is not atomic. A Transaction submits a known MULTI/EXEC body atomically. Both keep typed results by index:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use bytes::Bytes;
use redis_tower::{Pipeline, RedisConnection, Transaction, TransactionResult};
use redis_tower::commands::{Get, Incr, Set};

let mut connection = RedisConnection::connect("127.0.0.1:6379").await?;

let pipeline = Pipeline::new()
    .push(Set::new("{account:1}:name", "Ada"))
    .push(Get::new("{account:1}:name"))
    .execute(&mut connection)
    .await?;
let name: &Option<Bytes> = pipeline.get(1)?;

let transaction = Transaction::new()
    .watch(["{account:1}:counter"])
    .push(Incr::new("{account:1}:counter"))
    .execute(&mut connection)
    .await?;
match transaction {
    TransactionResult::Committed(mut replies) => {
        let counter: i64 = replies.take(0)?;
        println!("{counter}");
    }
    TransactionResult::Aborted => { /* rebuild if appropriate */ }
}
let _ = name;
Ok(())
}

A direct Transaction::watch is safe on supported shared clients because the already-built WATCH/MULTI/EXEC exchange is submitted as one operation. A read/compute/write retry loop spans separate calls and must hold a dedicated RedisConnection for the complete WATCH/read/build/EXEC window. A ConnectionPool does not expose a connection lease and cannot provide that ownership.

Cluster atomic transactions and multi-key commands require every key to hash to the same slot. Hash tags such as {account:1} make that relationship explicit. A split helper can distribute independent reads, but splitting is not atomic and is not a substitute for co-located keys.

Run the complete examples with:

cargo run -p redis-tower-examples --example pipeline
cargo run -p redis-tower-examples --example transaction

Streams, consumer groups, and blocking reads

The application owns acknowledgement. Create a group once, read on an isolated connection, finish processing, then acknowledge the exact entry ID:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::RedisConnection;
use redis_tower::commands::{XAck, XGroupCreate, XReadGroup};

let mut connection = RedisConnection::connect("127.0.0.1:6379").await?;
connection
    .execute(XGroupCreate::new("events", "workers", "0").mkstream())
    .await?;

let streams = connection
    .execute(XReadGroup::new("workers", "worker-1", "events").count(10).block(1_000))
    .await?;
for (_stream, entries) in streams {
    for entry in entries {
        // Persist the side effect before acknowledging this ID.
        process(&entry).await?;
        connection.execute(XAck::new("events", "workers", entry.id)).await?;
    }
}
async fn process(_entry: &redis_tower::commands::StreamEntry) -> Result<(), Box<dyn std::error::Error>> { Ok(()) }
Ok(())
}

XREAD/XREADGROUP BLOCK and list blocking commands hold their socket until a reply or Redis timeout. Do not put them on a MultiplexedClient, where they would stop the shared worker. Prefer a finite Redis blocking timeout so the task can observe shutdown; dropping a dedicated connection closes the socket. A caller timeout after bytes reach Redis cannot prove that no entry was delivered, so processing and acknowledgement must be idempotent where a lost reply matters.

See examples/streams.rs for a runnable basic stream flow and Production tuning for shutdown ordering.

Raw, custom, and module replies

RawCommand is the binary-safe escape hatch. It returns Frame by default; .query::<T>() applies a FromFrame decoder without changing the request:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::{MultiplexedClient, commands::RawCommand};

let client = MultiplexedClient::connect("127.0.0.1:6379").await?;
let count: i64 = client
    .execute(RawCommand::new("SCARD").arg("members").query())
    .await?;
let members: Vec<bytes::Bytes> = client
    .execute(RawCommand::new("SMEMBERS").arg("members").query())
    .await?;
let _ = (count, members);
Ok(())
}

Choose the decoder from the documented RESP shape: Option<T> for nil, Vec<T> for ordered arrays, tuples/maps only when the protocol shape warrants them, and raw Frame when a module varies by protocol version or options. Do not normalize nil into empty bytes or unordered results into an invented ordering.

The Cluster router knows the layouts of supported typed commands. An unknown custom command uses the legacy first-argument key convention for ordinary single-command routing; that is safe only when the first argument really is the complete routing key. Keyless node-local administration should use an explicit dedicated node connection. Unknown multi-key atomic layouts should not be guessed.

Feature modules have both Cargo and server prerequisites. Applications using the redis-tower facade need its commands-* feature names; applications depending directly on redis-tower-commands use the shorter names:

redis-tower featureredis-tower-commands featurePublic categoryServer capability
commands-jsonjsoncommands::jsonRedisJSON
commands-searchsearchcommands::searchRedis Search
commands-bloombloomcommands::bloomRedisBloom Bloom/Cuckoo
commands-sketchsketchcommands::sketchRedisBloom CMS/Top-K
commands-tdigesttdigestcommands::tdigestRedisBloom T-Digest
commands-timeseriestimeseriescommands::timeseriesRedisTimeSeries
commands-vector-setsvector-setscommands::vector_setsRedis Vector Sets

The facade’s default commands-stack feature and the command crate’s default stack feature each enable all seven command families. Neither installs those capabilities on the Redis server.

Pub/Sub and MONITOR

Publishing is an ordinary typed command. Receiving messages changes the socket into a stateful session, so construct the session from a fresh connection:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::{BinaryPubSubConnection, RedisConnection};
use tokio_stream::StreamExt;

let connection = RedisConnection::connect("127.0.0.1:6379").await?;
let mut subscriber = BinaryPubSubConnection::from_connection(connection)?;
subscriber.subscribe_bytes(&[b"events\xff".as_slice()]).await?;

if let Some(message) = subscriber.next().await {
    let message = message?;
    println!("{:?}: {:?}", message.channel, message.payload);
}
Ok(())
}

reconnect_with installs a replacement connection and replays subscriptions that were previously confirmed. Messages published while disconnected or before Redis processes the replayed subscription are not recovered. Messages that arrive after server-side subscription processing but before the client reads the confirmation are buffered and delivered. Cluster regular Pub/Sub is tied to an explicitly selected node; sharded Pub/Sub follows slot ownership through its separate API.

MonitorStream::new likewise consumes a fresh connection. There is no resume cursor and no automatic recovery of commands observed during a gap. MONITOR is an expensive debugging facility, not an application event stream.

Run the complete Pub/Sub example with:

cargo run -p redis-tower-examples --example pubsub

Standalone, Cluster, Sentinel, and Universal entry points

Choose the topology at construction; command types stay the same:

async fn example() -> Result<(), Box<dyn std::error::Error>> {
use redis_tower::MultiplexedClient;
use redis_tower_cluster::MultiplexedClusterClient;
use redis_tower_sentinel::MultiplexedSentinelClient;
use redis_tower_client::UniversalClient;

let standalone = MultiplexedClient::connect_url("redis://127.0.0.1:6379").await?;
let cluster = MultiplexedClusterClient::connect("127.0.0.1:7000").await?;
let sentinel = MultiplexedSentinelClient::connect(
    &["127.0.0.1:26379"],
    "mymaster",
).await?;
let universal = UniversalClient::connect_url("redis://127.0.0.1:6379").await?;
let _ = (standalone, cluster, sentinel, universal);
Ok(())
}

Use the explicit builders when Sentinel-hop and data-node credentials differ, when Cluster TLS/address mapping needs customization, or when read routing and reconnect policy matter. UniversalClient is the convenient application-level enum; topology-specific APIs remain necessary for cluster-wide scan, dedicated node sessions, sharded Pub/Sub, and advanced failover controls.

The runnable cluster and sentinel examples document their local fixtures. TLS/authentication and rotating credentials remain canonical in Cloud and rotating credentials.

Administration and diagnostics

commands::server, commands::acl, commands::cluster, and commands::diagnostics contain typed operator commands. Managed services often restrict CONFIG, DEBUG, MODULE, ACL mutation, failover, and persistence commands. Detect permission/server errors rather than assuming local Redis configuration.

Connection-state commands deserve extra caution. Configure authentication, RESP version, selected database, tracking, and decode limits through the connection/factory APIs so every reconnect repeats the same setup. Issuing AUTH, SELECT, HELLO, or tracking commands ad hoc on one shared socket does not update its factory’s future connections.

For continuous operations, prefer the metrics and lifecycle-event APIs over polling expensive diagnostic output. Production tuning is the canonical guide for observability, health probes, reconnect state, and graceful shutdown.

Feature-gated and versioned families

Cargo feature availability, Redis server availability, and command version are three separate checks. Building with commands-stack on the redis-tower facade (or stack on redis-tower-commands) proves that the Rust builders are present; it does not prove a deployment has RedisJSON, Search, Bloom, or TimeSeries. Native Array commands require Redis 8.8+, and Vector Sets require a supporting Redis 8 server.

Treat ERR unknown command or module-specific capability errors as deployment configuration/version failures. Gate startup with an explicit capability probe when a feature is required, and keep fallback behavior visible rather than silently dropping an option or changing a reply shape.