Pipelining batches many Redis commands into one round trip

Wed, 20 Jan 2027 00:00:00 +0000

Pipelining lets a client send several Redis commands without waiting for each reply before sending the next. It reduces request-response waiting and can amortize socket I/O overhead. Redis still executes the commands and produces their replies; batching is neither a promise of parallel execution nor a transaction boundary.

Fewer waits, not fewer commands

A synchronous loop repeatedly sends one command and waits. A pipeline instead sends a sequence and consumes the corresponding replies in order. Thinking of a batch as roughly one round trip is useful for latency estimates, but it does not promise one TCP packet, one system call, or simultaneous arrival of all replies.

The benefit is not exclusively on a distant network. Grouping I/O can reduce syscall and scheduling overhead even on a local connection, increasing achieved throughput without sharding. Conversely, pipelining does not erase expensive command work or bandwidth limits. Locate the actual bottleneck before concluding that adding shards is the necessary next step.

Plain pipelines have no non-interleaving guarantee. Other clients may execute commands between members of a batch, though a particular run need not exhibit interleaving. Seeing consecutive commands in one successful test does not establish transactional isolation.

Distinguish ordering from branching

Commands need not be completely unrelated. SET a counter, INCR it, then GET it can share one pipeline because all request arguments are known beforehand; their order establishes the intended server-side data dependency. What cannot fit in that same prebuilt batch is a later request whose key or argument must be calculated from an earlier reply.

Split such reply-dependent work into stages, or use a suitable native command or bounded script. If a client-side decision needs concurrency protection, consider WATCH. MULTI/EXEC provides execution isolation, not automatic rollback of successful commands after a runtime error.

Check your client’s defaults. redis-py 8.1.0 uses transactions for pipeline() unless transaction=False is specified. A benchmark of the default wrapper therefore measures both batching and MULTI/EXEC. The explicit option below separates those mechanisms and uses server command counters to verify which were invoked.

When it breaks

A command error does not cancel later commands already submitted in a plain pipeline. Its reply retains a position among the other replies. Inspect every result; treating the presence of an array as overall success can hide a rejected write and leave inconsistent application state.

By default, redis-py can raise ResponseError after reading the replies. execute(raise_on_error=False) instead returns command errors as elements. Neither mode reverses successful writes. A dropped connection is different: missing replies can leave an unknown executed prefix, and continuing after the last acknowledged command can still repeat an unacknowledged write that already ran.

Do not blindly retry increments or other non-idempotent effects. Even rewriting a fixed value needs a concurrency contract if another writer could have changed it meanwhile. Reliable recovery belongs to the business operation, not to the pipeline’s transport optimization.

Bound both batch count and bytes. The client buffers requests and results, and Redis may buffer replies that the client has not consumed. Large payloads or slow readers can exhaust memory or increase latency. A universal batch size measured only in command count ignores these costs.

Check it quickly

Use a POSIX environment with a C compiler, make, curl, tar, and Python 3.10 or newer. This ran on macOS with Python 3.14.4, Redis 8.10.1, and redis-py 8.1.0. The setup compiles Redis core with libc and installs the client in a temporary virtual environment, not a system service.

redis_lab=$(mktemp -d)
curl --fail --location --output "$redis_lab/redis.tar.gz" https://download.redis.io/releases/redis-8.10.1.tar.gz
tar -xzf "$redis_lab/redis.tar.gz" -C "$redis_lab"
make -C "$redis_lab/redis-8.10.1" build redis -j2 MALLOC=libc
export REDIS_SERVER="$redis_lab/redis-8.10.1/src/redis-server"
python3 -m venv "$redis_lab/venv"
"$redis_lab/venv/bin/python" -m pip install redis==8.1.0

Run the Python block with "$redis_lab/venv/bin/python" in the same shell. It starts a private Unix-socket Redis under /tmp with TCP and persistence disabled, then stops only its own process and cleans its runtime directory. Downloads require network access. Existing Redis instances are not contacted.

from contextlib import contextmanager
import os
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
import time

