Lettuce — Scalable Async Redis Client for Java

Introduction

Lettuce is an advanced Java client for Redis built on top of Netty. Unlike Jedis, Lettuce uses non-blocking I/O, making a single connection safely shareable across multiple threads. It is the default Redis driver in Spring Data Redis and supports synchronous, asynchronous (CompletableFuture), and reactive (Project Reactor) APIs.

What Lettuce Does

• Provides synchronous, asynchronous, and reactive APIs for all Redis commands
• Shares a single connection safely across threads via non-blocking Netty I/O
• Supports Redis Cluster with automatic topology refresh and adaptive routing
• Handles Redis Sentinel for automatic master discovery and failover
• Offers client-side caching and connection pooling for high-throughput use cases

Architecture Overview

Lettuce uses Netty's event loop for network I/O, multiplexing commands over a single TCP connection. Commands are encoded into RESP protocol frames and queued; responses are demultiplexed and dispatched to the correct future or subscriber. For Redis Cluster, Lettuce maintains a topology map and routes commands by hash slot. The reactive API wraps responses in Project Reactor Mono and Flux types.

Self-Hosting & Configuration

• Add lettuce-core as a Maven or Gradle dependency
• Create a RedisClient with a Redis URI including host, port, and optional password
• For Cluster, use RedisClusterClient with seed node URIs
• Configure connection timeout, auto-reconnect, and topology refresh intervals via ClientOptions
• For reactive usage, add Project Reactor to your classpath

Key Features

• Non-blocking I/O with a single thread-safe connection per client
• Three programming models: sync, async (CompletableFuture), and reactive (Reactor)
• Automatic Redis Cluster topology refresh with periodic and adaptive triggers
• TLS/SSL support for encrypted connections to Redis
• Client-side caching with server-assisted invalidation (Redis 6+ tracking)

Comparison with Similar Tools

• Jedis — synchronous and simpler; Lettuce is non-blocking and thread-safe by default
• Redisson — higher-level distributed objects; Lettuce is a lower-level driver
• Spring Data Redis — abstraction layer that uses Lettuce as its default driver
• ioredis (Node.js) — similar async-first philosophy for the JavaScript ecosystem
• redis-rs (Rust) — async Redis client for Rust with comparable design goals

FAQ

Q: When should I choose Lettuce over Jedis? A: Use Lettuce when you need async or reactive APIs, thread-safe shared connections, or Redis Cluster with automatic topology updates.

Q: Does Lettuce support connection pooling? A: Lettuce connections are thread-safe, so pooling is often unnecessary. For high-throughput scenarios, Lettuce provides an optional connection pool via AsyncPool.

Q: Is Lettuce compatible with Valkey? A: Yes. Lettuce communicates via the RESP protocol and works with Valkey, KeyDB, DragonflyDB, and other Redis-compatible servers.

Q: How does Lettuce handle Redis Cluster failover? A: Lettuce periodically refreshes the cluster topology and supports adaptive refresh triggered by MOVED/ASK redirections, automatically routing to new primaries.

Sources

• https://github.com/lettuce-io/lettuce-core
• https://lettuce.io/core/release/reference/