new-features.md

New & Noteworthy

What's new in Lettuce 8.0

• Project Reactor is no longer needed for the synchronous and asynchronous APIs. reactor-core is still a dependency of lettuce-core, but applications that use only sync()/async() can exclude it. The parts that still need Reactor are:

  • the reactive API (reactive(), commands(...ReactiveCommands.factory()));
  • the Kotlin coroutines API;
  • the deprecated RedisCredentialsProvider.

  Internally, connection setup, reconnection, Sentinel and Master/Replica topology discovery, the event bus and trace-context propagation no longer use Reactor. When compiling without Reactor on the classpath, pass a typed CredentialsProvider to RedisURI.setCredentialsProvider(...) and RedisURI.Builder.withAuthentication(...), for example a variable, a cast, CredentialsProvider.from(...) or StaticCredentialsProvider. A bare lambda doesn't compile, because the compiler needs Reactor to choose between those methods' two overloads.

• connectAsync(...) failures now report the original cause and message, as connect(...) does. Previously the asynchronous path could surface a RedisConnectionException with a null message that wrapped a CompletionException.

• RESP3 replies are now decoded the same way inside transactions and on Pub/Sub connections as on regular connections. On a Pub/Sub connection, a command that returns a RESP3 boolean no longer fails with UnsupportedOperationException. Some RESP3 map and set replies whose first element is message or pmessage are no longer mistaken for Pub/Sub messages. Before, such a reply went to the Pub/Sub listeners and the command never completed.

Breaking changes

Lettuce 8.0 removes the Reactor-based APIs deprecated in 7.8 and 7.9, and changes the Reactor-typed extension points that subclasses and custom implementations use.

• Event bus:

  • EventBus.get(), which returned a Flux<Event>, is removed. Use subscribe(Consumer) or subscribe(Class, Consumer), which return a Subscription; see Events for bridging to a Flux.
  • EventBus.subscribe(Consumer) is now abstract, so custom EventBus implementations must implement it.
  • DefaultEventBus(Scheduler) is replaced by DefaultEventBus(EventExecutorGroup) and DefaultEventBus(EventExecutorGroup, int).

• Tracing:

  • TraceContextProvider.getTraceContextLater() is removed. Implement getTraceContextAsync(Map) instead.
  • Tracing.getContext(), Tracing.clearContext() and Tracing.withTraceContextProvider(TraceContextProvider) are removed. Use the methods of the same names on AbstractRedisReactiveCommands.ReactorTraceContext.

• Reactive accessors:

  • reactive() remains available on all stateful connection interfaces as a deprecated default method that delegates to commands(...) with the matching *ReactiveCommands.factory().

  • The connection implementations no longer hold a reactive API instance. Removed:

    • the protected reactive fields;
    • the newRedisReactiveCommandsImpl() factory methods on StatefulRedisConnectionImpl, StatefulRedisPubSubConnectionImpl and StatefulRedisClusterPubSubConnectionImpl;
    • newRedisAdvancedClusterReactiveCommandsImpl() on StatefulRedisClusterConnectionImpl.

    Subclasses that override these methods are no longer called; obtain a custom reactive API through commands(CommandsFactory) instead.

  • commands(CommandsFactory) is now abstract on StatefulRedisConnection, StatefulRedisClusterConnection, StatefulRedisPubSubConnection, StatefulRedisClusterPubSubConnection and StatefulRedisSentinelConnection, so custom implementations of these interfaces must implement it.

