Connecting Redis - Lettuce Reference Guide (original) (raw)

Connections to a Redis Standalone, Sentinel, or Cluster require a specification of the connection details. The unified form is RedisURI. You can provide the database, password and timeouts within theRedisURI. You have following possibilities to create a RedisURI:

1. Use an URI:
   [](#%5F%5Fcodelineno-0-1) RedisURI.create("redis://localhost/");
2. Use the Builder
   [](#%5F%5Fcodelineno-1-1) RedisURI.Builder.redis("localhost", 6379).auth("password").database(1).build();
3. Set directly the values in RedisURI
[](#%5F%5Fcodelineno-2-1) new RedisURI("localhost", 6379, 60, TimeUnit.SECONDS);

URI syntax¶

Redis Standalone

redis :// [[username :] password@] host [:port][/database] [?[timeout=timeout[d|h|m|s|ms|us|ns]] [&clientName=clientName] [&libraryName=libraryName] [&libraryVersion=libraryVersion] ]

Redis Standalone (SSL)

rediss :// [[username :] password@] host [: port][/database] [?[timeout=timeout[d|h|m|s|ms|us|ns]] [&clientName=clientName] [&libraryName=libraryName] [&libraryVersion=libraryVersion] ]

Redis Standalone (Unix Domain Sockets)

redis-socket :// [[username :] password@]path [?[timeout=timeout[d|h|m|s|ms|us|ns]] [&database=database] [&clientName=clientName] [&libraryName=libraryName] [&libraryVersion=libraryVersion] ]

Redis Sentinel

redis-sentinel :// [[username :] password@] host1[:port1] [, host2[:port2]] [, hostN[:portN]] [/database] [?[timeout=timeout[d|h|m|s|ms|us|ns]] [&sentinelMasterId=sentinelMasterId] [&clientName=clientName] [&libraryName=libraryName] [&libraryVersion=libraryVersion] ]

Schemes

• redis Redis Standalone
• rediss Redis Standalone SSL
• redis-socket Redis Standalone Unix Domain Socket
• redis-sentinel Redis Sentinel

Timeout units

• d Days
• h Hours
• m Minutes
• s Seconds
• ms Milliseconds
• us Microseconds
• ns Nanoseconds

Hint: The database parameter within the query part has higher precedence than the database in the path.

RedisURI supports Redis Standalone, Redis Sentinel and Redis Cluster with plain, SSL, TLS and unix domain socket connections.

Hint: The database parameter within the query part has higher precedence than the database in the path. RedisURI supports Redis Standalone, Redis Sentinel and Redis Cluster with plain, SSL, TLS and unix domain socket connections.

Authentication¶

Redis URIs may contain authentication details that effectively lead to usernames with passwords, password-only, or no authentication. Connections are authenticated by using the information provided throughRedisCredentials. Credentials are obtained at connection time fromRedisCredentialsProvider. When configuring username/password on the URI statically, then a StaticCredentialsProvider holds the configured information.

Notes

• When using Redis Sentinel, the password from the URI applies to the data nodes only. Sentinel authentication must be configured for each sentinel node.
• Usernames are supported as of Redis 6.
• Library name and library version are automatically set on Redis 7.2 or greater.

Basic Usage¶

[](#%5F%5Fcodelineno-3-1)RedisClient client = RedisClient.create("redis://localhost"); [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3)StatefulRedisConnection<String, String> connection = client.connect(); [](#%5F%5Fcodelineno-3-4) [](#%5F%5Fcodelineno-3-5)RedisCommands<String, String> commands = connection.sync(); [](#%5F%5Fcodelineno-3-6) [](#%5F%5Fcodelineno-3-7)String value = commands.get("foo"); [](#%5F%5Fcodelineno-3-8) [](#%5F%5Fcodelineno-3-9)... [](#%5F%5Fcodelineno-3-10) [](#%5F%5Fcodelineno-3-11)connection.close(); [](#%5F%5Fcodelineno-3-12) [](#%5F%5Fcodelineno-3-13)client.shutdown();

• Create the RedisClient instance and provide a Redis URI pointing to localhost, Port 6379 (default port).
• Open a Redis Standalone connection. The endpoint is used from the initialized RedisClient
• Obtain the command API for synchronous execution. Lettuce supports asynchronous and reactive execution models, too.
• Issue a GET command to get the key foo.
• Close the connection when you’re done. This happens usually at the very end of your application. Connections are designed to be long-lived.
• Shut down the client instance to free threads and resources. This happens usually at the very end of your application.

Each Redis command is implemented by one or more methods with names identical to the lowercase Redis command name. Complex commands with multiple modifiers that change the result type include the CamelCased modifier as part of the command name, e.g. zrangebyscore andzrangebyscoreWithScores.

Redis connections are designed to be long-lived and thread-safe, and if the connection is lost will reconnect until close() is called. Pending commands that have not timed out will be (re)sent after successful reconnection.

All connections inherit a default timeout from their RedisClient and
and will throw a RedisException when non-blocking commands fail to return a result before the timeout expires. The timeout defaults to 60 seconds and may be changed in the RedisClient or for each connection. Synchronous methods will throw a RedisCommandExecutionException in case Redis responds with an error. Asynchronous connections do not throw exceptions when Redis responds with an error.

RedisURI¶

The RedisURI contains the host/port and can carry authentication/database details. On a successful connect you get authenticated, and the database is selected afterward. This applies
also after re-establishing a connection after a connection loss.

A Redis URI can also be created from an URI string. Supported formats are:

• redis://[password@]host[:port][/databaseNumber] Plaintext Redis connection
• rediss://[password@]host[:port][/databaseNumber] SSL Connections Redis connection
• redis-sentinel://[password@]host[:port][,host2[:port2]][/databaseNumber]#sentinelMasterId for using Redis Sentinel
• redis-socket:///path/to/socket Unix Domain Sockets connection to Redis

Exceptions¶

In the case of an exception/error response from Redis, you’ll receive aRedisException containing
the error message. RedisException is a RuntimeException.

Examples¶

[](#%5F%5Fcodelineno-4-1)RedisClient client = RedisClient.create(RedisURI.create("localhost", 6379)); [](#%5F%5Fcodelineno-4-2)client.setDefaultTimeout(20, TimeUnit.SECONDS); [](#%5F%5Fcodelineno-4-3) [](#%5F%5Fcodelineno-4-4)// … [](#%5F%5Fcodelineno-4-5) [](#%5F%5Fcodelineno-4-6)client.shutdown();

[](#%5F%5Fcodelineno-5-1)RedisURI redisUri = RedisURI.Builder.redis("localhost") [](#%5F%5Fcodelineno-5-2) .withPassword("authentication") [](#%5F%5Fcodelineno-5-3) .withDatabase(2) [](#%5F%5Fcodelineno-5-4) .build(); [](#%5F%5Fcodelineno-5-5)RedisClient client = RedisClient.create(redisUri); [](#%5F%5Fcodelineno-5-6) [](#%5F%5Fcodelineno-5-7)// … [](#%5F%5Fcodelineno-5-8) [](#%5F%5Fcodelineno-5-9)client.shutdown();

[](#%5F%5Fcodelineno-6-1)RedisURI redisUri = RedisURI.Builder.redis("localhost") [](#%5F%5Fcodelineno-6-2) .withSsl(true) [](#%5F%5Fcodelineno-6-3) .withPassword("authentication") [](#%5F%5Fcodelineno-6-4) .withDatabase(2) [](#%5F%5Fcodelineno-6-5) .build(); [](#%5F%5Fcodelineno-6-6)RedisClient client = RedisClient.create(redisUri); [](#%5F%5Fcodelineno-6-7) [](#%5F%5Fcodelineno-6-8)// … [](#%5F%5Fcodelineno-6-9) [](#%5F%5Fcodelineno-6-10)client.shutdown();

[](#%5F%5Fcodelineno-7-1)RedisURI redisUri = RedisURI.create("redis://authentication@localhost/2"); [](#%5F%5Fcodelineno-7-2)RedisClient client = RedisClient.create(redisUri); [](#%5F%5Fcodelineno-7-3) [](#%5F%5Fcodelineno-7-4)// … [](#%5F%5Fcodelineno-7-5) [](#%5F%5Fcodelineno-7-6)client.shutdown();

Streaming Credentials Provider¶

Lettuce 6.6.0 extends RedisCredentialsProvider to support streaming credentials. It is useful when you need to refresh credentials periodically. Example use cases include: token expiration, rotating credentials, etc. Connection configured with RedisCredentialsProvider supporting streaming will be re-authenticated automatically when new credentials are emitted and ReauthenticateBehavior is set to ON_NEW_CREDENTIALS.

Step 1 - Create a Streaming Credentials Provider¶

A simple example of a streaming credentials provider that emits new credentials.

[](#%5F%5Fcodelineno-8-1)public class MyStreamingRedisCredentialsProvider implements RedisCredentialsProvider { [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3) private final Sinks.Many<RedisCredentials> credentialsSink = Sinks.many().replay().latest(); [](#%5F%5Fcodelineno-8-4) [](#%5F%5Fcodelineno-8-5) @Override [](#%5F%5Fcodelineno-8-6) public boolean supportsStreaming() { [](#%5F%5Fcodelineno-8-7) return true; [](#%5F%5Fcodelineno-8-8) } [](#%5F%5Fcodelineno-8-9) [](#%5F%5Fcodelineno-8-10) @Override [](#%5F%5Fcodelineno-8-11) public Mono<RedisCredentials> resolveCredentials() { [](#%5F%5Fcodelineno-8-12) return credentialsSink.asFlux().next(); [](#%5F%5Fcodelineno-8-13) } [](#%5F%5Fcodelineno-8-14) [](#%5F%5Fcodelineno-8-15) @Override [](#%5F%5Fcodelineno-8-16) // Provide a continuous stream of credentials [](#%5F%5Fcodelineno-8-17) public Flux<RedisCredentials> credentials() { [](#%5F%5Fcodelineno-8-18) return credentialsSink.asFlux().onBackpressureLatest(); [](#%5F%5Fcodelineno-8-19) } [](#%5F%5Fcodelineno-8-20) [](#%5F%5Fcodelineno-8-21) public void close() { [](#%5F%5Fcodelineno-8-22) credentialsSink.tryEmitComplete(); [](#%5F%5Fcodelineno-8-23) } [](#%5F%5Fcodelineno-8-24) // Emit new credentials when needed [](#%5F%5Fcodelineno-8-25) public void emitCredentials(String username, char[] password) { [](#%5F%5Fcodelineno-8-26) credentialsSink.tryEmitNext(new StaticRedisCredentials(username, password)); [](#%5F%5Fcodelineno-8-27) } [](#%5F%5Fcodelineno-8-28) [](#%5F%5Fcodelineno-8-29)}

Step 2 - Create a RedisURI with streaming credentials provider¶

[](#%5F%5Fcodelineno-9-1) // Create a streaming credentials provider [](#%5F%5Fcodelineno-9-2) MyStreamingRedisCredentialsProvider streamingCredentialsProvider = new MyStreamingRedisCredentialsProvider(); [](#%5F%5Fcodelineno-9-3) [](#%5F%5Fcodelineno-9-4) // Emit initial credentials [](#%5F%5Fcodelineno-9-5) streamingCredentialsProvider.emitCredentials("testuser", "testpass".toCharArray()); [](#%5F%5Fcodelineno-9-6) [](#%5F%5Fcodelineno-9-7) // Enable automatic re-authentication [](#%5F%5Fcodelineno-9-8) ClientOptions clientOptions = ClientOptions.builder() [](#%5F%5Fcodelineno-9-9) // enable automatic re-authentication [](#%5F%5Fcodelineno-9-10) .reauthenticateBehavior(ClientOptions.ReauthenticateBehavior.ON_NEW_CREDENTIALS) [](#%5F%5Fcodelineno-9-11) .build(); [](#%5F%5Fcodelineno-9-12) [](#%5F%5Fcodelineno-9-13) // Create a RedisURI with streaming credentials provider [](#%5F%5Fcodelineno-9-14) RedisURI redisURI = RedisURI.builder().withHost(HOST).withPort(PORT) [](#%5F%5Fcodelineno-9-15) .withAuthentication(streamingCredentialsProvider) [](#%5F%5Fcodelineno-9-16) .build(); [](#%5F%5Fcodelineno-9-17) [](#%5F%5Fcodelineno-9-18) // RedisClient [](#%5F%5Fcodelineno-9-19) RedisClient redisClient = RedisClient.create(redisURI); [](#%5F%5Fcodelineno-9-20) rediscClient.connect().sync().ping(); [](#%5F%5Fcodelineno-9-21) [](#%5F%5Fcodelineno-9-22) // ... [](#%5F%5Fcodelineno-9-23) // Emit new credentials when needed [](#%5F%5Fcodelineno-9-24) streamingCredentialsProvider.emitCredentials("testuser", "password-rotated".toCharArray());

Microsoft Entra ID Authentication¶

Lettuce 6.6.0 introduces built-in support for authentication with Azure Managed Redis and Azure Cache for Redis using Microsoft Entra ID (formerly Azure Active Directory). It enables seamless integration with Azure's Redis services by fetching authentication tokens and managing the token renewal in the background. Integration is built on top of redis-authx library, and provides support for:

• System-assigned managed identity
• User-assigned managed identity
• Service principal

You can learn more about managed identities in the Microsoft Entra ID documentation.

Basic Usage¶

Pre-requisites¶

• register an application and create a service principal in Azure.
• Create a Redis cache in Azure and grant your service principal access: AMR or ACR documentation.

Step 1 - Add the dependencies¶

Lettuce requires redis-authx-entraid dependency to provide Microsoft Entra ID authentication support. Make sure to include that dependency on your classpath.

If using Maven, add the following dependency to your pom.xml:

[](#%5F%5Fcodelineno-10-1) <dependency> [](#%5F%5Fcodelineno-10-2) <groupId>redis.clients.authentication</groupId> [](#%5F%5Fcodelineno-10-3) <artifactId>redis-authx-entraid</artifactId> [](#%5F%5Fcodelineno-10-4) <version>0.1.1-beta1</version> [](#%5F%5Fcodelineno-10-5) </dependency>

Step 2 - Create Entra ID enabled credentials provider¶

The lifecycle of the credentials provider is not managed by the Lettuce client. You can create it once and reuse it across multiple clients\connections. When no longer needed, you should close the provider to release resources TokenBasedRedisCredentialsProvider#close.

Create Microsoft Entra ID enabled credentials provider¶

[](#%5F%5Fcodelineno-11-1) // Entra ID enabled credentials provider for Service Principle Identity with Client Secret [](#%5F%5Fcodelineno-11-2) TokenBasedRedisCredentialsProvider credentialsSP; [](#%5F%5Fcodelineno-11-3) try ( EntraIDTokenAuthConfigBuilder builder = EntraIDTokenAuthConfigBuilder.builder()) { [](#%5F%5Fcodelineno-11-4) builder.clientId(CLIENT_ID) [](#%5F%5Fcodelineno-11-5) .secret(CLIENT_SECRET) [](#%5F%5Fcodelineno-11-6) .authority(AUTHORITY) // "https://login.microsoftonline.com/{YOUR_TENANT_ID}"; [](#%5F%5Fcodelineno-11-7) .scopes(SCOPES); // "https://redis.azure.com/.default"; [](#%5F%5Fcodelineno-11-8) credentialsSP = TokenBasedRedisCredentialsProvider.create(builder.build()); [](#%5F%5Fcodelineno-11-9) }

You can test the credentials provider by obtaining a token.

[](#%5F%5Fcodelineno-12-1) // Test Entra ID credentials provider can resolve credentials [](#%5F%5Fcodelineno-12-2) credentialsSP.resolveCredentials() [](#%5F%5Fcodelineno-12-3) .doOnNext(c-> System.out.println(c.getUsername())) [](#%5F%5Fcodelineno-12-4) .block();

Step 3 - Enable automatic re-authentication¶

Microsoft Entra ID tokens have a limited lifetime. Lettuce provides a mechanism to automatically re-authenticate when new credentials are emitted by a RedisCredentialsProvider.

[](#%5F%5Fcodelineno-13-1) // Enable automatic re-authentication [](#%5F%5Fcodelineno-13-2) ClientOptions clientOptions = ClientOptions.builder() [](#%5F%5Fcodelineno-13-3) .reauthenticateBehavior(ClientOptions.ReauthenticateBehavior.ON_NEW_CREDENTIALS) [](#%5F%5Fcodelineno-13-4) .build();

Step 4 - Connect with Entra ID enabled credentials provider¶

[](#%5F%5Fcodelineno-14-1) // Use Entra ID credentials provider [](#%5F%5Fcodelineno-14-2) RedisURI redisURI = RedisURI.builder() [](#%5F%5Fcodelineno-14-3) .withHost(HOST) [](#%5F%5Fcodelineno-14-4) .withPort(PORT) [](#%5F%5Fcodelineno-14-5) .withSsl(true) [](#%5F%5Fcodelineno-14-6) .withAuthentication(credentialsSP).build(); [](#%5F%5Fcodelineno-14-7) [](#%5F%5Fcodelineno-14-8) // RedisClient [](#%5F%5Fcodelineno-14-9) RedisClient redisClient = RedisClient.create(redisURI); [](#%5F%5Fcodelineno-14-10) redisClient.setOptions(clientOptions); [](#%5F%5Fcodelineno-14-11) [](#%5F%5Fcodelineno-14-12) try { [](#%5F%5Fcodelineno-14-13) redisClient.setOptions(clientOptions); [](#%5F%5Fcodelineno-14-14) // Connect with Entra ID credentials provider [](#%5F%5Fcodelineno-14-15) try (StatefulRedisConnection<String, String> user1 = redisClient.connect(StringCodec.UTF8)) { [](#%5F%5Fcodelineno-14-16) System.out.println("Connected to redis as :" + user1.sync().aclWhoami()); [](#%5F%5Fcodelineno-14-17) System.out.println("Db size :" + user1.sync().dbsize()); [](#%5F%5Fcodelineno-14-18) } [](#%5F%5Fcodelineno-14-19) } finally { [](#%5F%5Fcodelineno-14-20) redisClient.shutdown(); // Shutdown Redis client and close connections [](#%5F%5Fcodelineno-14-21) credentialsSP.close(); // Shutdown Entra ID Credentials provider [](#%5F%5Fcodelineno-14-22) }