Redis with the `redis` Crate

17 min read

If you have reached for ioredis or node-redis in Node to cache database results, count rate-limited requests, or store sessions, the Rust redis crate is the direct equivalent. It speaks the same RESP protocol, exposes the same commands (GET, SET, INCR, EXPIRE, HSET, …), and integrates with tokio for async access — but it adds Rust’s signature twist: every value you read back is typed, and the type you ask for is part of the call.

Quick Overview

The redis crate is an async Redis client that maps each Redis command to a Rust method through the AsyncCommands trait. The defining difference from ioredis is that Redis values are untyped bytes on the wire, so you tell Rust what Rust type to decode each reply into — let n: i64 = con.incr("hits", 1).await? — and a mismatch is caught when the value is converted, not silently coerced like JavaScript would. For a TypeScript developer the two surprises are this mandatory return-type annotation and the fact that Redis async connections are multiplexed and cheaply cloneable, so you usually do not need a separate connection pool at all.

Note: This file covers the redis crate itself: connecting asynchronously, running commands, and the everyday patterns (caching, counters, rate limiting, locks). For pooling SQL connections see connection-pooling.md; for the SQL databases you are usually caching in front of see sqlx-intro.md and diesel-intro.md. The async model here builds directly on Section 11: Async.

TypeScript/JavaScript Example

A common Node setup: a shared client, a cache-aside helper, an atomic counter, and a fixed-window rate limiter, all with ioredis.

1
// TypeScript with ioredis (npm i ioredis)
2
import Redis from "ioredis";
3

4
const redis = new Redis(process.env.REDIS_URL ?? "redis://127.0.0.1:6379");
5

6
interface User {
7
  id: number;
8
  name: string;
9
  email: string;
10
}
11

12
// Cache-aside: check Redis, fall back to the database, then populate the cache.
13
async function getUser(id: number): Promise<User> {
14
  const key = `user:${id}`;
15
  const cached = await redis.get(key); // string | null
16
  if (cached !== null) {
17
    console.log(`cache HIT for ${key}`);
18
    return JSON.parse(cached) as User;
19
  }
20

21
  console.log(`cache MISS for ${key}`);
22
  const user = await loadUserFromDb(id); // imagine a SQL query here
23
  await redis.set(key, JSON.stringify(user), "EX", 300); // expire after 5 min
24
  return user;
25
}
26

27
// Atomic counter — INCR is server-side, so it is safe under concurrency.
28
async function recordVisit(): Promise<number> {
29
  return await redis.incr("visits"); // number
30
}
31

32
// Fixed-window rate limit: 3 requests per 60 seconds per user.
33
async function allowRequest(user: string): Promise<boolean> {
34
  const key = `rate:${user}`;
35
  const count = await redis.incr(key);
36
  if (count === 1) await redis.expire(key, 60);
37
  return count <= 3;
38
}
39

40
async function loadUserFromDb(id: number): Promise<User> {
41
  return { id, name: "Ada Lovelace", email: "ada@example.com" };
42
}

Key points:

One shared redis client is reused everywhere; ioredis multiplexes commands over a single socket.
Every reply is loosely typed — redis.get returns string | null, and you cast (as User) after JSON.parse.
INCR returns a number and is atomic on the server, so two concurrent callers never lose an increment.
A typo like redis.incrr("visits") is a runtime error; the type of the returned value is whatever you assert it to be.

Rust Equivalent

The same four operations with the redis crate. Bring the commands into scope with use redis::AsyncCommands, then call methods on a connection. The one new habit is the type annotation on the result: let val: String, let n: i64, let cached: Option<String>.

Add the dependencies in a fresh project (cargo new selects the latest stable edition, 2024):

1
[dependencies]
2
redis = { version = "1.2", features = ["tokio-comp", "connection-manager"] }
3
tokio = { version = "1", features = ["full"] }
4
serde = { version = "1", features = ["derive"] }
5
serde_json = "1"