• Credentials:

  • StaticCredentialsProvider and TokenBasedRedisCredentialsProvider implement only CredentialsProvider. They no longer implement RedisCredentialsProvider, resolveCredentials() or credentials(). Use resolveCredentialsAsync() and subscribeToCredentials(...), or wrap a provider with RedisCredentialsProvider.adapt(...) where a RedisCredentialsProvider is required.
  • The deprecated RedisURI.getCredentialsProvider() returns such providers wrapped in an adapter, so don't cast its result to a concrete provider type. The adapter of an immediate provider such as StaticCredentialsProvider is still a RedisCredentialsProvider.ImmediateRedisCredentialsProvider, so code that checks for that interface and calls resolveCredentialsNow() keeps working. Otherwise use RedisURI.getCredentialsProviderAsync(). See Authentication.
  • ConnectionState.getCredentialsProvider() and ConnectionState.setCredentialsProvider(RedisCredentialsProvider) are removed in favor of getCredentialsProviderAsync() and setCredentialsProvider(CredentialsProvider).
  • On RedisAuthenticationHandler, the constructor and createHandler(...) variants that take a RedisCredentialsProvider are removed, as are complete() and onNext(RedisCredentials).

• Connection extension points: these now use Supplier<CompletionStage<SocketAddress>> instead of Mono<SocketAddress>:

  • RedisClient.getSocketAddress(RedisURI);
  • RedisClusterClient.getSocketAddressSupplier(...);
  • AbstractRedisClient.connectionBuilder(...);
  • ConnectionBuilder.socketAddressSupplier(...) and socketAddress();
  • the ConnectionWatchdog and MaintenanceAwareConnectionWatchdog constructors and their wrapSocketAddressSupplier(...).

  The watchdog constructors also no longer take a ConnectionFacade.

• RESP3 map replies in transactions: inside MULTI/EXEC on a RESP3 connection, commands whose result is built from the RESP3 reply types now return a RESP3 map reply as a Map, the same as outside a transaction. Before, they returned a flat List of keys and values. This affects EVAL, EVALSHA and FCALL (and their read-only variants) with ScriptOutputType.OBJECT, FUNCTION LIST, CLUSTER LINKS, and dispatch(...) with an ObjectOutput. Code that casts these TransactionResult entries to List must handle a Map instead. RESP2 connections are not affected.

What's new in Lettuce 7.9

• Introduced a reactor-free credentials SPI: CredentialsProvider resolves credentials as a CompletionStage via resolveCredentialsAsync() and no longer requires Project Reactor. It adds a from(Supplier) factory and a nested ImmediateCredentialsProvider (resolveCredentialsNow()) for synchronous resolution, and supports streaming credentials through the callback-based subscribeToCredentials(Consumer<RedisCredentials>, Consumer<Throwable>) that returns an io.lettuce.core.Subscription. RedisURI now stores a CredentialsProvider and exposes getCredentialsProviderAsync(), setCredentialsProvider(CredentialsProvider) and Builder.withAuthentication(CredentialsProvider). The reactive RedisCredentialsProvider (returning Mono through resolveCredentials()/credentials()) now extends CredentialsProvider and is deprecated; the reactive RedisURI accessors are retained as compatibility shims, so existing code keeps working. RedisCredentialsProvider.adapt(CredentialsProvider) wraps a CredentialsProvider for APIs that still require a RedisCredentialsProvider, such as a Spring Data Redis RedisCredentialsProviderFactory, and keeps streaming. An adapted CredentialsProvider.ImmediateCredentialsProvider stays a RedisCredentialsProvider.ImmediateRedisCredentialsProvider.
• Deprecated the Reactor-based resolveCredentials() of StaticCredentialsProvider and resolveCredentials()/credentials() of TokenBasedRedisCredentialsProvider in favor of resolveCredentialsAsync(), resolveCredentialsNow() and subscribeToCredentials(...), which don't require Project Reactor.
• Deprecated the Mono-based connection extension points used by subclasses and custom connection plumbing: both AbstractRedisClient.connectionBuilder(...) overloads, RedisClient.getSocketAddress(RedisURI), RedisClusterClient.getSocketAddressSupplier(...), and the ConnectionWatchdog and MaintenanceAwareConnectionWatchdog constructors and their wrapSocketAddressSupplier(...). Their signatures change in the next major release; there is no replacement yet.

