10. Client Development
Applications never talk to Redis directly. Every command goes through a client library, and many production incidents blamed on "Redis" are really client problems: connection storms, timeouts that are too long or too short, retries that apply a payment twice, or outages that last longer than the failover that caused them. This chapter covers the main client libraries for Python, Node.js, Java and Go, how they manage connections, timeouts, retries, RESP3, clusters and failovers, and how to develop and test Redis code with local servers, test containers, fakes and repeatable fixtures.
All examples in this chapter were run against Redis Open Source 8.10.3 with redis-py 8.1.0, node-redis 6.3.1, ioredis 6.0.0, Jedis 8.0.2, Lettuce 7.9.0 and go-redis 9.23.0. Client defaults (timeouts, pool sizes, protocol version) change between major versions, and several changed in the 2025-2026 releases. The defaults quoted here were read from these versions. Check the changelog whenever you upgrade a client.
<a id="101-client-libraries"></a>
10.1 Client Libraries
This subchapter tours the official clients for the four most common backend languages and the object-mapping libraries built on top of them. It focuses on the design choices that change how you write and operate code: blocking or asynchronous calls, pooled or multiplexed connections, how pipelines work, how replies are typed and how errors surface.
| Language | Library | Package | Connection model | Style |
|---|---|---|---|---|
| Python | redis-py | redis (PyPI) | Pool of connections | Sync and asyncio |
| Node.js | node-redis | redis (npm) | One multiplexed connection per client | Promises |
| Node.js | ioredis | ioredis (npm) | One multiplexed connection per client | Promises |
| Java | Jedis | redis.clients:jedis | Pool of connections | Blocking |
| Java | Lettuce | io.lettuce:lettuce-core | Shared thread-safe connection (Netty) | Sync, async, reactive |
| Go | go-redis | github.com/redis/go-redis/v9 | Pool of connections | Blocking calls with context.Context |
Python (redis-py)
You could talk to Redis with a raw socket and the RESP encoder from chapter 1.3, but every application would then reimplement the same things: parsing replies into native types, keeping connections open and reusing them, reconnecting after a network error, batching commands, routing them in a cluster. A client library packages these once. redis-py is the official Python client. It provides a synchronous API (redis) and an asyncio API (redis.asyncio) in the same package, and it uses the C parser hiredis automatically when it is installed (pip install "redis[hiredis]"), which speeds up parsing of large replies.
The client object is not a connection
The most important mental model: redis.Redis(...) does not open a connection. It creates a facade over a connection pool. Each command borrows a connection from the pool, sends the command, reads the reply and returns the connection. The object is thread-safe, so the right pattern is one client per process, created at startup and shared. Creating a new Redis object per request creates a new pool per request, which throws away the main benefit.
An analogy: the Redis object is a taxi dispatch desk. You ask the desk for a ride (a command), it hands you whichever taxi (connection) is free, and the taxi goes back to the rank when the ride is over. Building a new dispatch desk for every ride is possible, but you pay for a new taxi each time.
Bytes or strings
Redis values are byte strings (chapter 2.2). By default redis-py returns bytes, which is correct for binary data such as images or serialized objects. For text data, decode_responses=True decodes every reply as UTF-8. Choose per client: use one client with decode_responses=True for text and another without it for binary values.
Default settings in redis-py 8.1
| Setting | Default | Meaning |
|---|---|---|
socket_connect_timeout | 5 s | Maximum time to open a TCP connection |
socket_timeout | 5 s | Maximum time to wait for a reply |
max_connections (pool) | 100 | ConnectionPool raises MaxConnectionsError when all are in use |
retry | 10 retries, exponential backoff with jitter (base 10 ms, cap 1 s) | Retries on ConnectionError and TimeoutError |
socket_keepalive | True | TCP keepalive on every connection |
health_check_interval | 0 (off) | When set, idle connections are checked with PING before reuse |
protocol | Not set: RESP3 on the wire, RESP2-style Python replies | See "RESP3 Features" (10.2) |
Older guides describe redis-py as having no timeouts and no retries by default. That is no longer true, and the default retry policy has consequences for non-idempotent commands (see "Timeouts and Retries" in 10.2).
Example: the synchronous API
import redis
# One client per process. It owns a connection pool and is thread-safe.
r = redis.Redis(host="localhost", port=6379, decode_responses=True)
# Equivalent, from a URL (handy for configuration through environment variables):
# r = redis.Redis.from_url("redis://localhost:6379/0", decode_responses=True)
r.set("user:1:name", "Ada") # True
r.get("user:1:name") # 'Ada'
r.get("missing") # None: a missing key is not an error
r.hset("user:1", mapping={"name": "Ada", "visits": 0})
r.hincrby("user:1", "visits", 1) # 1
r.hgetall("user:1") # {'name': 'Ada', 'visits': '1'} numbers come back as strings
try:
r.incr("user:1:name") # a string that is not a number
except redis.ResponseError as e: # server-side errors
print(e) # value is not an integer or out of range
# Pipeline (chapter 4.3): several commands, one round trip
with r.pipeline(transaction=False) as p: # transaction=True (the default) wraps them in MULTI/EXEC
for i in range(3):
p.incr(f"counter:{i}")
print(p.execute()) # [1, 1, 1]
Error hierarchy
| Exception | Raised when | Typical reaction |
|---|---|---|
redis.ResponseError | The server returned an error (WRONGTYPE, syntax, script error) | A bug or a data problem. Do not retry. |
redis.ConnectionError | Connection refused, reset or closed | Retry with backoff if the command is idempotent |
redis.TimeoutError | No reply within socket_timeout | The outcome is unknown. Retry only idempotent commands. |
redis.ReadOnlyError | Write sent to a replica (READONLY) | Rediscover the primary (chapter 7.2) |
redis.exceptions.MaxConnectionsError | The pool is exhausted | Bound concurrency or use a blocking pool |
Example: the asyncio API
With asyncio it is easy to start thousands of commands at once. That exposes a pitfall: the default ConnectionPool refuses to create more than 100 connections and fails immediately. Running asyncio.gather over 1,000 INCR calls with the default client raised MaxConnectionsError: Too many connections. A BlockingConnectionPool makes callers wait for a free connection instead:
import asyncio
import redis.asyncio as aioredis
async def main() -> None:
# Waits up to 2 s for a free connection instead of failing at once
pool = aioredis.BlockingConnectionPool(
host="localhost", port=6379, max_connections=20, timeout=2, decode_responses=True
)
r = aioredis.Redis(connection_pool=pool)
results = await asyncio.gather(*(r.incr("hits") for _ in range(1000)))
print(max(results)) # 1000: 20 connections served 1,000 concurrent calls
async with r.pipeline(transaction=False) as p:
p.incr("a")
p.get("a")
print(await p.execute()) # [1, '1']
await r.aclose() # close the pool's connections
asyncio.run(main())
On the test machine the 1,000 increments over 20 pooled connections took about 0.2 s.
Key Takeaways
redis.Redisis a thread-safe facade over a connection pool. Create one per process and share it.decode_responses=Truereturnsstrinstead ofbytes. Keep a separate client for binary data.- A missing key returns
None. Server errors raiseResponseError, network problems raiseConnectionErrororTimeoutError. - redis-py 8.x has 5 s timeouts, a pool limit of 100 and 10 automatic retries by default. Know these values before you rely on them.
- With
asyncio, use aBlockingConnectionPool(or limit concurrency yourself) so bursts wait instead of failing.
Practice
- (Beginner) Create a client with and without
decode_responses=True, store the string"café"and read it back with both. Explain the two results and when each is the right choice.- (Intermediate) Reproduce the
MaxConnectionsErrorwithasyncio.gatherover 1,000INCRcalls on a default client. Fix it twice: once with aBlockingConnectionPooland once with anasyncio.Semaphorearound the calls. Compare the number of connections the server sees withINFO clients.- (Interview) "A Flask application creates
redis.Redis()inside every request handler. Under load, Redis shows tens of thousands of connections and the application is slow. Why, and what is the fix?" Hint: think about what the constructor creates, what happens to it after the request, and the cost of the TCP handshake andHELLOper connection.
Node.js (node-redis, ioredis)
Node.js runs JavaScript on a single thread with an event loop, so a Node client does not need a pool to serve concurrent requests. Instead, both popular libraries keep one TCP connection per client object and multiplex all concurrent commands over it. Commands are written to the socket in the order they are issued, and because Redis replies on a connection in the same order, the client matches each reply to the oldest waiting promise.
request A ─ GET user:1 ──┐
request B ─ INCR hits ───┼──▶ one socket ──▶ Redis executes in order
request C ─ GET user:2 ──┘ │
▼
promise A ◀─ "Ada" ◀──┐
promise B ◀─ 42 ◀──┼──── replies in the same order (FIFO)
promise C ◀─ "Alan" ◀──┘
A side effect is automatic pipelining: commands issued in the same tick of the event loop leave in one write and their replies arrive together. 1,000 concurrent INCR calls with Promise.all on a single node-redis client completed in about 25 ms.
Two libraries
- node-redis (
redison npm) is the official client maintained by Redis. It supports Redis 8 features such as the Query Engine, JSON, time series and probabilistic structures, and client-side caching. - ioredis is also hosted by the Redis organization. Its README says it is maintained on a best-effort basis and recommends node-redis for new projects. It is still widely used, especially in older code, and has conveniences such as a built-in
keyPrefixand optional automatic pipelining (enableAutoPipelining, off by default).
| node-redis 6.3 | ioredis 6.0 | |
|---|---|---|
| Connecting | Explicit: await client.connect() | Connects on construction (unless lazyConnect: true) |
| Method names | camelCase: hSet, zRangeWithScores | Lowercase command names: hset, zrange |
ZRANGE ... WITHSCORES | [{ value: 'a', score: 1.5 }] | Flat array of strings: ['a', '1.5'] |
| Pipelines | client.multi()...execAsPipeline() | redis.pipeline()...exec(), returns [err, result] pairs |
| Protocol on the wire | RESP3 by default | RESP3 by default, with RESP2-shaped JavaScript replies (replyMapping: "legacy") |
| Connect timeout | 5,000 ms | 10,000 ms |
| Reply timeout | None unless socket.socketTimeout is set | None unless commandTimeout is set |
| Reconnect delay | 50 ms × 2^n, capped at 2,000 ms, plus up to 200 ms jitter | 50 ms × 2^(n-1), capped at 5,000 ms, plus up to 200 ms jitter |
| While disconnected | Commands queued (offline queue) | Commands queued; each fails after 20 reconnect attempts (maxRetriesPerRequest) |
Example: node-redis
import { createClient, createClientPool } from 'redis';
const client = createClient({ url: 'redis://localhost:6379' });
// The client is an EventEmitter: without an 'error' listener, a network error crashes the process
client.on('error', (err) => console.error('Redis client error', err));
await client.connect();
await client.set('user:1:name', 'Ada'); // 'OK'
await client.get('missing'); // null
await client.hSet('user:1', { name: 'Ada', visits: 0 });
await client.hGetAll('user:1'); // { name: 'Ada', visits: '0' }
// Concurrency on one connection: automatically pipelined
const results = await Promise.all(Array.from({ length: 1000 }, () => client.incr('hits')));
// Explicit pipeline (no MULTI/EXEC) and transaction
await client.multi().incr('a').get('a').execAsPipeline(); // [1, '1']
await client.multi().incr('a').get('a').exec(); // [2, '2'] wrapped in MULTI/EXEC
try {
await client.incr('user:1:name');
} catch (e) {
console.log(e.constructor.name, e.message); // SimpleError ERR value is not an integer or out of range
}
// Blocking commands need their own connection: use a pool (or client.duplicate())
const pool = await createClientPool({ url: 'redis://localhost:6379' }, { minimum: 1, maximum: 5 }).connect();
const job = await pool.blPop('jobs', 5); // { key: 'jobs', element: 'j1' } or null
await pool.close();
await client.close(); // waits for pending replies, then closes
Why blocking commands need a separate connection
On a multiplexed connection, a BLPOP that waits for data holds up every command queued behind it. In a test, a PING sent on the same client right after BLPOP jobs-empty 1 waited 1,013 ms. With the BLPOP on a client.duplicate(), the PING took 2 ms. The same applies to Pub/Sub subscriber mode with RESP2 and to WATCH-based transactions, whose state belongs to the connection (chapter 4.2).
Example: ioredis
import Redis from 'ioredis';
const redis = new Redis({ host: 'localhost', port: 6379 }); // starts connecting immediately
await redis.set('user:1:name', 'Ada');
await redis.zadd('z', 1.5, 'a');
await redis.zrange('z', 0, -1, 'WITHSCORES'); // [ 'a', '1.5' ]
// Pipeline results are [error, result] pairs
await redis.pipeline().incr('a').get('a').exec(); // [ [ null, 1 ], [ null, '1' ] ]
// Optional: batch commands from the same tick automatically
const fast = new Redis({ host: 'localhost', port: 6379, enableAutoPipelining: true });
await redis.quit();
await fast.quit();
Key Takeaways
- Node clients multiplex all concurrent commands over one connection. Replies are matched in FIFO order, which gives free pipelining.
- Use node-redis for new projects. ioredis is stable but maintained on a best-effort basis.
- Always attach an
'error'listener, or a network error becomes an unhandled exception. - Blocking commands, RESP2 Pub/Sub and
WATCHneed a dedicated connection (duplicate()or a client pool). - Neither library has a reply timeout by default. Configure one explicitly (10.2).
Practice
- (Beginner) Write the same script with node-redis and ioredis: set a hash, read it back, run a three-command pipeline and print the results. List every difference in the returned values.
- (Intermediate) Measure 10,000
INCRcalls three ways: awaiting each call in a loop,Promise.allon one client, andPromise.allwith ioredisenableAutoPipelining. Explain the difference between the first and the other two with chapter 4.3.- (Interview) "A Node.js service runs a worker loop with
BLPOP queue 0on the same client it uses for HTTP request handling. Latency of every endpoint goes up to seconds. Why?" Hint: draw the command queue of the single connection and where theBLPOPsits in it.
Java (Jedis, Lettuce)
Java has two mature official clients with opposite designs, and choosing between them is mostly choosing a concurrency model.
- Jedis is small and synchronous. A call blocks the calling thread until the reply arrives, and a connection serves one thread at a time. Concurrency comes from a pool (Apache Commons Pool 2).
- Lettuce is built on Netty and is non-blocking. A single
StatefulRedisConnectionis thread-safe and multiplexes commands from all threads, like the Node.js clients. It offers synchronous, asynchronous (CompletionStage) and reactive (Project Reactor) APIs over the same connection. Spring Data Redis uses Lettuce by default.
Jedis 8: RedisClient replaces JedisPooled
Jedis 7.2 introduced builder-based clients next to the older JedisPooled class, and in Jedis 8 JedisPooled no longer exists. The entry points are RedisClient (standalone), RedisClusterClient and RedisSentinelClient. They are thread-safe objects that own a pool. The low-level Jedis class (one connection, not thread-safe) and JedisPool still exist for code that manages connections itself.
Defaults measured in these versions
| Setting | Jedis 8.0.2 | Lettuce 7.9.0 |
|---|---|---|
| Connect timeout | 2,000 ms | 10 s |
| Reply (command) timeout | 2,000 ms socket timeout | 60 s |
| Pool | maxTotal 8, maxIdle 8, minIdle 0 | No pool needed |
| Pool exhausted | Waits forever (blockWhenExhausted=true, maxWait=-1) | Not applicable |
| Protocol | Negotiates RESP3 | RESP3 |
| Reconnect | Broken connections are discarded from the pool | Automatic; commands are buffered in an unbounded queue meanwhile |
Two of these defaults are classic production problems. A Jedis pool of 8 with an infinite wait turns a slow Redis into threads that hang forever. Lettuce's 60-second command timeout means a request thread waiting on a synchronous call can hang for a minute. Set both explicitly.
Example: Jedis
import java.time.Duration;
import java.util.List;
import java.util.Map;
import redis.clients.jedis.*;
import redis.clients.jedis.exceptions.JedisDataException;
ConnectionPoolConfig pool = new ConnectionPoolConfig();
pool.setMaxTotal(32); // size from measured concurrency (see 10.2)
pool.setMaxIdle(32);
pool.setMinIdle(4); // keep some warm connections
pool.setMaxWait(Duration.ofMillis(500)); // fail fast instead of waiting forever
try (RedisClient jedis = RedisClient.builder()
.hostAndPort("localhost", 6379)
.clientConfig(DefaultJedisClientConfig.builder()
.connectionTimeoutMillis(1000)
.socketTimeoutMillis(1000)
.clientName("orders-api") // visible in CLIENT LIST
.build())
.poolConfig(pool)
.build()) {
jedis.set("user:1:name", "Ada"); // "OK"
jedis.get("missing"); // null
jedis.hset("user:1", Map.of("name", "Ada", "visits", "0"));
jedis.hincrBy("user:1", "visits", 1); // 1
try (AbstractPipeline p = jedis.pipelined()) { // one round trip
Response<Long> n = p.incr("counter");
Response<String> v = p.get("counter");
p.sync(); // send and read all replies
System.out.println(n.get() + " " + v.get()); // 1 1
}
try (AbstractTransaction tx = jedis.multi()) { // MULTI/EXEC
tx.incr("counter");
tx.get("counter");
List<Object> replies = tx.exec(); // [2, 2]
}
try {
jedis.incr("user:1:name");
} catch (JedisDataException e) { // server-side error
System.out.println(e.getMessage()); // ERR value is not an integer or out of range
}
}
Example: Lettuce
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import io.lettuce.core.*;
import io.lettuce.core.api.StatefulRedisConnection;
import io.lettuce.core.api.async.RedisAsyncCommands;
import io.lettuce.core.api.sync.RedisCommands;
RedisClient client = RedisClient.create("redis://localhost:6379"); // io.lettuce.core.RedisClient
client.setOptions(ClientOptions.builder()
.timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1))) // instead of 60 s
.build());
// One connection for the whole application: it is thread-safe
StatefulRedisConnection<String, String> conn = client.connect();
RedisCommands<String, String> sync = conn.sync();
sync.set("user:1:name", "Ada");
System.out.println(sync.get("user:1:name")); // Ada
RedisAsyncCommands<String, String> async = conn.async();
List<RedisFuture<Long>> futures = new ArrayList<>();
for (int i = 0; i < 1000; i++) {
futures.add(async.incr("hits")); // not awaited: pipelined on the wire
}
LettuceFutures.awaitAll(Duration.ofSeconds(5), futures.toArray(new RedisFuture[0]));
async.incr("a")
.thenCompose(v -> async.get("a")) // compose non-blocking calls
.thenAccept(v -> System.out.println("a = " + v));
conn.close();
client.shutdown(); // releases Netty threads
Both libraries have a class named RedisClient. If both are on the classpath (common during a migration), the compiler reports an ambiguous reference. Use the fully qualified name for one of them.
Since Lettuce 7.8, conn.reactive() is deprecated in favor of conn.commands(RedisReactiveCommands.factory()). The reactive API itself is unchanged.
Choosing
| Situation | Choice |
|---|---|
| Classic thread-per-request application, simple code | Jedis with a sized pool |
| Spring Boot | Lettuce (the default), unless you have a reason to switch |
| Reactive stack (WebFlux), many concurrent requests, few threads | Lettuce |
Need to use one connection per thread for blocking commands or WATCH | Jedis, or a dedicated Lettuce connection |
Key Takeaways
- Jedis is blocking and pooled. Lettuce is non-blocking with a shared thread-safe connection.
- In Jedis 8, use
RedisClient,RedisClusterClientandRedisSentinelClient.JedisPooledno longer exists. - The Jedis pool default (8 connections, infinite wait) and the Lettuce command timeout default (60 s) are too permissive for most services. Set them.
- Lettuce exposes sync, async and reactive APIs over the same connection.
- Blocking commands and
WATCHneed dedicated connections in Lettuce too.
Practice
- (Beginner) Write the same "set, get, increment, pipeline" program with Jedis and with Lettuce's synchronous API. Then rewrite the Lettuce version with the async API and
CompletionStagechaining.- (Intermediate) Start 50 threads that each run a 500 ms Lua script (or
BLPOPwith a 0.5 s timeout) through a JedisRedisClientwith the default pool. Measure how long the 50th thread waits. Then setmaxWaitto 200 ms and observe the exception. Which behavior do you want in a web service and why?- (Interview) "Why can Lettuce serve a whole application with one connection while Jedis needs a pool?" Hint: think about who waits for the reply (a thread or a future), how replies are matched to requests on one socket, and what the server does with commands from one connection.
Go (go-redis)
go-redis (github.com/redis/go-redis/v9) is the official Go client. Its design follows Go conventions: the client is safe for concurrent use by many goroutines, every command takes a context.Context, and every command returns a typed Cmd object from which you read the value and the error.
Commands return Cmd objects
rdb.Get(ctx, "k") -> *StringCmd
.Result() -> (string, error) both at once
.Val() -> string value only (zero value on error)
.Err() -> error error only
A missing key is reported as the sentinel error redis.Nil, not as an empty string. Code that ignores the error cannot tell "missing" from "empty".
Defaults in go-redis 9.23
| Option | Default | Note |
|---|---|---|
Protocol | 3 | RESP3 |
PoolSize | 10 × GOMAXPROCS | 120 on a 12-CPU machine |
DialTimeout | 5 s | |
ReadTimeout / WriteTimeout | 5 s | |
PoolTimeout | ReadTimeout + 1 s | Wait for a free connection |
MaxRetries | 3 | Backoff between 10 ms and 1 s |
ContextTimeoutEnabled | false | Context deadlines are ignored for network I/O |
The last line surprises most Go developers. With the default options, a BLPOP called with a context that expires after 50 ms waited the full 2 s until data arrived. With ContextTimeoutEnabled: true, the same call failed after 50 ms with an I/O timeout.
Example
package main
import (
"context"
"errors"
"fmt"
"time"
"github.com/redis/go-redis/v9"
)
func main() {
ctx := context.Background()
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
DialTimeout: time.Second,
ReadTimeout: 500 * time.Millisecond,
WriteTimeout: 500 * time.Millisecond,
PoolSize: 20,
ContextTimeoutEnabled: true, // honor context deadlines and cancellation
})
defer rdb.Close()
if err := rdb.Set(ctx, "user:1:name", "Ada", 0).Err(); err != nil { // 0 = no expiration
panic(err)
}
name, err := rdb.Get(ctx, "user:1:name").Result()
fmt.Println(name, err) // Ada <nil>
_, err = rdb.Get(ctx, "missing").Result()
if errors.Is(err, redis.Nil) { // missing key: a sentinel error, not a failure
fmt.Println("not found")
}
rdb.HSet(ctx, "user:1", "name", "Ada", "visits", 0)
fmt.Println(rdb.HGetAll(ctx, "user:1").Val()) // map[name:Ada visits:0]
// Pipeline: commands are queued in the callback and sent in one round trip
cmds, err := rdb.Pipelined(ctx, func(p redis.Pipeliner) error {
p.Incr(ctx, "counter")
p.Get(ctx, "counter")
return nil
})
fmt.Println(cmds[0].(*redis.IntCmd).Val(), err) // 1 <nil>
// Transaction: the same, wrapped in MULTI/EXEC
_, err = rdb.TxPipelined(ctx, func(p redis.Pipeliner) error {
p.Incr(ctx, "counter")
return nil
})
// A per-request deadline, honored because ContextTimeoutEnabled is true
reqCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
defer cancel()
_, err = rdb.BLPop(reqCtx, 0, "jobs").Result()
fmt.Println(err) // i/o timeout after about 50 ms
err = rdb.Incr(ctx, "user:1:name").Err()
fmt.Printf("%T %v\n", err, err) // proto.RedisError ERR value is not an integer or out of range
}
1,000 goroutines calling Incr concurrently on a client with PoolSize: 20 finished in 36 ms and opened exactly 20 connections (rdb.PoolStats().TotalConns).
Key Takeaways
- A go-redis client is a concurrency-safe pool. Create it once and share it.
- Every command returns a
Cmd. Read.Result()or.Err(), and test forredis.Nilwitherrors.Is. - Set
ContextTimeoutEnabled: trueif you want context deadlines to bound Redis calls. Pipelinedsends a batch, andTxPipelinedsends the same batch insideMULTI/EXEC.- The default pool is 10 connections per CPU. Multiply by the number of pods to estimate server connections.
Practice
- (Beginner) Write a function
GetUser(ctx, rdb, id) (User, bool, error)that returnsfalsewith no error for a missing user and an error only for real failures.- (Intermediate) Reproduce the context experiment: call
BLPop(ctx, 0, "empty")with a 50 ms context, once with default options and once withContextTimeoutEnabled: true, while another goroutine pushes an element after 2 s. Measure both durations.- (Interview) "An HTTP handler in Go passes the request context to every Redis call, yet requests still hang for seconds when Redis is slow. What is the likely cause?" Hint: look at how the client decides when a network read gives up, and which option connects that to the context.
Object Mapping Libraries
Much of the Redis code in an application is repetitive: turn an object into a hash or a JSON document, choose a key name, generate an ID, read it back into an object, and maintain secondary indexes to find objects by something other than their ID (chapter 8.4). Object mapping (OM) libraries do this the way an ORM does it for SQL. You declare a model class with typed fields. The library generates keys and primary keys, validates and converts values, declares a Query Engine index (chapter 9.1) from field annotations, and translates a fluent query API into FT.SEARCH.
class Customer: shop:customer:01M72M... (JSON document)
last_name: indexed ──save──▶ { "pk": "01M72M...", "last_name": "Lovelace", "age": 36, ... }
age: indexed, sortable
FT.CREATE shop:customer:index ON JSON PREFIX 1 shop:customer: SCHEMA ...
Customer.find(age >= 30) ──────▶ FT.SEARCH shop:customer:index "@age:[30 +inf]"
Because querying uses the Query Engine, OM libraries need Redis 8 (or Redis Stack on 7.x).
The libraries
| Library | Language | Status in our tests |
|---|---|---|
| redis-om-python 1.2.0 | Python (Pydantic v2), sync and async | Worked against Redis 8.10 |
| Redis OM Spring 2.0.10 | Java / Spring Boot 4, built on Jedis | Annotations @Document, @Indexed, @Searchable, RedisDocumentRepository |
| redis-om-node 0.4.7 | JavaScript / TypeScript | createIndex() failed on a fresh Redis 8 database (see below) |
| Redis OM .NET 1.3.0 | C# | Not tested here |
redis-om-node 0.4.7 depends on node-redis 4. Its createIndex() first drops any old index and ignores only the error text Unknown Index name, which older servers returned. Redis 8.0 to 8.6 reply no such index, and Redis 8.10 replies SEARCH_INDEX_NOT_FOUND Index not found, so the first createIndex() on an empty database throws. This is a good example of a general risk: OM libraries sit on top of both the client and the server, and they often lag behind both.
Example: redis-om-python
import os
from typing import List
os.environ["REDIS_OM_URL"] = "redis://localhost:6379" # read when the models are defined
from redis_om import EmbeddedJsonModel, Field, JsonModel, Migrator
class Address(EmbeddedJsonModel, index=True):
city: str = Field(index=True)
postal_code: str
class Customer(JsonModel, index=True):
first_name: str
last_name: str = Field(index=True) # TAG field: exact match
age: int = Field(index=True, sortable=True) # NUMERIC SORTABLE
tags: List[str] = Field(index=True)
address: Address
class Meta:
global_key_prefix = "shop" # keys become shop:customer:<ULID>
model_key_prefix = "customer"
Migrator().run() # creates the index, or recreates it if the model changed
c = Customer(first_name="Ada", last_name="Lovelace", age=36, tags=["vip"],
address=Address(city="London", postal_code="W1"))
c.save()
print(c.key()) # shop:customer:01M72M5PRQJKBFX6FHBR4P8JKX (ULID primary key)
londoners = Customer.find(
(Customer.address.city == "London") & (Customer.age >= 30)
).sort_by("-age").all() # FT.SEARCH with a numeric range and a tag
vips = Customer.find(Customer.tags << ["vip"]).all() # "<<" means "contains one of"
Customer(first_name="X", last_name="Y", age="not a number",
tags=[], address=Address(city="Rome", postal_code="00100")) # pydantic ValidationError
The index created by Migrator for this model:
$.pk -> pk TAG
$.last_name -> last_name TAG
$.age -> age NUMERIC SORTABLE UNF
$.tags[*] -> tags TAG
$.address.city -> address_city TAG
Without a Meta class, keys are named after the Python module, for example :__main__.Customer:01M72M5DPYPVA2NCWHK6C9Q4F3. Set both prefixes so keys follow your naming convention (chapter 2.1) and survive refactoring.
Migrator stores a hash of each index definition in a key next to the index. When the model changes, it drops and recreates the index, and Redis then reindexes all keys in the background (chapter 9.1). On a large dataset, plan that like a schema migration.
Example: Redis OM Spring (sketch)
@Document("customer") // stored as JSON, prefix "customer:"
public class Customer {
@Id private String id;
@Indexed private String lastName; // TAG
@Indexed(sortable = true) private int age; // NUMERIC
@Searchable private String bio; // TEXT (full-text)
}
public interface CustomerRepository extends RedisDocumentRepository<Customer, String> {
List<Customer> findByLastName(String lastName); // derived query -> FT.SEARCH
}
When to use an OM library
| Good fit | Poor fit |
|---|---|
| CRUD-style entities searched by a few fields | Counters, queues, leaderboards, rate limiters (core data types are clearer) |
| Teams that want validation and typed models | Hot paths where you need exact control over commands and round trips |
| Prototyping with the Query Engine | Code that must run on servers without the Query Engine |
Key Takeaways
- OM libraries map classes to hashes or JSON documents and generate Query Engine indexes from field annotations.
- They need the Query Engine: Redis 8, or Redis Stack on 7.x.
- Set key prefixes explicitly. Defaults may embed module or class names in keys.
- Schema changes drop and rebuild the index, which triggers a background reindex.
- Check compatibility with your server version. redis-om-node 0.4.7 failed to create an index on Redis 8.
Practice
- (Beginner) Define a
ProductHashModelwithname(full-text),category(tag) andprice(numeric, sortable). Save five products and query "category audio, price below 100, sorted by price".- (Intermediate) Run
MONITOR(chapter 12.1) while executingMigrator().run(),save()and afind()query. Write down every Redis command the library sends, and compare them with the commands you would write by hand.- (Interview) "Your team wants to model a shopping cart, a leaderboard and the user profile with an OM library. Which of the three would you model that way, and why not the others?" Hint: think about which operations each feature needs (
HINCRBY,ZINCRBY, search by field) and what the library adds or hides.
<a id="102-connection-management"></a>
10.2 Connection Management
This subchapter looks at what happens between the client object and the server: how connections are reused, how long a client should wait and when it should try again, what RESP3 changes for clients, how clients route commands in a cluster, and how they survive a failover.
Connection Pooling
Opening a connection to Redis is much more expensive than sending a command on an existing one. A new connection needs a TCP handshake (one round trip), a TLS handshake if encryption is on (one or two more), and then the client's setup commands. A trace of a new redis-py 8.1 connection with MONITOR showed HELLO 3, CLIENT SETINFO LIB-NAME redis-py and CLIENT SETINFO LIB-VER 8.1.0 before the first real command, plus AUTH and SELECT when a password or database is configured. A GET on an open connection is one round trip. On a fresh connection it is four or more.
Connections also cost the server. Each idle client used about 17.6 KB of server memory in a test on Redis 8.10 (200 idle connections freed 3.5 MB when closed), and the server accepts at most maxclients connections (10,000 by default). Clients that open and close a connection per request also wear out ephemeral ports on the application host (sockets in TIME_WAIT).
So every client reuses connections. There are two strategies:
Pooling (redis-py, Jedis, go-redis) Multiplexing (node-redis, ioredis, Lettuce)
thread 1 ──borrow──▶ [conn A] ──▶ thread/request 1 ──┐
thread 2 ──borrow──▶ [conn B] ──▶ Redis thread/request 2 ──┼──▶ [one conn] ──▶ Redis
thread 3 ──wait... (pool full) thread/request 3 ──┘ (FIFO reply matching)
◀──return── conn A is free
- Pooling: each in-flight command holds a connection exclusively. Concurrency is limited by the pool size.
- Multiplexing: all callers share one connection and their commands are pipelined. Concurrency is limited by the bandwidth of one connection and by Redis itself. Blocking commands,
WATCHand RESP2 Pub/Sub still need dedicated connections (10.1).
Sizing a pool
A pool that is too small makes callers wait. One that is too large multiplies connections on the server. Little's law gives a starting point:
connections busy on average = commands per second × time each command holds a connection
2,000 commands/s × 1 ms (round trip + server time) = 2 connections busy on average
Size the pool for peaks (several times the average), plus one connection for each blocking command that can be in progress at the same time. A pool of 10 to 50 per process is typical. Then multiply by the number of processes:
60 pods × 4 worker processes × pool of 50 = 12,000 possible connections > maxclients 10,000
That calculation, not the pool size of a single process, is what usually causes ERR max number of clients reached during a deployment or an autoscaling event.
What happens when the pool is empty
| Client | Behavior when all connections are in use (defaults) |
|---|---|
redis-py ConnectionPool | Fails at once: MaxConnectionsError: Too many connections (limit 100) |
redis-py BlockingConnectionPool | Waits up to timeout (default 20 s), then ConnectionError: No connection available. |
Jedis RedisClient | Waits forever (maxWait=-1) for one of 8 connections |
| go-redis | Waits up to PoolTimeout (ReadTimeout + 1 s) for one of 10 × GOMAXPROCS connections |
In a test with a BlockingConnectionPool(max_connections=2, timeout=0.5) and both connections busy in BLPOP, a PING failed with No connection available. after 0.50 s. Failing fast is usually better than waiting: a request that cannot get a connection in a few hundred milliseconds will probably miss its deadline anyway, and waiting threads pile up.
Example: configuring pools explicitly
import redis
pool = redis.BlockingConnectionPool(
host="localhost",
port=6379,
max_connections=50, # peak concurrency of this process, not of the whole fleet
timeout=0.5, # wait at most 0.5 s for a free connection
socket_connect_timeout=1,
socket_timeout=1,
health_check_interval=30, # PING a connection that has been idle for 30 s before reusing it
client_name="checkout-api", # shows up as name=checkout-api in CLIENT LIST
)
r = redis.Redis(connection_pool=pool, decode_responses=True)
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
PoolSize: 50,
MinIdleConns: 5, // keep warm connections for traffic spikes
PoolTimeout: 500 * time.Millisecond,
ConnMaxIdleTime: 5 * time.Minute, // close connections idle for too long
})
Pools and processes
- Forking: a connection must never be shared between a parent and a child process, or both read each other's replies. redis-py pools record the process ID and reset themselves in the child after a
fork()(servers such as Gunicorn fork workers). Other runtimes need care: create clients after the fork, not before. - Serverless: short-lived function instances each open their own connections. Create the client outside the handler so warm instances reuse it, and keep pools small.
Watching connections on the server
redis-cli INFO clients | grep connected_clients # current number of connections
redis-cli CLIENT LIST | grep -o 'name=[^ ]*\|lib-name=[^ ]*\|lib-ver=[^ ]*' | sort | uniq -c
# 50 lib-name=redis-py
# 50 lib-ver=8.1.0
# 50 name=checkout-api
redis-cli INFO stats | grep total_connections_received # grows quickly = connection churn
Modern clients send CLIENT SETINFO with their library name and version, so CLIENT LIST shows which services and which library versions are connected. Setting a client name per service makes this even clearer.
Key Takeaways
- New connections cost several round trips and server memory (about 17.6 KB each when idle). Reuse them.
- Pooled clients hold a connection per in-flight command. Multiplexed clients share one connection.
- Size pools from measured concurrency (Little's law) and check the total across all processes against
maxclients. - Know what your pool does when empty. Prefer a short wait and a clear error to an infinite wait.
- Name clients and watch
connected_clientsandtotal_connections_receivedto spot leaks and churn.
Practice
- (Beginner) Run a script that creates a new client and runs one
GETper iteration, 1,000 times, and another that reuses one client. Compare the run time andtotal_connections_receivedbefore and after each run.- (Intermediate) Your service handles 3,000 requests per second, each request runs 4 Redis commands sequentially, and the average command time is 0.8 ms. Estimate the average number of busy connections per process (8 processes), choose a pool size, and compute the total connections for 40 pods.
- (Interview) "After moving from 10 to 60 pods, Redis starts rejecting connections with
max number of clients reached, although CPU is at 20%. What happened and what are your options?" Hint: multiply pool sizes, think about idle connections, multiplexing clients,maxclients, and proxies.
Timeouts and Retries
A client that waits forever for a dead server hangs the application. A client that gives up too early fails requests that would have succeeded. A client that retries blindly can apply the same write several times. Timeouts and retries are where most client configuration mistakes live, so it is worth being precise about each one.
The timeouts
| Timeout | Bounds | Too short | Too long |
|---|---|---|---|
| Connect timeout | Opening a TCP (and TLS) connection | Fails during brief network hiccups | Requests hang when the server is down |
| Socket / command timeout | Waiting for the reply to a sent command | Fails slow but successful commands; unknown outcome | Threads pile up behind a stuck server |
| Pool wait timeout | Waiting for a free pooled connection | Errors during bursts | Hides pool exhaustion as latency |
| Blocking command timeout | BLPOP key 5, XREAD BLOCK 5000 | n/a (it is the business timeout) | n/a |
| Request deadline | The whole operation in your application |
Two rules connect them:
- The socket timeout must be longer than any blocking command timeout on that connection. Otherwise every
BLPOPthat waits longer than the socket timeout looks like a network failure. - The sum of attempts must fit the request deadline:
attempts × (timeout + backoff)should be shorter than the time the caller is willing to wait.
Rule 1 matters more than it seems. With redis-py 8.1 and socket_timeout=0.5, a BLPOP never 2 raised TimeoutError only after 9.5 seconds. MONITOR showed why: the client sent BLPOP 11 times, because the default retry policy (10 retries) treats a timeout as retryable. With retries disabled, it failed after 0.5 s. With socket_timeout=3, it returned None after 2 s as intended.
A timeout means "unknown", not "failed"
When a reply does not arrive in time, the client cannot know whether the command was executed. The request may have been lost on the way, executed with the reply lost, or still be queued. For reads this does not matter. For writes it does:
client network Redis
│── INCR payments ───────────────────────────────────────▶│ executes: payments = 1
│ reply delayed ◀─────────────────│
│ timeout! (0.5 s) │
│── retry: INCR payments ────────────────────────────────▶│ executes: payments = 2
│ timeout! │
│── retry: INCR payments ────────────────────────────────▶│ executes: payments = 3
│ raise TimeoutError │
This was reproduced with a small TCP proxy that delays integer replies by 1 s. A redis-py client with socket_timeout=0.5 and 2 retries called incr("payments") once and got TimeoutError, while the server held payments = 3. With retries disabled, the client still got TimeoutError but the server held payments = 1: the error did not mean the increment failed.
Retries in each client (defaults)
| Client | What is retried automatically |
|---|---|
| redis-py 8.1 | Every command on ConnectionError or TimeoutError, up to 10 times (backoff 10 ms to 1 s with jitter) |
| go-redis 9.23 | Network errors and read timeouts of non-blocking commands, up to 3 times; context cancellations are not retried |
| Lettuce 7.9 | After a reconnect, commands that were sent but not answered are queued again and re-sent |
| ioredis 6.0 | Commands in flight when the connection drops are re-sent after reconnect (autoResendUnfulfilledCommands: true) |
| node-redis 6.3 | Reconnects with backoff; commands issued while disconnected wait in the offline queue |
| Jedis 8.0 (standalone) | No command retry; cluster clients retry redirections and connection errors (maxAttempts) |
So most clients provide at-least-once execution by default for some failures. That is safe for idempotent commands (GET, SET key value, HSET, SADD, DEL, EXPIRE with an absolute time) and unsafe for non-idempotent ones (INCR, LPUSH, XADD with *, ZINCRBY, APPEND, most Lua scripts).
Backoff with jitter
Retrying immediately after a failure makes things worse: if a server is overloaded, thousands of clients retrying in lock-step keep it overloaded. Exponential backoff spaces attempts out (10 ms, 20 ms, 40 ms, ...) and jitter randomizes each delay so that clients do not retry in synchronized waves:
delay(n) = min(cap, random(0, base × 2^n)) "full jitter", used by redis-py's default backoff
Making writes safe to retry
The general solution is to make the write idempotent with an operation ID (chapter 8.2). This Lua script applies a credit only once per operation ID. It was tested through the same delaying proxy with 3 retries: the client received the final balance, and the server held 100, not 300.
import redis
from redis.backoff import ExponentialWithJitterBackoff
from redis.retry import Retry
r = redis.Redis(
host="localhost", port=6379, decode_responses=True,
socket_connect_timeout=1,
socket_timeout=0.5, # longer than any blocking call on this client
retry=Retry(ExponentialWithJitterBackoff(base=0.05, cap=1.0), retries=3),
)
# SET NX on the operation key decides whether this attempt is the first one
IDEMPOTENT_INCRBY = r.register_script("""
if redis.call('SET', KEYS[1], '1', 'NX', 'EX', ARGV[2]) then
return redis.call('INCRBY', KEYS[2], ARGV[1])
end
return redis.call('GET', KEYS[2])
""")
def credit(account: int, amount: int, op_id: str) -> int:
# op_id comes from the caller (for example the payment ID), so a retry reuses it
return int(IDEMPOTENT_INCRBY(keys=[f"op:{op_id}", f"balance:{account}"], args=[amount, 86400]))
credit(42, 100, "pay-7f3a") # 100, even if the first reply timed out and the call was retried
Both keys must be in the same hash slot in a cluster: use op:{42}:pay-7f3a and balance:{42}.
Configuring timeouts in other clients
// node-redis: no reply timeout by default
const client = createClient({
url: 'redis://localhost:6379',
pingInterval: 10_000, // keep the connection active (see below)
socket: {
connectTimeout: 1_000,
socketTimeout: 30_000, // inactivity timeout, must exceed pingInterval
reconnectStrategy: (retries) => Math.min(2 ** retries * 50, 2_000) + Math.floor(Math.random() * 100),
},
});
node-redis has two behaviors worth knowing, both observed in tests:
socketTimeoutis an inactivity timeout. An idle client withsocketTimeout: 500dropped and reopened its connection 4 times in 2.2 s. WithpingInterval: 200, it never did.- After a socket timeout, the default reconnect strategy gives up and closes the client for good: the next command failed with
ClientClosedError: The client is closed. A customreconnectStrategy, as above, makes it reconnect.
The per-command options withCommandOptions({ timeout }) and withAbortSignal(signal) only remove commands that are still waiting to be written. A BLPOP that had already been sent ran to completion despite a 200 ms timeout option.
// Lettuce: a 1 s timeout for every command instead of 60 s
client.setOptions(ClientOptions.builder()
.timeoutOptions(TimeoutOptions.enabled(Duration.ofSeconds(1)))
.build());
Idle connections and keepalive
Firewalls, NAT gateways and cloud load balancers often drop TCP connections that have been idle for a few minutes, without telling either side. The next command on such a connection waits for a reply that never comes. Defenses:
- TCP keepalive (on by default in redis-py and Lettuce; ioredis sends keepalives after 30 s) keeps the connection visible to middleboxes.
- Application-level health checks: redis-py
health_check_intervalpings a connection before reusing it if it has been idle longer than the interval. node-redispingIntervalsends periodicPINGs. - Server-side idle timeout: the server's
timeoutsetting closes idle clients after N seconds (default 0, meaning never). If you set it, the client's health check interval must be shorter.
Key Takeaways
- Configure connect, reply and pool-wait timeouts explicitly. Library defaults range from 2 s to 60 s, or no timeout at all.
- The reply timeout must exceed every blocking command timeout on that connection.
- A timeout means the outcome is unknown. A retried write may be applied several times.
- Most clients retry or re-send some commands automatically. Make writes idempotent with operation IDs, or disable retries for them.
- Use exponential backoff with jitter, and keep total retry time within the request deadline.
Practice
- (Beginner) With redis-py, call
BLPOP empty 2withsocket_timeout=0.5and the default retry policy, then withsocket_timeout=3. Explain the durations and count theBLPOPcommands withMONITOR.- (Intermediate) Write a TCP proxy (about 30 lines of
asyncio) that delays replies starting with:by one second. Show that a retriedINCRis applied several times, then make it safe with the operation-ID script above.- (Interview) "Our payment service occasionally credits a customer twice, but only during Redis maintenance windows. There is no bug in the business logic. What would you look at first?" Hint: consider what the client does after a timeout or a reconnect, which commands are idempotent, and how an operation ID changes the picture.
RESP3 Features
Chapter 1.3 introduced RESP3 as a protocol version with richer types. For client developers and users, RESP3 changes three practical things: the shape of the data your code receives, the ability to receive push messages on a normal connection, and the connection handshake.
Negotiation with HELLO
A connection starts in RESP2. The client switches it by sending HELLO 3 (optionally with AUTH and SETNAME in the same command). The reply is itself a RESP3 map describing the server:
127.0.0.1:6379> HELLO 3
1# "server" => "redis"
2# "version" => "8.10.3"
3# "proto" => (integer) 3
4# "id" => (integer) 213
5# "mode" => "standalone"
6# "role" => "master"
7# "modules" => (array) search, bf, vectorset, timeseries, ReJSON (with versions)
A server older than Redis 6 replies to HELLO with an unknown-command error, and clients that negotiate automatically stay on RESP2.
The same commands on the wire
Captured on Redis 8.10 with a raw socket:
Command RESP2 reply RESP3 reply
HGETALL h *4 $4 name $3 Ada $6 visits $1 3 %2 $4 name $3 Ada $6 visits $1 3 (array vs map)
ZSCORE z a $3 1.5 ,1.5 (string vs double)
GET nokey $-1 _ (null bulk vs null)
EXISTS h :1 :1 (unchanged)
With RESP2, the client has to know that HGETALL returns pairs and that ZSCORE returns a number encoded as a string. With RESP3, the reply says so itself, which makes generic parsing simpler and module commands (such as FT.SEARCH and FT.INFO) easier to map to native types.
Push messages
The most important RESP3 feature for clients is the push type (>): data the server sends without a request. With RESP2, a connection in subscriber mode can only run subscription commands, so Pub/Sub needs a dedicated connection. With RESP3, pushes are distinguishable from replies, so a connection can receive:
- Pub/Sub messages while running other commands (chapter 4.1).
- Client-side caching invalidations (
CLIENT TRACKING, chapter 8.1), which is why built-in client-side caches in redis-py, node-redis, Jedis and Lettuce require RESP3. - On Redis Cloud and Redis Software, maintenance notifications such as
MOVING,MIGRATINGandFAILING_OVER, which recent official clients use to relax timeouts and reconnect before a planned failover (redis-py enables them in"auto"mode). Redis Open Source 8.10 does not implement them:CLIENT MAINT_NOTIFICATIONS ONreturns an unknown-subcommand error.
What the clients do by default
Every client tested in this chapter negotiated RESP3 by default (resp=3 in CLIENT INFO). Two of them still hand RESP2-shaped values to your code, so that upgrading does not break existing programs:
| Client | Wire protocol | Value shapes your code receives |
|---|---|---|
| redis-py 8.1 | RESP3 | RESP2-style unless protocol=3 or legacy_responses=False |
| node-redis 6.3 | RESP3 | Native (zRangeWithScores gives { value, score }) |
| ioredis 6.0 | RESP3 | RESP2-style (replyMapping: "legacy") |
| Jedis 8.0 | RESP3 (auto-negotiated) | Typed Java API |
| Lettuce 7.9 | RESP3 | Typed Java API |
| go-redis 9.23 | RESP3 | Typed Cmd results |
In redis-py the difference is visible:
r = redis.Redis(decode_responses=True) # RESP3 wire, legacy shapes
r.zrange("z", 0, -1, withscores=True) # [('a', 1.5), ('b', 2.0)] tuples
r3 = redis.Redis(decode_responses=True, protocol=3) # RESP3 wire, RESP3 shapes
r3.zrange("z", 0, -1, withscores=True) # [['a', 1.5], ['b', 2.0]] lists
r2 = redis.Redis(decode_responses=True, protocol=2) # force RESP2 on the wire
r2.client_info()["resp"] # '2'
Code that unpacks tuples or compares results with == can break when you switch to protocol=3. Test your code before changing the setting, and use protocol=2 if you must support a server or proxy that cannot speak RESP3.
Other RESP3 types
Booleans (#t/#f), big numbers ((), verbatim strings (=, used for example by INFO with a format hint), sets (~) and attributes (|, metadata attached to a reply) complete the protocol. Few commands produce attributes in practice. A client should still parse them, or skip them, without breaking.
Key Takeaways
HELLO 3switches a connection to RESP3 and returns a map with server version, mode, role and modules.- RESP3 replies carry their own type: maps, doubles, nulls, booleans, sets.
- Push messages allow Pub/Sub, client-side caching invalidations and maintenance notifications on a normal connection.
- All clients tested here use RESP3 on the wire by default. redis-py and ioredis keep RESP2-shaped values unless told otherwise.
- Changing the protocol setting can change the types your code receives. Test before switching.
Practice
- (Beginner) Run
HGETALL,ZSCORE,GETon a missing key andSMEMBERSwithredis-cli -2andredis-cli -3. Write down the type of each reply.- (Intermediate) Extend the minimal Python client from chapter 1.3 to send
HELLO 3and parse maps (%), doubles (,), nulls (_) and push messages (>). Test it withCLIENT TRACKING ONand a second client that modifies a tracked key.- (Interview) "Why does client-side caching need RESP3, while RESP2 needs a second connection with
REDIRECT?" Hint: think about how a RESP2 client tells an unsolicited message from the reply to its last command.
Cluster-Aware Clients
In Redis Cluster (chapter 7.3), nodes do not forward requests. A node that does not own a key's slot replies with MOVED or ASK, and the client has to go elsewhere. A client that knows nothing about the cluster therefore fails or bounces between nodes. A cluster-aware client does the routing itself, so most commands reach the right node in one round trip.
What a cluster client does
startup seed nodes ──▶ CLUSTER SHARDS / CLUSTER SLOTS ──▶ slot map: 0-5460 → A, 5461-10922 → B, ...
per command slot = CRC16(key) mod 16384 ──▶ node from the slot map ──▶ connection pool of that node
MOVED resend to the node in the reply, refresh the slot map
ASK send ASKING + command to the target node once, keep the map
errors connection refused or timeout ──▶ refresh the map from another node, retry with backoff
multi-key keys in different slots ──▶ split by slot (some clients) or raise CROSSSLOT
fan-out KEYS, DBSIZE, FLUSHALL, SCRIPT LOAD ──▶ send to all primaries, merge the results
Clients learn how to handle keyless and multi-key commands from command tips that the server publishes in COMMAND INFO:
MGET request_policy:multi_shard split by slot, merge replies in order
MSET request_policy:multi_shard response_policy:all_succeeded
DEL request_policy:multi_shard response_policy:agg_sum sum the counts
DBSIZE request_policy:all_shards response_policy:agg_sum
FLUSHALL request_policy:all_shards response_policy:all_succeeded
Multi-key commands differ between clients
The same MGET a b, where a (slot 15495) and b (slot 3300) are on different nodes, behaved differently in each client:
| Client | Cross-slot MGET | Pipeline across nodes | MULTI across slots |
|---|---|---|---|
redis-py 8.1 RedisCluster | Error before sending; mget_nonatomic() splits | Split by node | CrossSlotTransactionError (client-side) |
node-redis 6.3 createCluster | Split by slot automatically | CROSSSLOT from the server | |
ioredis 6.0 Cluster | CROSSSLOT from the server | Rejected: "All keys in the pipeline should belong to the same slots allocation group" | |
Jedis 8.0 RedisClusterClient | Split automatically | ||
Lettuce 7.9 RedisClusterClient | Split automatically | ||
go-redis 9.23 ClusterClient | CROSSSLOT from the server | Split by node | CROSSSLOT from the server |
(Empty cells were not tested.) When a client splits a multi-key command, the result is no longer atomic: another client can change b between the reads of a and b. When atomicity matters, put the keys in the same slot with a hash tag (chapter 7.3), for example {user:1}:profile and {user:1}:cart, and every client will accept them.
Example: redis-py
import redis
from redis.cluster import ClusterNode, RedisCluster
rc = RedisCluster(
startup_nodes=[ClusterNode("10.0.0.1", 7001), ClusterNode("10.0.0.2", 7002)], # any reachable nodes
decode_responses=True,
socket_timeout=1,
)
rc.keyslot("user:1") # 10778
rc.get_node_from_key("user:1").name # '10.0.0.2:7002'
rc.mget_nonatomic("user:1", "user:2") # split by slot, results in the original order
rc.mget("{user}:1", "{user}:2") # same slot thanks to the hash tag: one MGET
with rc.pipeline() as p: # non-transactional pipeline: grouped per node
for i in range(6):
p.set(f"k{i}", i)
p.execute() # [True, True, True, True, True, True]
with rc.pipeline(transaction=True) as p: # transactions only within one slot
p.incr("{cart:1}:items")
p.expire("{cart:1}:items", 60)
p.execute() # [1, True]
Example: node-redis, Lettuce and go-redis
import { createCluster } from 'redis';
const cluster = createCluster({
rootNodes: [{ url: 'redis://10.0.0.1:7001' }, { url: 'redis://10.0.0.2:7002' }],
useReplicas: true, // route read-only commands to replicas
});
cluster.on('error', (err) => console.error('cluster error', err));
await cluster.connect();
await cluster.mGet(['a', 'b']); // [ '1', '2' ] split across nodes
RedisClusterClient client = RedisClusterClient.create(RedisURI.create("redis://10.0.0.1:7001"));
client.setOptions(ClusterClientOptions.builder()
.topologyRefreshOptions(ClusterTopologyRefreshOptions.builder()
.enablePeriodicRefresh(Duration.ofSeconds(30)) // off by default
.build()) // adaptive triggers (MOVED, ASK, reconnects) are on by default since 7.0
.build());
StatefulRedisClusterConnection<String, String> conn = client.connect();
conn.setReadFrom(ReadFrom.REPLICA_PREFERRED); // reads go to replicas when available
rdb := redis.NewClusterClient(&redis.ClusterOptions{
Addrs: []string{"10.0.0.1:7001", "10.0.0.2:7002"},
ReadOnly: true, // allow read-only commands on replicas
})
Keeping the slot map fresh
The slot map changes after failovers, resharding and scaling. Clients refresh it in two ways:
- Reactively: on
MOVED, on connection errors, or when a node disappears. Every client does this. - Periodically: a background refresh, so that new replicas or changed addresses are picked up even when nothing fails. In Lettuce it is disabled by default (60 s period when enabled), and the adaptive triggers are enabled by default since 7.0.
A client that sees many MOVED replies in steady state is not caching the slot map, or is refreshing it from a node with an outdated view.
Addresses that clients cannot reach
Cluster nodes announce their own IP addresses in CLUSTER SHARDS. When the cluster runs in Docker, Kubernetes or behind NAT, those can be internal addresses that the client cannot reach: the client connects to the seed node and then fails on every redirect. Fixes, on either side:
- Server:
cluster-announce-ip,cluster-announce-portandcluster-announce-hostname(chapter 12.3 for Kubernetes). - Client: address remapping, such as ioredis
natMap, JedishostAndPortMapperor LettuceMappingSocketAddressResolver.
The cluster used for the tests in this chapter ran six nodes in one container with --cluster-announce-ip set to the Docker host's address. Without it, clients outside the container could not have followed the redirects.
Proxies and managed endpoints
Some managed services and proxies (chapter 7.4) expose a cluster behind a single endpoint that routes commands itself. Use a standalone client for those, since the endpoint will not send MOVED. Using a cluster client against a non-cluster endpoint fails at startup (redis-py: Cluster mode is not enabled on this node).
Key Takeaways
- Cluster clients cache the slot map, compute slots locally and keep a connection pool per node.
- They follow
MOVED(refresh the map) andASK(one-time redirect), and refresh topology after errors. - Multi-key commands, pipelines and transactions across slots behave differently in each client. Hash tags make them work everywhere.
- Commands split across slots are not atomic.
- Make sure announced node addresses are reachable from clients, or remap them in the client.
Practice
- (Beginner) Start a local cluster (see "Local Development Environments" in 10.3). With your client, print the slot and the node of ten keys, then run
MGETon two keys in different slots and on two keys with the same hash tag.- (Intermediate) Count
MOVEDreplies seen by the server (INFO errorstats,errorstat_MOVED) while a client runs a mixed workload. Then reshard 1,000 slots withredis-cli --cluster reshardduring the workload and compare the counts and the client's error rate.- (Interview) "A Node.js service migrated from a single Redis to a cluster.
MGETcalls with 50 keys still work, but p99 latency doubled. Why might that be?" Hint: think about how the client splits the keys, how many nodes each call now touches, and which node is the slowest.
Handling Failover in Clients
Replication, Sentinel and Cluster (chapter 7) make Redis survive the loss of a primary. They do not make the failover invisible to clients. For several seconds the primary for some keys does not exist. Clients see errors, then have to find the new primary, then the application has to decide what happened to the writes that were in flight. A well-configured client turns a failover into a short burst of errors. A poorly configured one turns it into a long outage or into duplicated and lost writes.
What a client sees
t=0 primary of slots 5461-10922 crashes
t=0..3 s commands to it: connection refused / timeouts (cluster-node-timeout = 3 s)
t≈3-5 s replica promoted; cluster bus spreads the new config
t≈5 s client gets MOVED or reconnects, refreshes the slot map
t>5 s commands succeed on the new primary
This timeline was measured. A redis-py RedisCluster client with socket_timeout=1 incremented a counter every 10 ms while the primary owning the key was shut down (cluster-node-timeout 3000). The client saw 72 ConnectionError exceptions between 1.2 s and 6.6 s after the start (a 5.3 s window), then recovered by itself with no restart. The final counter matched the number of successful calls (551), so in that run no increment was lost or duplicated. That is not guaranteed in general (see below).
Errors to expect
| Error | Meaning during a failover | Client reaction |
|---|---|---|
| Connection refused / reset, timeout | Old primary is down or unreachable | Retry idempotent commands with backoff; refresh topology |
READONLY You can't write against a read only replica | Connected to a server that is now (or still) a replica | Drop connections, rediscover the primary (chapter 7.2) |
MOVED | Slot now served by another node | Follow, refresh slot map |
CLUSTERDOWN The cluster is down | Some slots have no primary yet | Retry after a short delay |
TRYAGAIN | Multi-key command during slot migration | Retry after a short delay |
LOADING Redis is loading the dataset in memory | A restarted node is still loading RDB/AOF | Retry after a delay, or route elsewhere |
MASTERDOWN Link with MASTER is down | Replica with replica-serve-stale-data no lost its primary | Read from another node, or wait |
Libraries handle the routing part (rediscovery, slot map refresh, reconnection) when you use the Sentinel-aware or cluster-aware client. The application has to decide the rest.
The application's decisions
- How long to wait. With the tested settings, writes to the failed shard were impossible for about 5 seconds. Either the request deadline is long enough for the client's retries to bridge that window, or requests fail fast and the caller handles it. Do not let unbounded queues hide the window: Lettuce's request queue is unbounded by default (
requestQueueSize=Integer.MAX_VALUE) and node-redis queues commands while offline, so a long outage can grow memory and then flush a burst of stale commands. Bound them (requestQueueSize,commandsQueueMaxLength,disableOfflineQueue, ioredismaxRetriesPerRequest). - What to retry. Retries bridge the window for idempotent commands. Non-idempotent writes need operation IDs (see "Timeouts and Retries").
- What to do without Redis. Decide per use case: a cache read falls back to the database, a rate limiter may fail open (allow) or closed (reject), a lock should fail closed. A circuit breaker stops calling Redis for a while after repeated errors, which protects the application's threads and the recovering server.
- What may have been lost. Replication is asynchronous (chapter 7.1). Writes acknowledged by the old primary but not yet replicated are lost when the replica is promoted. If that matters, use
WAITfor important writes (chapter 7.1), or keep the source of truth elsewhere. - Subscriptions. Pub/Sub messages published while a subscriber was disconnected are lost (chapter 4.1). Clients resubscribe after reconnecting (ioredis
autoResubscribeis on by default), but consumers that need every message should use streams.
Example: degrading gracefully with a circuit breaker
import time
import redis
from redis.backoff import ExponentialWithJitterBackoff
from redis.retry import Retry
class CircuitBreaker:
"""Stop calling Redis for `cooldown` seconds after `threshold` consecutive failures."""
def __init__(self, threshold: int = 5, cooldown: float = 10.0):
self.threshold, self.cooldown = threshold, cooldown
self.failures, self.open_until = 0, 0.0
def allow(self) -> bool:
return time.monotonic() >= self.open_until # closed, or cool-down over (half-open)
def record(self, ok: bool) -> None:
if ok:
self.failures = 0
return
self.failures += 1
if self.failures >= self.threshold:
self.open_until = time.monotonic() + self.cooldown # open: skip Redis for a while
breaker = CircuitBreaker()
r = redis.Redis(host="localhost", port=6379, socket_timeout=0.2, socket_connect_timeout=0.2,
retry=Retry(ExponentialWithJitterBackoff(base=0.01, cap=0.05), retries=1), # not 10
decode_responses=True)
def get_price(product_id: int, load_from_db) -> str:
key = f"price:{product_id}"
if breaker.allow():
try:
cached = r.get(key) # a cache read: safe to retry, safe to skip
breaker.record(ok=True)
if cached is not None:
return cached
except (redis.ConnectionError, redis.TimeoutError):
breaker.record(ok=False)
return load_from_db(product_id) # degrade: no cache, but the request succeeds
price = load_from_db(product_id)
if breaker.allow():
try:
r.set(key, price, ex=300)
except (redis.ConnectionError, redis.TimeoutError):
breaker.record(ok=False)
return price
The bounded retry policy matters as much as the breaker. Against a stopped server, 20 calls of get_price took 19 s with redis-py's default policy (10 retries with backoff, about 4 s per failing call until the breaker opened) and 0.06 s with one retry.
Test it before production does
Failover behavior depends on the client version, its settings and the deployment. Measure it the way the timeline above was measured: run a loop of writes, kill or fail over the primary (SHUTDOWN NOSAVE on a test node, SENTINEL FAILOVER, CLUSTER FAILOVER on a replica for a planned switch), and record the error window, the error types and whether the data matches the successful calls.
Beyond a single deployment
For applications that run against two independent Redis deployments (for example Active-Active databases in two regions, chapter 7.4), recent clients can fail over between them on the client side, with health checks and circuit breakers: redis-py MultiDBClient (marked experimental in 8.1) and Jedis MultiDbClient.
Key Takeaways
- A failover is a window of errors (about 5 s in the measured test), not an instant switch.
- Use Sentinel-aware or cluster-aware clients so rediscovery and slot map refresh are automatic.
- Bound waiting: timeouts, retry budgets and offline queues. Unbounded queues turn outages into memory growth.
- Retry idempotent commands only. Asynchronous replication can lose acknowledged writes.
- Decide per use case what to do when Redis is unavailable, and protect the application with a circuit breaker.
- Rehearse failovers against your real client configuration.
Practice
- (Beginner) Using the cluster from 10.3, run a loop that increments a counter every 10 ms and counts successes and exceptions by type. Stop the primary of that key's slot. Record the error window and compare the counter with the success count.
- (Intermediate) Repeat the experiment with
cluster-node-timeoutof 1,000, 3,000 and 15,000 ms, and with client socket timeouts of 0.2 s and 5 s. Plot the error window. Which setting dominates?- (Interview) "During a Sentinel failover, our Java service (Lettuce, default settings) ran out of memory, although Redis was down for only 30 seconds. Explain a plausible mechanism." Hint: look at what Lettuce does with commands issued while disconnected, the size of that buffer, and the request rate.
<a id="103-testing-and-development-workflow"></a>
10.3 Testing and Development Workflow
This subchapter covers the everyday workflow around Redis code: a local environment that behaves like production, integration tests against real servers started from test code, fakes and mocks for fast unit tests, and repeatable test data.
Local Development Environments
A local Redis is easy to start (chapter 1.2). The hard part is making it behave like production closely enough that code which works on a laptop also works in production. Many "works on my machine" bugs with Redis come from differences that are invisible in a quick test:
| Difference | What breaks |
|---|---|
| Version (7.2 locally, 8.x in production, or the reverse) | New commands (HEXPIRE, vector sets), changed error messages, default protocol |
| Modules / Query Engine missing locally | FT.* and JSON.* fail; OM libraries cannot create indexes |
| Standalone locally, cluster in production | Multi-key commands, transactions and Lua scripts across slots fail with CROSSSLOT |
No maxmemory locally | Eviction and OOM errors never appear in development |
Different notify-keyspace-events, ACL users, maxmemory-policy | Notifications missing, NOPERM errors, keys evicted that "should never be evicted" |
| No TLS locally | Certificate and hostname problems appear only at deployment |
The goal is not to copy production exactly. It is to keep the differences that matter visible and deliberate: the same Redis version, the same modules, the same eviction policy, and a cluster available locally when production uses one.
Example: a Compose file with a standalone server and an optional cluster
services:
redis:
image: redis:8.10 # same version as production
command: >
redis-server
--maxmemory 256mb
--maxmemory-policy allkeys-lru
--appendonly yes
ports:
- "127.0.0.1:6379:6379"
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
retries: 10
redis-cluster:
image: redis:8.10
profiles: ["cluster"] # started only with: docker compose --profile cluster up
ports:
- "127.0.0.1:7001-7006:7001-7006"
entrypoint: ["sh", "-c"]
command:
- |
for port in 7001 7002 7003 7004 7005 7006; do
mkdir -p /data/$$port
redis-server --port $$port --cluster-enabled yes \
--cluster-config-file /data/$$port/nodes.conf --dir /data/$$port \
--cluster-announce-ip 127.0.0.1 --save "" --appendonly no --daemonize yes
done
sleep 1
yes yes | redis-cli --cluster create 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 \
127.0.0.1:7004 127.0.0.1:7005 127.0.0.1:7006 --cluster-replicas 1
tail -f /dev/null
Notes on the cluster service:
- All six nodes run in one container, so they reach each other on
127.0.0.1, and with--cluster-announce-ip 127.0.0.1they announce addresses that the host can also reach through the published ports. Separate containers would announce their internal Docker addresses, which a client on the host cannot follow after aMOVED(10.2). $$portescapes$for Compose, so the shell inside the container sees$port.docker compose --profile cluster up -dstarted it in about 10 s, andCLUSTER INFOreportedcluster_state:ok.
Configuration through the environment
Read the connection details from the environment so that the same code runs locally, in CI and in production:
import os
import redis
# redis://localhost:6379/0 locally, rediss://user:password@prod-host:6380/0 in production
r = redis.Redis.from_url(os.environ.get("REDIS_URL", "redis://localhost:6379/0"), decode_responses=True)
For cluster mode, use a separate variable (or a flag) and build a cluster client from it, so the code path that production uses is the one you test locally.
Shared development servers
When several developers share one Redis server, they overwrite each other's keys. Options, from best to worst:
- One local server per developer (Compose, as above). Cheap and isolated.
- One logical database per developer (
/1,/2, ...) on a shared standalone server. Does not work with clusters, which only have database 0. - A key prefix per developer (
dev:alice:), set in configuration. Some clients apply it transparently: iorediskeyPrefix, JediskeyPreProcessor. Lua scripts and hash tags need extra care.
Protect shared servers with an ACL user that cannot run dangerous commands (chapter 11.1), so a FLUSHALL meant for a laptop cannot wipe a team environment.
Everyday tools
| Tool | Use during development |
|---|---|
redis-cli | Inspect keys, run commands, --scan --pattern, --bigkeys (chapter 1.3) |
| Redis Insight | Browse data, profile commands, inspect indexes (chapter 1.3) |
MONITOR | See every command your code sends (development only, chapter 12.1) |
CLIENT LIST | Check how many connections your app opens and which library version it uses |
SLOWLOG GET | Find slow commands early (chapter 12.1) |
Key Takeaways
- Match the production version, modules, topology and memory policy locally. Differences should be deliberate.
- Compose profiles can provide an optional local cluster next to a standalone server.
- Cluster nodes in containers must announce addresses that clients can reach.
- Read connection settings from the environment, so one code path runs everywhere.
- Prefer one server per developer to shared servers with prefixes or database numbers.
Practice
- (Beginner) Start the Compose file above with the cluster profile. Connect with
redis-cli -c -p 7001, set ten keys and check withCLUSTER KEYSLOTandCLUSTER NODESwhere each one went.- (Intermediate) Take a piece of application code that uses
MGETor aMULTIblock over several keys, run it against the standalone server and then the cluster, and fix the cluster failures with hash tags.- (Interview) "A feature passed all tests locally but failed in production with
CROSSSLOT Keys in request don't hash to the same slot. What does that tell you about the development environment, and how would you prevent it from happening again?" Hint: compare topologies, then think about where in the workflow (local, CI, staging) a cluster should exist.
Integration Testing with Testcontainers
Unit tests with fakes are fast but only test your code against an approximation of Redis (see "Mocking Redis"). Integration tests run your Redis code against a real Redis server: the same version, the same commands, Lua, the Query Engine, real TTLs and real error messages. The historical difficulty was managing that server: installing it on every developer machine and CI runner, keeping versions in sync and cleaning up afterwards.
Testcontainers solves this from inside the test code. A test asks for a container image, the library starts it with Docker, waits until the server is ready, gives the test a host and a mapped port, and removes the container at the end, even if the test process crashes (a helper container named Ryuk cleans up). It exists for Java, Python, Node.js, Go, .NET and other languages.
test session starts
└─ start redis:8.10 container (random host port) ── wait for PING ──▶ ready
├─ test 1: FLUSHDB, run code, assert
├─ test 2: FLUSHDB, run code, assert
└─ test 3: FLUSHDB, run code, assert
test session ends
└─ stop and remove container
Container lifecycle
Starting a container takes a few seconds, while flushing a database takes less than a millisecond. So the usual pattern is one container per test session (or test class), and FLUSHDB before each test. A container per test gives perfect isolation but makes a suite of hundreds of tests slow.
Example: pytest
# conftest.py
import pytest
import redis
from testcontainers.community.redis import RedisContainer # testcontainers.redis is deprecated
@pytest.fixture(scope="session")
def redis_container():
with RedisContainer("redis:8.10") as container: # pin the production version
yield container
@pytest.fixture
def r(redis_container):
client = redis.Redis(
host=redis_container.get_container_host_ip(),
port=int(redis_container.get_exposed_port(6379)),
decode_responses=True,
)
client.flushdb() # every test starts from an empty database
yield client
client.close()
# rate_limit.py: the code under test (fixed window limiter, chapter 8.2)
import redis
def allow_request(r: redis.Redis, user_id: str, limit: int, window_s: int) -> bool:
key = f"rate:{user_id}"
with r.pipeline() as p: # MULTI/EXEC
p.incr(key)
p.expire(key, window_s, nx=True) # set the TTL only on the first hit of the window
count, _ = p.execute()
return count <= limit
# test_rate_limit.py
from rate_limit import allow_request
def test_allows_up_to_limit(r):
results = [allow_request(r, "u1", limit=3, window_s=60) for _ in range(5)]
assert results == [True, True, True, False, False]
def test_window_has_ttl(r):
allow_request(r, "u2", limit=3, window_s=60)
assert 0 < r.ttl("rate:u2") <= 60 # a range, not an exact value: time passes
def test_users_are_independent(r):
for _ in range(3):
allow_request(r, "u3", limit=3, window_s=60)
assert allow_request(r, "u4", limit=3, window_s=60)
The three tests passed in 2.6 s, including starting and stopping the container.
Example: Node.js (node:test)
import { test, before, after, beforeEach } from 'node:test';
import assert from 'node:assert/strict';
import { RedisContainer } from '@testcontainers/redis';
import { createClient } from 'redis';
let container, client;
before(async () => {
container = await new RedisContainer('redis:8.10').start();
client = createClient({ url: container.getConnectionUrl() }); // redis://host:port
await client.connect();
});
after(async () => {
await client.close();
await container.stop();
});
beforeEach(async () => {
await client.flushDb();
});
async function addToCart(c, userId, sku, qty) {
const key = `cart:${userId}`;
await c.multi().hIncrBy(key, sku, qty).expire(key, 86400).exec();
}
test('adds quantities for the same SKU', async () => {
await addToCart(client, 'u1', 'sku-1', 2);
await addToCart(client, 'u1', 'sku-1', 3);
assert.deepEqual(await client.hGetAll('cart:u1'), { 'sku-1': '5' });
});
Example: Java (JUnit 5)
import static org.junit.jupiter.api.Assertions.assertEquals;
import java.util.List;
import org.junit.jupiter.api.*;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import com.redis.testcontainers.RedisContainer; // com.redis:testcontainers-redis
import redis.clients.jedis.RedisClient;
@Testcontainers
class LeaderboardTest {
@Container // static: one container for the whole class
static RedisContainer redis = new RedisContainer("redis:8.10");
static RedisClient client;
@BeforeAll
static void connect() { client = RedisClient.create(redis.getRedisURI()); } // redis://host:port
@AfterAll
static void close() { client.close(); }
@BeforeEach
void clean() { client.flushDB(); }
@Test
void topPlayersInScoreOrder() {
client.zadd("lb", 100, "alice");
client.zadd("lb", 250, "bob");
client.zadd("lb", 180, "carol");
assertEquals(List.of("bob", "carol"), client.zrevrange("lb", 0, 1));
}
}
Practical points
- Pin the image tag to the production version (
redis:8.10, notredis:latest), so tests do not change behavior when a new image is published. - CI needs Docker. Most hosted runners have it. When the tests themselves run inside a container (dev containers, some CI setups), Testcontainers must reach the sibling containers. In the containerized setup used for this chapter, the Python library detected the situation and connected to the container's internal address. The Java library tried the mapped port on the Docker gateway, which was not reachable there: the tests needed Ryuk disabled (
TESTCONTAINERS_RYUK_DISABLED=true) and a connection to the container's internal address. Check the Testcontainers documentation for your CI platform before you rely on it. - Clusters: a cluster container needs reachable announced addresses (see "Local Development Environments"). Many teams run their integration tests against a standalone container and keep a smaller set of cluster tests for multi-key and routing code.
- Parallel tests: tests running in parallel against one container must not share keys. See "Data Seeding and Fixtures".
Key Takeaways
- Integration tests against a real Redis catch what fakes miss: real commands, Lua, the Query Engine, TTLs, errors.
- Testcontainers starts a pinned Redis image from test code and cleans it up afterwards.
- Start one container per session or class and
FLUSHDBbefore each test. - Pin the image version, and check how Docker is reached in CI.
Practice
- (Beginner) Turn the
allow_requesttests into your language of choice with Testcontainers. Add a test that the counter resets after the window by using a 1-second window.- (Intermediate) Measure your suite's duration with one container per test and one container per session, for 20 tests. Then add a test that creates a Query Engine index and verify it runs only because the image includes it.
- (Interview) "Your team's Redis tests use an in-memory fake. A production bug in a Lua script was not caught. How would you change the test strategy without making the suite slow?" Hint: split tests into unit and integration layers, think about which code paths need a real server, and about container reuse.
Mocking Redis
Integration tests are the most faithful, but they need Docker and take seconds to start. For fast unit tests, and for simulating failures that are hard to produce with a real server, there are two lighter options: mocks and fakes.
| Approach | What it is | Fidelity | Speed | Best for |
|---|---|---|---|---|
Mock (unittest.mock, Mockito, Jest mocks) | An object that records calls and returns what you program | None: you define the behavior | Fastest | Verifying calls; injecting failures |
| Fake (fakeredis, miniredis, ioredis-mock) | An in-process reimplementation of Redis commands | Good for core commands, gaps elsewhere | Fast | Unit tests of logic that uses core data types |
| Real server (Testcontainers) | The actual Redis | Complete | Seconds to start | Integration tests, Lua, Query Engine, cluster |
Common fakes:
- fakeredis (Python): emulates Redis inside the process and plugs into redis-py.
- miniredis (Go): an in-process server on a real TCP port, used with go-redis.
- ioredis-mock (Node.js): a drop-in replacement for ioredis. Version 8.13.1 declares a peer dependency on ioredis 5, so npm refused to install it next to ioredis 6.
Where fakes diverge
The same operations on fakeredis 2.40 and on Redis 8.10:
| Operation | fakeredis 2.40 | Redis 8.10 |
|---|---|---|
| Key with 50 ms TTL read after 80 ms | Expired (None) | Expired (None) |
INCR on a list | WRONGTYPE error | WRONGTYPE error |
JSON.SET / JSON.GET | Works | Works |
HEXPIRE (field expiration) | Works | Works |
EVAL | Unknown command, unless installed as fakeredis[lua] | Works |
FT.CREATE | Unknown command | Works |
OBJECT ENCODING, INFO | Unknown command | Works |
A fake is good at the core data types and their errors. It is not a substitute for testing scripts, the Query Engine, performance, memory or cluster behavior. Treat a passing test against a fake as "the logic is right", not "it works with Redis".
Example: a fake for logic, a mock for failures
# product_cache.py: the code under test
import json
import logging
import redis
log = logging.getLogger(__name__)
def get_product(r: redis.Redis, db, product_id: int) -> dict:
"""Cache-aside read that degrades to the database when Redis is unavailable."""
key = f"product:{product_id}"
try:
cached = r.get(key)
if cached is not None:
return json.loads(cached)
except redis.ConnectionError:
log.warning("redis unavailable, reading %s from the database", key)
return db.load_product(product_id) # no write-back: Redis is down
product = db.load_product(product_id)
r.set(key, json.dumps(product), ex=300)
return product
# test_product_cache.py
from unittest.mock import MagicMock
import fakeredis
import pytest
import redis
from product_cache import get_product
@pytest.fixture
def db():
db = MagicMock()
db.load_product.return_value = {"id": 1, "name": "Headphones"}
return db
@pytest.fixture
def r():
return fakeredis.FakeRedis(decode_responses=True) # a fresh, empty fake per test
def test_miss_then_hit(r, db):
assert get_product(r, db, 1)["name"] == "Headphones"
assert get_product(r, db, 1)["name"] == "Headphones"
db.load_product.assert_called_once() # second call served from the cache
assert 0 < r.ttl("product:1") <= 300
def test_falls_back_when_redis_is_down(db):
broken = MagicMock(spec=redis.Redis) # spec: only real Redis methods exist
broken.get.side_effect = redis.ConnectionError("connection refused") # inject the failure
assert get_product(broken, db, 1)["name"] == "Headphones"
broken.set.assert_not_called()
Both tests ran in 0.4 s with no server. The second test shows what mocks are best at: an outage is one line to simulate, while producing one with a real server needs stopping containers or network tricks.
Separate FakeRedis instances do not share data. To simulate several clients of one server (for example a writer and a reader), pass the same fakeredis.FakeServer() to each instance.
Design for testability
Code that calls Redis directly from business logic forces every test to involve Redis. A thin repository (or "port") around Redis access helps:
business logic ──▶ CartRepository (interface)
├── RedisCartRepository ◀── integration tests (Testcontainers)
└── InMemoryCartRepository ◀── unit tests of business logic
Unit tests of the business logic then use a simple in-memory implementation of your interface, not a fake of Redis. Only the Redis implementation needs tests against Redis, and those should use a real server.
Key Takeaways
- Mocks verify calls and inject failures. Fakes emulate Redis commands in-process. Real servers give full fidelity.
- fakeredis covers core data types well but not the Query Engine,
OBJECT,INFO, and Lua only with theluaextra. - Use mocks for failure paths (connection errors, timeouts) that are hard to produce otherwise.
- Wrap Redis access behind a repository interface. Test business logic against a simple implementation, and the Redis implementation against a real server.
Practice
- (Beginner) Write fakeredis tests for a function that adds an item to a capped list (
LPUSH+LTRIM, chapter 2.3) and returns the list length.- (Intermediate) Take the circuit breaker from 10.2 and test it with mocks only: simulate 5 consecutive
TimeoutErrors, check that the 6th call does not reach Redis, then advance time (patchtime.monotonic) and check that the next call tries Redis again.- (Interview) "When is a test against an in-memory fake of Redis misleading? Give three concrete examples." Hint: think about features the fake does not implement, behaviors that depend on the server's configuration or topology, and non-functional properties such as latency and memory.
Data Seeding and Fixtures
Tests, demos and local environments need data in Redis: a few keys for a unit test, thousands of products for a search demo, a realistic snapshot to reproduce a bug. A good fixture strategy makes that data repeatable (the same every time), isolated (one test's data does not leak into another's) and fast to load.
Four ways to load data
| Technique | How | Speed | Best for |
|---|---|---|---|
| Factories in test code | Helper functions that create the keys a test needs | Fast for small data | Unit and integration tests |
| Pipelined script | Client pipeline in batches (chapter 4.3) | Fast | Seeding thousands to millions of keys from code |
redis-cli --pipe | Stream a file of commands into the server | Fastest | Large seed files, shell scripts, CI |
| RDB snapshot | Start the server with a prepared dump.rdb | Instant after load | Realistic datasets, bug reproduction |
Factories
A factory creates exactly the data a test needs, with sensible defaults and overrides:
import itertools
import json
_ids = itertools.count(1)
def make_product(r, **overrides) -> str:
"""Create a product hash with defaults; return its key."""
product = {"name": "Test product", "price": 10, "stock": 5, "category": "misc", **overrides}
key = f"product:{next(_ids)}"
r.hset(key, mapping=product)
r.zadd("idx:product:price", {key: product["price"]}) # keep the manual index in sync (chapter 8.4)
return key
def test_cheapest_first(r):
expensive = make_product(r, price=200)
cheap = make_product(r, price=5)
assert r.zrange("idx:product:price", 0, 0) == [cheap]
Tests that state only the values they care about (price=5) are easier to read than tests that load a large shared fixture file where the relevant values are hidden.
Bulk seeding with redis-cli --pipe
redis-cli --pipe streams commands without waiting for each reply and reports a summary at the end. Generate the file with a fixed random seed so every run produces the same data:
# generate_seed.py: python generate_seed.py > seed.txt
import random
random.seed(42) # deterministic: same data on every run
for i in range(1, 10_001):
print(f'HSET product:{i} name "Product {i}" price {random.randint(1, 500)} stock {random.randint(0, 100)}')
print(f'ZADD idx:product:price {random.randint(1, 500)} product:{i}')
cat seed.txt | redis-cli --pipe
# All data transferred. Waiting for the last reply...
# Last reply received from server.
# errors: 0, replies: 20000
Loading these 20,000 commands took 0.08 s. The inline format above is fine for simple text values. For values that contain spaces, quotes, newlines or binary data, generate the commands in RESP (chapter 1.3) instead: a RESP-encoded value "hello world\r\nwith newline" loaded intact.
Snapshot fixtures
For a realistic dataset (thousands of keys, many types, indexes), build it once, save it, and start test servers from the snapshot:
redis-cli SAVE # write dump.rdb on the seeded server
docker cp redis-seed:/data/dump.rdb fixtures/products.rdb
from pathlib import Path
from testcontainers.community.redis import RedisContainer
container = RedisContainer("redis:8.10").with_copy_into_container(
Path("fixtures/products.rdb"), "/data/dump.rdb", mode=0o644 # copied before the server starts
)
with container:
r = container.get_client(decode_responses=True)
r.dbsize() # 10004: loaded from the snapshot at startup
RDB files are versioned. A server can load files written by the same or older versions, but not by newer ones (chapter 6.1), so regenerate snapshot fixtures when you upgrade, and keep the generator script under version control next to the file. Avoid snapshots of production data in test fixtures unless they have been anonymized.
Isolation between tests
| Situation | Isolation technique |
|---|---|
| Tests run one at a time | FLUSHDB before each test |
| Tests run in parallel against one standalone server | One logical database per worker |
| Tests run in parallel against a cluster (only database 0) | A unique key prefix per test, with a hash tag if multi-key commands are used, or one container per worker |
| Tests depend on time (TTLs, windows) | Assert ranges (0 < ttl <= 60), use short TTLs, never long sleeps |
Parallel tests are where sharing bites. With pytest-xdist and 4 workers, 8 tests that each expect an empty database and count to 100 all passed when each worker used its own database, and 7 of 8 failed when all workers shared one:
# conftest.py
import pytest
import redis
@pytest.fixture
def r(worker_id): # provided by pytest-xdist: "gw0", "gw1", ... or "master"
index = 0 if worker_id == "master" else int(worker_id.removeprefix("gw"))
client = redis.Redis(host="localhost", port=6379, db=1 + index, decode_responses=True)
client.flushdb() # flushes only this worker's database
yield client
client.close()
Never point a fixture that runs FLUSHDB or FLUSHALL at a shared or production server. A simple guard is to refuse to run unless the URL points at localhost or a test container, or to use an ACL user without @dangerous commands for anything shared (chapter 11.1).
Key Takeaways
- Fixture data should be repeatable, isolated and fast to load.
- Use factories for test-specific data, pipelines or
redis-cli --pipefor bulk data, and RDB snapshots for large realistic datasets. - Generate seed data deterministically (fixed random seed) and use RESP encoding for values with special characters.
- Regenerate RDB fixtures when upgrading Redis, and do not ship unanonymized production data in fixtures.
- Isolate parallel tests with per-worker databases, unique prefixes or separate containers, and guard against flushing the wrong server.
Practice
- (Beginner) Write a seed generator for 1,000 user hashes with a fixed random seed, load it with
redis-cli --pipe, and check that two runs produce identical data by comparing theHGETALLoutput of a sample of keys.- (Intermediate) Build an RDB fixture with 50,000 products and a Query Engine index definition, and start a Testcontainers Redis from it. Measure startup time with and without the fixture, and check
FT.INFOuntilpercent_indexedreaches 1.- (Interview) "Our Redis integration tests pass when run one by one but fail randomly in CI, where they run in parallel. What are the likely causes and how would you fix them?" Hint: think about shared keys and databases,
FLUSHDBin one worker deleting another worker's data, time-dependent assertions, and cluster-specific limits on database numbers.
<a id="11-security"></a>