Tip: Equivalently, cargo add redis --features tokio-comp,connection-manager then cargo add tokio --features full. The tokio-comp feature wires Redis I/O into the Tokio runtime; connection-manager adds the auto-reconnecting ConnectionManager used later.

1
use redis::aio::ConnectionManager;
2
use redis::AsyncCommands;
3
use serde::{Deserialize, Serialize};
4

5
#[derive(Serialize, Deserialize, Debug)]
6
struct User {
7
    id: u64,
8
    name: String,
9
    email: String,
10
}
11

12
// Cache-aside: check Redis, fall back to the "database", then populate the cache.
13
async fn get_user(con: &mut ConnectionManager, id: u64) -> redis::RedisResult<User> {
14
    let key = format!("user:{id}");
15

16
    if let Some(json) = con.get::<_, Option<String>>(&key).await? {
17
        println!("cache HIT for {key}");
18
        return Ok(serde_json::from_str(&json).expect("valid cached JSON"));
19
    }
20

21
    println!("cache MISS for {key}");
22
    let user = User { id, name: "Ada Lovelace".into(), email: "ada@example.com".into() };
23
    let payload = serde_json::to_string(&user).expect("serializable");
24
    let _: () = con.set_ex(&key, payload, 300).await?; // EX 300 seconds
25
    Ok(user)
26
}
27

28
#[tokio::main]
29
async fn main() -> redis::RedisResult<()> {
30
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
31
    let mut con = ConnectionManager::new(client).await?;
32

33
    let _: () = redis::cmd("FLUSHDB").query_async(&mut con).await?; // clean slate for the demo
34

35
    let u1 = get_user(&mut con, 42).await?; // miss
36
    println!("{u1:?}");
37
    let u2 = get_user(&mut con, 42).await?; // hit
38
    println!("{u2:?}");
39

40
    // Pipeline: batch several commands into one round-trip.
41
    let (a, b): (i64, i64) = redis::pipe()
42
        .atomic()
43
        .incr("hits", 1)
44
        .incr("hits", 10)
45
        .query_async(&mut con)
46
        .await?;
47
    println!("pipeline hits => {a}, {b}");
48

49
    Ok(())
50
}

Running this against a local Redis prints the real output:

1
cache MISS for user:42
2
User { id: 42, name: "Ada Lovelace", email: "ada@example.com" }
3
cache HIT for user:42
4
User { id: 42, name: "Ada Lovelace", email: "ada@example.com" }
5
pipeline hits => 1, 11

Detailed Explanation

Going line by line, contrasting with the ioredis version:

redis::Client::open("redis://127.0.0.1:6379/") parses a connection URL and returns a Client. Like new Redis(url), this does not open a socket yet — it is a lazy handle. (The URL form redis://:password@host:port/db carries auth and database index, exactly like ioredis.)
ConnectionManager::new(client).await? establishes the actual async connection. A ConnectionManager multiplexes many concurrent commands over one socket and transparently reconnects if the connection drops — the closest match to how ioredis behaves out of the box. It is Clone, and each clone shares the same underlying connection, so you store one in your application state and .clone() it per task. This is why Rust async Redis rarely needs a pool (contrast with connection-pooling.md, which is essential for synchronous SQL).
use redis::AsyncCommands is the trait that adds .get, .set, .incr, .expire, and dozens more as methods on a connection. Without the use, those methods are invisible — a frequent first stumble (see Common Pitfalls). This is the trait-method pattern from Section 09: Generics & Traits: the methods live on a trait, and the trait must be in scope.
con.get::<_, Option<String>>(&key) asks Redis for the value and decodes the reply into Option<String>. Redis returns bytes; the FromRedisValue trait converts them into the Rust type you name. Decoding into Option<String> means “a missing key is None, not an error” — the type-system equivalent of ioredis returning string | null. The turbofish ::<_, Option<String>> names the return type inline; alternatively, annotate the binding: let cached: Option<String> = con.get(&key).await?.
con.set_ex(&key, payload, 300) is SET key value EX 300 in one call. The let _: () = ... annotation says “this command returns nothing useful; decode the reply as the unit type ().” You must state this — Rust will not guess (see Common Pitfalls for the exact error).
redis::pipe().atomic().incr(...).incr(...).query_async(&mut con) builds a pipeline (multiple commands sent in one network round-trip) and .atomic() wraps it in MULTI/EXEC. The replies come back as a tuple whose type you annotate — here (i64, i64). This mirrors redis.pipeline().incr(...).incr(...).exec() in ioredis, but the tuple is statically typed.
#[tokio::main] and async fn main put you inside the Tokio runtime, just as Node’s event loop is always running. Unlike JavaScript Promises, Rust futures are lazy: nothing happens until .await. Forgetting .await does not “fire and forget” — it produces an unused-Future warning and the command never runs. See Section 11: Promises vs Futures.

Key Differences

Aspect	`ioredis` (TypeScript)	`redis` crate (Rust)
Reply typing	Loosely typed (`string \| null`), cast after parse	You name the Rust type per call; `FromRedisValue` decodes
Missing key	`null`	`Option<T>` decoded as `None`
Errors	Rejected `Promise` (try/catch)	`RedisResult<T>` = `Result<T, RedisError>`, handled with `?`
Connection reuse	One client, multiplexed	`MultiplexedConnection` / `ConnectionManager`, cheaply `Clone`
Pooling	Not needed	Usually not needed for async (unlike sync SQL)
Reconnect	Automatic	`ConnectionManager` reconnects; raw connections do not
Pipelines	`redis.pipeline()`	`redis::pipe()`, replies as a typed tuple
JSON values	`JSON.stringify` / `JSON.parse`	`serde_json::to_string` / `from_str` (see Section 15)
Eagerness	Promises run immediately	Futures are lazy — nothing runs without `.await`

The deepest difference is the typed reply. In ioredis, await redis.get(key) is always string | null and you decide afterward what it “really” is. In Rust, the conversion happens as part of the call, so con.get::<_, i64>(key) will error at decode time if the stored value is not a valid integer, rather than handing you a string you might misuse.

Note: The redis crate (1.x) ships two command traits. AsyncCommands (used above) is generic — you choose the return type. AsyncTypedCommands is the newer, opinionated variant where each method has a fixed, sensible return type, so you often skip the annotation. Pick one per file for consistency; AsyncTypedCommands is shown under Best Practices.

Common Pitfalls

Forgetting the return-type annotation

A TypeScript developer expects con.set("k", "v").await? to “just work” because in ioredis the reply is discarded. In Rust the compiler cannot infer what type to decode the reply into:

1
use redis::AsyncCommands;
2

3
#[tokio::main]
4
async fn main() -> redis::RedisResult<()> {
5
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
6
    let mut con = client.get_multiplexed_async_connection().await?;
7

8
    con.set("k", "v").await?; // does not compile (error[E0277]: the trait bound `!: FromRedisValue` is not satisfied)
9
    Ok(())
10
}

The real cargo check output:

1
error[E0277]: the trait bound `!: FromRedisValue` is not satisfied
2
    --> src/main.rs:8:9
3
     |
4
   8 |     con.set("k", "v").await?;
5
     |         ^^^ the trait `FromRedisValue` is not implemented for `!`
6
     |
7
     = help: the following other types implement trait `FromRedisValue`:
8
               ()
9
               (T,)
10
               (T1, T2)
11
               ...
12
     = help: did you intend to use the type `()` here instead?
13
note: required by a bound in `redis::AsyncCommands::set`

The compiler even suggests the fix: annotate the discarded reply as ().

1
let _: () = con.set("k", "v").await?; // "I do not care about the reply"

Forgetting to import the trait

The command methods live on AsyncCommands. Without the use, con.get(...) does not exist and you get no method named 'get' found. The fix is one line: use redis::AsyncCommands; (or use redis::AsyncTypedCommands;). This is the same “method comes from a trait that must be in scope” rule as the rest of Rust.

Decoding into the wrong Rust type at runtime

Redis is dynamically typed on the server. Calling a string command on a key that holds a list is a server-side WRONGTYPE error, surfaced as a RedisError:

1
use redis::AsyncCommands;
2

3
#[tokio::main]
4
async fn main() -> redis::RedisResult<()> {
5
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
6
    let mut con = client.get_multiplexed_async_connection().await?;
7

8
    let _: () = con.rpush("mylist", "x").await?;
9
    let bad: String = con.get("mylist").await?; // runtime error: key holds a list, not a string
10
    println!("{bad}");
11
    Ok(())
12
}

Real runtime output:

1
Error: "WRONGTYPE": Operation against a key holding the wrong kind of value

This is not a compiler error — the compiler cannot know what a key holds — but unlike JavaScript it surfaces as a typed Err you must handle, not a silently coerced value.

Assuming you need a connection pool

Coming from sync SQL, the instinct is to build a pool. For async Redis, a MultiplexedConnection/ConnectionManager already multiplexes concurrent commands over one socket and is cheap to .clone(). Reach for a pool only when you specifically need blocking commands (e.g. BLPOP) that hold a connection, or features that require a dedicated connection.

Best Practices

Store one ConnectionManager in your app state and clone it. It auto-reconnects and multiplexes; cloning is cheap. This is the idiomatic shared-handle pattern, the same as sharing a sqlx::Pool (see connection-pooling.md).
Prefer AsyncTypedCommands when you want fixed return types. It removes most annotations. The same program with the typed trait — note no turbofish or let _: ():

1
use redis::AsyncTypedCommands;
2

3
#[tokio::main]
4
async fn main() -> redis::RedisResult<()> {
5
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
6
    let mut con = client.get_multiplexed_async_connection().await?;
7

8
    con.set("greeting", "hi").await?;                 // returns ()
9
    let val: Option<String> = con.get("greeting").await?; // GET is naturally nullable
10
    println!("typed get => {val:?}");
11

12
    let n = con.incr("visits", 1).await?; // returns i64 — no annotation needed
13
    println!("typed incr => {n}");
14

15
    let existed = con.exists("greeting").await?; // returns bool
16
    println!("typed exists => {existed}");
17
    Ok(())
18
}

Real output:

1
typed get => Some("hi")
2
typed incr => 1
3
typed exists => true

Always set a TTL on cache and ephemeral keys. Use set_ex (or set_options with SetExpiry) so keys self-expire; an unbounded cache is a memory leak.
Use atomic server-side operations instead of read-modify-write. INCR, INCRBY, EXPIRE, and SET ... NX execute atomically on the server, so concurrent callers never race. Building a counter with GET then SET is a classic concurrency bug.
Decode missing keys as Option<T>. It makes “absent” a value you handle with ?.-style combinators rather than an error — the spiritual cousin of TypeScript’s ?? and ?.. See Section 08: Result & Option.
Keep serialization in one place. Serialize values with serde_json (or a compact format like MessagePack) on the way in and out, so a key always holds the same shape. See Section 15: Serialization.

Real-World Example

A small, production-flavored cache/session service: a Cache struct wrapping a ConnectionManager, with generic put/get helpers that serialize any serde type to JSON with a TTL. This is the shape you would store in your axum application state (see Section 16: Web APIs) and hand to request handlers.

1
use redis::aio::ConnectionManager;
2
use redis::AsyncCommands;
3
use serde::{de::DeserializeOwned, Deserialize, Serialize};
4
use std::time::Duration;
5

6
#[derive(Clone)]
7
struct Cache {
8
    con: ConnectionManager,
9
}
10

11
impl Cache {
12
    async fn connect(url: &str) -> redis::RedisResult<Self> {
13
        let client = redis::Client::open(url)?;
14
        let con = ConnectionManager::new(client).await?;
15
        Ok(Self { con })
16
    }
17

18
    async fn put<T: Serialize>(
19
        &self,
20
        key: &str,
21
        value: &T,
22
        ttl: Duration,
23
    ) -> redis::RedisResult<()> {
24
        let json = serde_json::to_string(value).expect("serializable");
25
        let mut con = self.con.clone();
26
        con.set_ex(key, json, ttl.as_secs()).await
27
    }
28

29
    async fn get<T: DeserializeOwned>(&self, key: &str) -> redis::RedisResult<Option<T>> {
30
        let mut con = self.con.clone();
31
        let raw: Option<String> = con.get(key).await?;
32
        Ok(raw.and_then(|s| serde_json::from_str(&s).ok()))
33
    }
34
}
35

36
#[derive(Serialize, Deserialize, Debug)]
37
struct Session {
38
    user_id: u64,
39
    role: String,
40
}
41

42
#[tokio::main]
43
async fn main() -> redis::RedisResult<()> {
44
    let cache = Cache::connect("redis://127.0.0.1:6379/").await?;
45

46
    let session = Session { user_id: 7, role: "editor".into() };
47
    cache.put("session:abc", &session, Duration::from_secs(900)).await?;
48

49
    let loaded: Option<Session> = cache.get("session:abc").await?;
50
    println!("loaded => {loaded:?}");
51

52
    let missing: Option<Session> = cache.get("session:xyz").await?;
53
    println!("missing => {missing:?}");
54
    Ok(())
55
}

Real output:

1
loaded => Some(Session { user_id: 7, role: "editor" })
2
missing => None

The Cache struct is Clone (because ConnectionManager is), so every handler gets its own cheap handle to the same multiplexed connection. The generic put<T: Serialize> / get<T: DeserializeOwned> pair means any serde-derived type can be cached without bespoke code per type — Rust monomorphizes a specialized version for each T at compile time, whereas the TypeScript equivalent erases the generic and trusts a runtime as cast.

Exercises

Exercise 1: A typed cache-aside helper

Difficulty: Beginner

Objective: Practise the mandatory return-type annotation and the Option<T> “missing key” pattern.

Instructions: Write async fn cached_greeting(con: &mut ConnectionManager, name: &str) -> redis::RedisResult<String> that returns the value of the key greet:{name} if present, and otherwise stores format!("Hello, {name}!") with a 60-second TTL and returns it. Call it twice for the same name and observe the second call reading from the cache.

Solution

1
use redis::aio::ConnectionManager;
2
use redis::AsyncCommands;
3

4
async fn cached_greeting(
5
    con: &mut ConnectionManager,
6
    name: &str,
7
) -> redis::RedisResult<String> {
8
    let key = format!("greet:{name}");
9

10
    if let Some(cached) = con.get::<_, Option<String>>(&key).await? {
11
        return Ok(cached);
12
    }
13

14
    let greeting = format!("Hello, {name}!");
15
    let _: () = con.set_ex(&key, &greeting, 60).await?;
16
    Ok(greeting)
17
}
18

19
#[tokio::main]
20
async fn main() -> redis::RedisResult<()> {
21
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
22
    let mut con = ConnectionManager::new(client).await?;
23
    let _: () = redis::cmd("FLUSHDB").query_async(&mut con).await?;
24

25
    println!("{}", cached_greeting(&mut con, "Ada").await?); // computes + stores
26
    println!("{}", cached_greeting(&mut con, "Ada").await?); // reads from cache
27
    Ok(())
28
}

Both calls print Hello, Ada!; the second served it from Redis. The key detail is con.get::<_, Option<String>>(&key), where the Option turns “absent” into None instead of an error.

Exercise 2: A fixed-window rate limiter

Difficulty: Intermediate

Objective: Use the atomic INCR + EXPIRE pattern that backs most API rate limiters.

Instructions: Write async fn allow_request(con, user: &str, limit: i64, window_secs: i64) -> redis::RedisResult<bool> that increments rate:{user}, sets the TTL to window_secs only on the first hit of a window (when the counter equals 1), and returns whether the count is within limit. Call it five times for one user with limit = 3 and print which requests are allowed.

Solution

1
use redis::aio::MultiplexedConnection;
2
use redis::AsyncCommands;
3

4
async fn allow_request(
5
    con: &mut MultiplexedConnection,
6
    user: &str,
7
    limit: i64,
8
    window_secs: i64,
9
) -> redis::RedisResult<bool> {
10
    let key = format!("rate:{user}");
11
    let count: i64 = con.incr(&key, 1).await?;
12
    if count == 1 {
13
        // Start the window only on the first request that created the key.
14
        let _: () = con.expire(&key, window_secs).await?;
15
    }
16
    Ok(count <= limit)
17
}
18

19
#[tokio::main]
20
async fn main() -> redis::RedisResult<()> {
21
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
22
    let mut con = client.get_multiplexed_async_connection().await?;
23
    let _: () = redis::cmd("FLUSHDB").query_async(&mut con).await?;
24

25
    for i in 1..=5 {
26
        let ok = allow_request(&mut con, "alice", 3, 60).await?;
27
        println!("request {i}: allowed = {ok}");
28
    }
29
    Ok(())
30
}

Real output:

1
request 1: allowed = true
2
request 2: allowed = true
3
request 3: allowed = true
4
request 4: allowed = false
5
request 5: allowed = false

Because INCR runs atomically on the server, this counter is correct even under thousands of concurrent requests — a GET-then-SET version would not be.

Exercise 3: A `SET NX EX` distributed lock

Difficulty: Advanced

Objective: Use set_options to build the canonical “acquire-once” lock and prove the second acquirer is rejected.

Instructions: Using SetOptions with ExistenceCheck::NX and SetExpiry::EX(30), write code that tries to acquire lock:job twice. The first attempt should succeed (true) and the second should fail (false) because the key already exists. The EX(30) ensures the lock auto-releases if the holder crashes.

Solution

1
use redis::{AsyncCommands, ExistenceCheck, SetExpiry, SetOptions};
2

3
#[tokio::main]
4
async fn main() -> redis::RedisResult<()> {
5
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
6
    let mut con = client.get_multiplexed_async_connection().await?;
7
    let _: () = redis::cmd("FLUSHDB").query_async(&mut con).await?;
8

9
    // SET lock:job owner-1 NX EX 30
10
    let opts = SetOptions::default()
11
        .conditional_set(ExistenceCheck::NX)
12
        .with_expiration(SetExpiry::EX(30));
13
    let acquired: bool = con.set_options("lock:job", "owner-1", opts).await?;
14
    println!("first acquire => {acquired}");
15

16
    // A different worker tries while the lock is held.
17
    let opts2 = SetOptions::default()
18
        .conditional_set(ExistenceCheck::NX)
19
        .with_expiration(SetExpiry::EX(30));
20
    let acquired2: bool = con.set_options("lock:job", "owner-2", opts2).await?;
21
    println!("second acquire => {acquired2}");
22

23
    Ok(())
24
}

Real output:

1
first acquire => true
2
second acquire => false

The NX flag means “set only if the key does not exist,” so the second worker is cleanly turned away. Pairing it with EX(30) guarantees the lock cannot be held forever if the first worker dies before releasing it — the foundation of safe distributed locking. (For multi-node correctness, study the Redlock algorithm before relying on this in production.)

Redis with the redis Crate

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Key Differences

Common Pitfalls

Forgetting the return-type annotation

Forgetting to import the trait

Decoding into the wrong Rust type at runtime

Assuming you need a connection pool

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A typed cache-aside helper

Exercise 2: A fixed-window rate limiter

Exercise 3: A SET NX EX distributed lock

Redis with the `redis` Crate

Exercise 3: A `SET NX EX` distributed lock