What's new in Lettuce 7.8

• Fixed LCS for non-String key codecs and Redis Cluster through the new lcs(key1, key2) and lcs(key1, key2, LcsArgs) overloads on the sync, async, reactive, cluster node-selection and Kotlin APIs. The keys are now passed as regular key arguments, so they are encoded through the key codec and participate in cluster slot routing; lcs(key1, key2) returns the longest common substring as V. LcsArgs.Builder gained key-less entry points (justLen(), withIdx(), minMatchLen(…), withMatchLen()). Deprecated lcs(LcsArgs), LcsArgs.Builder.keys(…) and LcsArgs.by(…), which encode the keys as plain strings and do not participate in slot routing
• Support for the unified ZRANGE syntax introduced in Redis 6.2 through new zrange and zrangeWithScores overloads (list-returning, plus streaming-channel variants on the sync and async APIs) accepting a ZRange selector: ZRange.byIndex(start, stop), ZRange.byScore(range) (BYSCORE) or ZRange.byLex(range) (BYLEX). Each selector exposes only the options the server accepts for its kind — rev() on all three, limit(...) on score and lexicographical ranges — and zrangeWithScores has no lexicographical overload because BYLEX cannot be combined with WITHSCORES, so illegal combinations do not compile. Available in the sync, async, reactive, cluster node-selection and Kotlin APIs — a single entry point covering the ZREVRANGE, ZRANGEBYSCORE, ZREVRANGEBYSCORE, ZRANGEBYLEX and ZREVRANGEBYLEX variants
• Deprecated the sorted-set range commands that Redis 6.2 superseded with the unified ZRANGE syntax: zrangebylex, zrangebyscore, zrangebyscoreWithScores, zrevrange, zrevrangeWithScores, zrevrangebylex, zrevrangebyscore and zrevrangebyscoreWithScores (all overloads, including the streaming-channel variants) on the sync, async, reactive and cluster node-selection APIs. Each @deprecated note names the zrange/zrangeWithScores overload and ZRange selector option (rev(), limit(...)) that replaces it. The Kotlin coroutine API no longer exposes these commands; use the ZRange-based zrange/zrangeWithScores functions instead
• Deprecated the server-assisted client-side caching support (ClientSideCaching, CacheFrontend, CacheAccessor, RedisCache in io.lettuce.core.support.caching). This implementation is legacy and incomplete and is scheduled for removal in a future major release. There is no replacement yet — a redesigned client-side caching API is planned.
• Fixed ScriptOutputType.OBJECT decoding so top-level scalar responses are returned directly instead of being treated as collections. Top-level integer responses now return Long instead of a one-element List<Long>; RESP arrays remain lists.
• Fixed XAUTOCLAIM reply decoding for pending entries that were deleted from the stream (the third reply element added in Redis 7.0). With JUSTID, those deleted IDs are no longer misreported as claimed messages through ClaimedMessages.getMessages(); they are now exposed through the new ClaimedMessages.getDeletedIds(), which returns an empty list on Redis before 7.0.
• Began making Project Reactor an optional dependency for the client's public API. Added commands(CommandsFactory) on the stateful connection interfaces (StatefulRedisConnection and the cluster, pub/sub and sentinel variants), which returns a command API bound to the connection and cached per factory. Command APIs now expose a static factory() — for example RedisReactiveCommands.factory() — so the reactive API can be obtained via connection.commands(RedisReactiveCommands.factory()). The reactive() accessor is deprecated in favor of this factory-based accessor.
• Deprecated the Reactor-based EventBus.get() (which returns a Flux<Event>) in favor of a callback-based subscription API: EventBus.subscribe(Consumer<Event>) and EventBus.subscribe(Class<T>, Consumer<T>), each returning an io.lettuce.core.Subscription that is closed to stop delivery. This lets event consumers avoid a direct dependency on Project Reactor.
• Deprecated the Reactor (Mono) parts of the tracing SPI: TraceContextProvider.getTraceContextLater() (returning Mono<TraceContext>) is deprecated in favor of the callback-based getTraceContextAsync(...), removing Project Reactor from the trace-context propagation path used by custom TraceContextProvider implementations.