import redis
from redis.backoff import NoBackoff
from redis.retry import Retry


@contextmanager
def instance():
 with TemporaryDirectory(prefix="redis-lab-", dir="/tmp") as directory:
 endpoint = str(Path(directory) / "redis.sock")
 process = subprocess.Popen([
 os.environ["REDIS_SERVER"], "--port", "0",
 "--unixsocket", endpoint, "--unixsocketperm", "700",
 "--save", "", "--appendonly", "no", "--dir", directory,
 "--maxmemory-policy", "noeviction",
 ], stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
 client = redis.Redis(unix_socket_path=endpoint, decode_responses=False,
 socket_timeout=2, retry=Retry(NoBackoff(), 0))
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "Redis exited during startup"
 try:
 if client.ping():
 break
 except redis.ConnectionError:
 if time.monotonic() >= deadline:
 raise
 time.sleep(0.02)
 yield client
 finally:
 client.close()
 if process.poll() is None:
 process.terminate()
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors.decode()


def calls(client, name):
 return client.info("commandstats").get(f"cmdstat_{name}", {}).get("calls", 0)


with instance() as client:
 initial_multi = calls(client, "multi")
 initial_exec = calls(client, "exec")
 with client.pipeline(transaction=False) as batch:
 assert batch.set("counter", 4) is batch
 batch.incr("counter")
 batch.get("counter")
 assert client.get("counter") is None
 assert batch.execute() == [True, 5, b"5"]
 assert calls(client, "multi") == initial_multi
 assert calls(client, "exec") == initial_exec
 print("plain pipeline buffers locally and returns ordered SET, INCR, GET results")

 with client.pipeline() as batch:
 batch.set("default-counter", 4)
 batch.incr("default-counter")
 assert batch.execute() == [True, 5]
 assert calls(client, "multi") == initial_multi + 1
 assert calls(client, "exec") == initial_exec + 1
 print("redis-py's default pipeline also sends MULTI and EXEC")

 client.set("wrong-type", "text")
 with client.pipeline(transaction=False) as batch:
 batch.set("before-error", "written")
 batch.lpush("wrong-type", "item")
 batch.set("after-error", "written")
 responses = batch.execute(raise_on_error=False)
 assert len(responses) == 3
 assert responses[0] is responses[2] is True
 assert isinstance(responses[1], redis.ResponseError)
 assert "WRONGTYPE" in str(responses[1])
 assert client.mget("before-error", "wrong-type", "after-error") == [
 b"written", b"text", b"written",
 ]
 print("a plain pipeline returns the error in place and keeps both surrounding writes")

 with client.pipeline(transaction=False) as batch:
 batch.incr("raise-before")
 batch.lpush("wrong-type", "item")
 batch.incr("raise-after")
 try:
 batch.execute()
 except redis.ResponseError as error:
 assert "WRONGTYPE" in str(error)
 else:
 raise AssertionError("default execute should raise the command error")
 assert client.mget("raise-before", "raise-after") == [b"1", b"1"]
 print("raising the client exception does not cancel already-sent later commands")

The first batch returns a pipeline object while buffering SET, then queues INCR and GET. Before execute, the counter is absent. Execution returns True, five, and the bytes for five in order. This demonstrates local buffering and a valid ordered dependency without waiting for intermediate replies.

Server counters show no MULTI or EXEC for that explicit nontransactional batch. The default pipeline then increases both counters once, proving that the client added transaction commands. The check runs on an isolated server so unrelated traffic cannot change those counters.

Next, LPUSH targets a string between two valid writes. Returning errors as elements preserves the middle WRONGTYPE response, and both surrounding writes remain. The final case enables the default exception behavior; both increments still apply before the exception reaches the application.

Four summaries follow assertions on replies, counters, and stored values. This exercise checks batching semantics, not a guaranteed speedup, a particular cross-client schedule, or recovery after a broken connection. The separate timing exercise measures one controlled workload rather than treating these correctness assertions as performance evidence.

Sources