What's new in Lettuce 7.7

• Probabilistic data structures (RedisBloom) support through RedisBloomFilterCommands, RedisCuckooFilterCommands, RedisTopKCommands, RedisCMSCommands and RedisTDigestCommands, with the respective async, reactive and Kotlin APIs — covering Bloom Filter (BF.*), Cuckoo Filter (CF.*), Top-K, Count-Min Sketch and T-Digest
• Support for the HIMPORT command family for bulk-loading hashes that share the same field names, declaring the field names once per connection and sending only values per hash — see Hash Import
• Support for the SUNIONCARD and SDIFFCARD set cardinality commands
• Support for the LMOVEM and BLMOVEM multi-element list move commands
• Support for the MAXCOUNT and MAXSIZE options on XREAD and XREADGROUP
• Support for FT.ALIASLIST to list search index aliases
• Support for the VISMEMBER Vector Set command — see Redis Vector Sets
• Support for CLIENT NO-TOUCH to control key access-time updates per connection

What's new in Lettuce 7.2

• Support for FT.HYBRID command enabling hybrid vector and full-text search queries
• Ability to expose upstream driver libraries in CLIENT SETINFO payload for better client identification

What's new in Lettuce 7.1

• Support for XREADGROUP with CLAIM argument for atomic message claiming in Redis Streams consumer groups
• Compare-and-Set (CAS) / Compare-and-Delete (CAD) commands through DIGEST, DELEX and SET extensions for optimistic locking patterns
• Support for MSETEX command to atomically set multiple keys with expiration

What's new in Lettuce 7.0

• Maintenance events support for graceful handling of Redis maintenance operations enabling hitless upgrades
• Upgrade to Netty 4.2 with adaptive memory allocator and improved threading model
• RediSearch cluster mode support with cursor sticking and read operation distribution across nodes
• String-based JSON API to avoid unnecessary byte-to-string conversions
• Removal of deprecated APIs as part of major version cleanup

What’s new in Lettuce 6.8

• RediSearch support through RediSearchCommands and the respective reactive, async and Kotlin APIs

What’s new in Lettuce 6.7

• VectorSet support through RedisVectorSetCommands and the respective reactive, async and Kotlin APIs
• ConnectionPoolSupport also allows the user to provide custom connection validations

What’s new in Lettuce 6.6

• Support HGETDEL, HGETEX and HSETEX
• Introduce command replay filter to avoid command replaying after reconnect
• Deprecate the STRALGO command and implement the LCS in its place
• Token based authentication integration with core extension

What’s new in Lettuce 6.5

• RedisJSON support through RedisJSONCommands and the respective reactive, async and Kotlin APIs
• Complete support for all CLUSTER commands (added CLUSTER MYSHARDID and CLUSTER LINKS)
• Added support for the CLIENT TRACKING command
• Migrated the documentation to MkDocs

What’s new in Lettuce 6.4

• Hash Field Expiration is now fully supported
• Sharded Pub/Sub is now fully supported
• Support CLIENT KILL with [MAXAGE] parameter and HSCAN with NOVALUES parameter

What’s new in Lettuce 6.3

• Redis Function support (fcall and FUNCTION commands).

• Support for Library Name and Version through LettuceVersion. Automated registration of the Lettuce library version upon connection handshake.

• Support for Micrometer Tracing to trace observations (distributed tracing and metrics).

What’s new in Lettuce 6.2

• RedisCredentialsProvider abstraction to externalize credentials and credentials rotation.

• Retrieval of Redis Cluster node connections using ConnectionIntent to obtain read-only connections.

• Master/Replica now uses SENTINEL REPLICAS to discover replicas instead of SENTINEL SLAVES.

What’s new in Lettuce 6.1

• Kotlin Coroutines support for SCAN/HSCAN/SSCAN/ZSCAN through ScanFlow.

• Command Listener API through RedisClient.addListener(CommandListener).

• Micrometer support through MicrometerCommandLatencyRecorder.

• Experimental support for io_uring.

• Configuration of extended Keep-Alive options through KeepAliveOptions (only available for some transports/Java versions).

• Configuration of netty's AddressResolverGroup through ClientResources. Uses DnsAddressResolverGroup when netty-resolver-dns is on the classpath.

• Add support for Redis ACL commands.

• Java Flight Recorder Events

What’s new in Lettuce 6.0

• Support for RESP3 usage with Redis 6 along with RESP2/RESP3 handshake and protocol version discovery.

• ACL authentication using username and password or password-only authentication.

• Cluster topology refresh is now non-blocking.

• Kotlin Coroutine Extensions.

• RxJava 3 support.

• Refined Scripting API accepting the Lua script either as byte[] or String.

• Connection and Queue failures now no longer throw an exception but properly associate the failure with the Future handle.

• Removal of deprecated API including timeout methods accepting TimeUnit. Use methods accepting Duration instead.

• Lots of internal refinements.

• xpending methods return now List<PendingMessage> and PendingMessages

• Spring support removed. Use Spring Data Redis for a seamless Spring integration with Lettuce.

• AsyncConnectionPoolSupport.createBoundedObjectPool(…) methods are now blocking to await pool initialization.

• DecodeBufferPolicy for fine-grained memory reclaim control.

• RedisURI.toString() renders masked password.

• ClientResources.commandLatencyCollector(…) refactored into ClientResources.commandLatencyRecorder(…) returning CommandLatencyRecorder.

What’s new in Lettuce 5.3

• Improved SSL configuration supporting Cipher suite selection and PEM-encoded certificates.

• Fixed method signature for randomkey().

• Un-deprecated ClientOptions.pingBeforeActivateConnection to allow connection verification during connection handshake.

What’s new in Lettuce 5.2

• Allow randomization of read candidates using Redis Cluster.

• SSL support for Redis Sentinel.

What’s new in Lettuce 5.1

• Add support for ZPOPMIN, ZPOPMAX, BZPOPMIN, BZPOPMAX commands.

• Add support for Redis Command Tracing through Brave, see Configuring Client resources.

• Add support for Redis Streams.

• Asynchronous connect() for Master/Replica connections.

• Asynchronous Connection Pooling through AsyncConnectionPoolSupport and AsyncPool.

• Dedicated exceptions for Redis LOADING, BUSY, and NOSCRIPT responses.

• Commands in at-most-once mode (auto-reconnect disabled) are now canceled already on disconnect.

• Global command timeouts (also for reactive and asynchronous API usage) configurable through Client Options.

• Host and port mappers for Lettuce usage behind connection tunnels/proxies through SocketAddressResolver, see Configuring Client resources.

• SCRIPT LOAD dispatch to all cluster nodes when issued through RedisAdvancedClusterCommands.

• Reactive ScanStream to iterate over the keyspace using SCAN commands.

• Transactions using Master/Replica connections are bound to the master node.

What’s new in Lettuce 5.0

• New artifact coordinates: io.lettuce:lettuce-core and packages moved from com.lambdaworks.redis to io.lettuce.core.

• Reactive API now Reactive Streams-based using Project Reactor.

• Redis Command Interfaces supporting dynamic command invocation and Redis Modules.

• Enhanced, immutable Key-Value objects.

• Asynchronous Cluster connect.

• Native transport support for Kqueue on macOS systems.

• Removal of support for Guava.

• Removal of deprecated RedisConnection and RedisAsyncConnection interfaces.

• Java 9 compatibility.

• HTML and PDF reference documentation along with a new project website: https://redis.github.io/lettuce/.