2. Configuration - 《Redisson》 - Devlive 开源社区(devlive.org)

2.1. Programmatic configuration
2.2. Declarative configuration
2.3. Common settings
2.4. Cluster mode
2.5. Replicated mode
2.6. Single instance mode
2.7. Sentinel mode
2.8. Master slave mode
2.9. Proxy mode
2.10. Multi cluster mode
2.11. Multi Sentinel mode

2.1. Programmatic configuration

Programmatic configuration performed by Config object instance. For example:

Config config = new Config();
config.setTransportMode(TransportMode.EPOLL);
config.useClusterServers()
       // use "rediss://" for SSL connection
      .addNodeAddress("perredis://127.0.0.1:7181");
RedissonClient redisson = Redisson.create(config);

2.2. Declarative configuration

Redisson can also be configured in a declarative way by using a user supplied text file in YAML format.

2.2.1 YAML file based configuration

Redisson configuration could be stored in YAML format.
Use config.fromYAML method to read configuration stored in YAML format:

Config config = Config.fromYAML(new File("config-file.yaml"));  
RedissonClient redisson = Redisson.create(config);

Use config.toYAML method to write configuration in YAML format:

Config config = new Config();
// ... many settings are set here
String yamlFormat = config.toYAML();

2.2.2 Variable syntax

Variables are used to parameterize the Redisson configuration and substituted with actual values at Redisson startup. Variables are defined using the ${variable_name} syntax. In order to resolve variable references to their values, the following sources are consulted in sequence of precedence, with later sources preceding earlier ones:

environment variables
Java system properties

Definition example:

singleServerConfig:
  address: "redis://127.0.0.1:${REDIS_PORT}"

Default values complies with shell format. Example:

singleServerConfig:
  address: "redis://127.0.0.1:${REDIS_PORT:-6379}"

2.2.3 Passwords encryption

This feature is available only in Redisson PRO edition.

Redisson supports the Advanced Encryption Standard (AES) encryption for passwords defined in the configuration file with the secret key stored in the file.

org.redisson.config.PasswordCipher class is used to encrypt passwords. Secret key file may contain any characters. Encrypted password has {aes} prefix.

Syntax:

java -cp redisson-all.jar org.redisson.config.PasswordCipher encode <unencrypted password> <path to secret key file>

Usage example:

java -cp redisson-all.jar org.redisson.config.PasswordCipher encode pass123 secret_key.txt

output:

{aes}M+TfpT4T6psLCfS+RHKT7Fx0j6r5wOX535G3NMnaphY=

Secret key file is defined through secretKey setting in Redisson configuration YAML file and applied to all encrypted passwords. Configuration YAML file example:

singleServerConfig:
   address: "rediss://127.0.0.1:6379"
   password: "{aes}M+TfpT4T6psLCfS+RHKT7Fx0j6r5wOX535G3NMnaphY="
   sslTruststore: file:truststore
   sslTruststorePassword: "{aes}31paDOrhnyPfDxXPgqyLZF8QR5yJU3U1bZfhsuM4Ruo="
   secretKey: file:secret_key

2.3. Common settings

Follow settings belong to org.redisson.Config object and common for all modes:

codec

Default value: org.redisson.codec.Kryo5Codec

Redis data codec. Used during read and write Redis data. Several implementations are available.

connectionListener

Default value: null

Connection listener which is triggered when Redisson connected/disconnected to Redis server.

lazyInitialization

Default value: false

Defines whether Redisson connects to Redis only when first Redis call is made and not during Redisson instance creation.

true - connects to Redis only when first Redis call is made
false - connects to Redis during Redisson instance creation

nettyThreads

Default value: 32

Threads amount shared between all internal redis clients used by Redisson. Netty threads are used for Redis response decoding and command sending. 0 = cores_amount * 2

nettyHook

Default value: empty object

Netty hook applied to Netty Bootstrap and Channel objects.

nettyExecutor

Default value: null

Use external ExecutorService which is used by Netty for Redis response decoding and command sending.

executor

Default value: null

Use external ExecutorService which process all listeners of RTopic, RRemoteService invocation handlers and RExecutorService tasks.

eventLoopGroup

Use external EventLoopGroup. EventLoopGroup processes all Netty connection tied with Redis servers by own threads. Each Redisson client creates own EventLoopGroup by default. So if there are multiple Redisson instances in same JVM it would be useful to share one EventLoopGroup among them.

Only io.netty.channel.epoll.EpollEventLoopGroup, io.netty.channel.kqueue.KQueueEventLoopGroup and io.netty.channel.nio.NioEventLoopGroup are allowed for usage.

transportMode

Default value: TransportMode.NIO

Available values:

TransportMode.NIO,
TransportMode.EPOLL - requires netty-transport-native-epoll lib in classpath
TransportMode.KQUEUE - requires netty-transport-native-kqueue lib in classpath

threads

Default value: 16

Threads are used to execute listeners logic of RTopic object, invocation handlers of RRemoteService, RTopic object and RExecutorService tasks.

protocol

Default value: RESP2

Defines Redis protocol version. Available values: RESP2, RESP3

lockWatchdogTimeout

Default value: 30000

RLock object watchdog timeout in milliseconds. This parameter is only used if RLock object acquired without leaseTimeout parameter. Lock expires after lockWatchdogTimeout if watchdog didn’t extend it to the next lockWatchdogTimeout time interval. This prevents against infinity locked locks due to Redisson client crash or any other reason when lock can’t be released in proper way.

checkLockSyncedSlaves

Default value: true

Defines whether to check synchronized slaves amount with actual slaves amount after lock acquisition.

slavesSyncTimeout

Default value: 1000

Defines slaves synchronization timeout in milliseconds applied to each operation of RLock, RSemaphore, RPermitExpirableSemaphore objects.

reliableTopicWatchdogTimeout

Default value: 600000

Reliable Topic watchdog timeout in milliseconds. Reliable Topic subscriber expires after timeout if watchdog didn’t extend it to next timeout time interval. This prevents against infinity grow of stored messages in topic due to Redisson client crush or any other reason when subscriber can’t consumer messages anymore.

addressResolverGroupFactory

Default value: org.redisson.connection.SequentialDnsAddressResolverFactory

Allows to specify customized implementation of DnsAddressResolverGroup.

Available implementations:

org.redisson.connection.DnsAddressResolverGroupFactory - uses default DNS servers list provided by OS.
org.redisson.connection.SequentialDnsAddressResolverFactory - uses default DNS servers list provided by OS and allows to control concurrency level of requests to DNS servers.
org.redisson.connection.RoundRobinDnsAddressResolverGroupFactory - uses default DNS servers list provided by OS in round robin mode.

useScriptCache

Default value: false

Defines whether to use Lua-script cache on Redis side. Most Redisson methods are Lua-script based and this setting turned on could increase speed of such methods execution and save network traffic.

keepPubSubOrder

Default value: true

Defines whether keep PubSub messages handling in arrival order or handle messages concurrently. This setting applied only for PubSub messages per channel.

minCleanUpDelay

Default value: 5

Defines minimum delay in seconds for clean up process of expired entries. Applied to JCache, RSetCache, RClusteredSetCache, RMapCache, RListMultimapCache, RSetMultimapCache, RLocalCachedMapCache, RClusteredLocalCachedMapCache objects.

maxCleanUpDelay

Default value: 1800

Defines maximum delay in seconds for clean up process of expired entries. Applied to JCache, RSetCache, RClusteredSetCache, RMapCache, RListMultimapCache, RSetMultimapCache, RLocalCachedMapCache, RClusteredLocalCachedMapCache objects.

cleanUpKeysAmount

Default value: 100

Defines expired keys amount deleted per single operation during clean up process of expired entries. Applied to JCache, RSetCache, RClusteredSetCache, RMapCache, RListMultimapCache, RSetMultimapCache, RLocalCachedMapCache, RClusteredLocalCachedMapCache objects.

meterMode

Default value: ALL

Defines Micrometer statistics collection mode.

This setting is available only in Redisson PRO edition.

Available values:

ALL - collect both Redis and Redisson objects statistics
REDIS - collect only Redis statistics
OBJECTS - collect only Redisson objects statistics

meterRegistryProvider

Default value: null

Defines Micrometer registry provider used to collect various statistics for Redisson objects. Please refer to statistics monitoring sections for list of all available providers.

This setting is available only in Redisson PRO edition.

useThreadClassLoader

Default value: true

Defines whether to supply Thread ContextClassLoader to Codec. Usage of Thread.getContextClassLoader() may resolve ClassNotFoundException error arise during Redis response decoding. This error might arise if Redisson is used in both Tomcat and deployed application.

performanceMode

Default value: LOWER_LATENCY_MODE_2

Defines command processing engine performance mode. Since all values are application specific (except NORMAL value) it’s recommended to try all of them.

This setting is available only in Redisson PRO edition.

Available values:

HIGHER_THROUGHPUT - switches command processor engine to higher throughput mode
LOWER_LATENCY_AUTO - switches command processor engine to lower latency mode and detect optimal settings automatically
LOWER_LATENCY_MODE_3 - switches command processor engine to lower latency mode with predefined settings set #3
LOWER_LATENCY_MODE_2 - switches command processor engine to lower latency mode with predefined settings set #2
LOWER_LATENCY_MODE_1 - switches command processor engine to lower latency mode with predefined settings set #1
NORMAL - switches command processor engine to normal mode

2.4. Cluster mode

Cluster mode could be used with any hosting.

Compatible with:

Programmatic config example:

Config config = new Config();
config.useClusterServers()
    .setScanInterval(2000) // cluster state scan interval in milliseconds
    // use "rediss://" for SSL connection
    .addNodeAddress("redis://127.0.0.1:7000", "redis://127.0.0.1:7001")
    .addNodeAddress("redis://127.0.0.1:7002");
RedissonClient redisson = Redisson.create(config);

2.4.1. Cluster settings

Documentation covers Redis server cluster configuration is here.
Cluster connection mode is activated by follow line:
ClusterServersConfig clusterConfig = config.useClusterServers();

ClusterServersConfig settings listed below:

checkSlotsCoverage

Default value: true

Enables cluster slots check during Redisson startup.

nodeAddresses

Add Redis cluster node or Redis endpoint addresss in host:port format. Redisson discovers automatically cluster topology. Use rediss:// protocol for SSL connection.

scanInterval

Default value: 1000

Scan interval in milliseconds. Applied to Redis clusters topology scan.

slots

Default value: 231

Partitions amount used for data partitioning. Data partitioning supported by Set, Map, BitSet, Bloom filter, Spring Cache, JCache, Micronaut Cache and Hibernate Cache structures.

This setting is available only in Redisson PRO edition.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

subscriptionMode

Default value: MASTER

Set node type used for subscription operation. Available values:

SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

Сonnection load balancer for multiple Redis servers. Available implementations:

org.redisson.connection.balancer.CommandsLoadBalancer
org.redisson.connection.balancer.WeightedRoundRobinBalancer
org.redisson.connection.balancer.RoundRobinLoadBalancer
org.redisson.connection.balancer.RandomLoadBalancer

subscriptionConnectionMinimumIdleSize

Default value: 1

Minimum idle connection pool size for subscription (pub/sub) channels. Used by RTopic, RPatternTopic, RLock, RSemaphore, RCountDownLatch, RClusteredLocalCachedMap, RClusteredLocalCachedMapCache, RLocalCachedMap, RLocalCachedMapCache objects and Hibernate Local Cached Region Factories.

subscriptionConnectionPoolSize

Default value: 50

Maximum connection pool size for subscription (pub/sub) channels. Used by RTopic, RPatternTopic, RLock, RSemaphore, RCountDownLatch, RClusteredLocalCachedMap, RClusteredLocalCachedMapCache, RLocalCachedMap, RLocalCachedMapCache objects and Hibernate Local Cached Region Factories.

shardedSubscriptionMode

Default value: AUTO

Defines whether to use sharded subscription feature available in Redis 7.0+. Used by RMapCache, RLocalCachedMap, RCountDownLatch, RLock, RPermitExpirableSemaphore, RSemaphore, RLongAdder, RDoubleAdder, Micronaut Session, Apache Tomcat Manager objects.

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node.

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 24

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout in milliseconds during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout in milliseconds. Starts to countdown when Redis command was succesfully sent.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval in milliseconds after which another one attempt to send Redis command will be executed.

failedSlaveReconnectionInterval

Default value: 3000

Interval of Redis Slave reconnection attempt when it was excluded from internal list of available servers. On each timeout event Redisson tries to connect to disconnected Redis server. Value in milliseconds.

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

Defines Credentials resolver which is invoked during connection for Redis server authentication. Returns Credentials object per Redis node address, it contains username and password fields. Allows to specify dynamically changing Redis credentials.

subscriptionsPerConnection

Default value: 5

Subscriptions per subscribe connection limit. Used by RTopic, RPatternTopic, RLock, RSemaphore, RCountDownLatch, RClusteredLocalCachedMap, RClusteredLocalCachedMapCache, RLocalCachedMap, RLocalCachedMapCache objects and Hibernate Local Cached Region Factories.

clientName

Default value: null

Name of client connection.

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

Defines path to SSL truststore. It’s stores certificates which is used to identify server side of SSL connection. SSL truststore is read on each new connection creation and can be dynamically reloaded.

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

Defines path to SSL keystore. It’s stores private key and certificates corresponding to their public keys. Used if server side of SSL connection requires client authentication. SSL keystore is read on each new connection creation and can be dynamically reloaded.

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

This setting allows to detect and reconnect broken connections using PING command. PING command sending interval defined in milliseconds. Useful in cases when netty lib doesn’t invoke channelInactive method for closed connections. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpKeepAliveCount

Default value: 0

Defines the maximum number of keepalive probes TCP should send before dropping the connection. 0 value means use system default setting.

tcpKeepAliveIdle

Default value: 0

Defines the time in seconds the connection needs to remain idle before TCP starts sending keepalive probes. 0 value means use system default setting.

tcpKeepAliveInterval

Default value: 0

Defines the time in seconds between individual keepalive probes. 0 value means use system default setting.

tcpUserTimeout

Default value: 0

Defines the maximum amount of time in milliseconds that transmitted data may remain unacknowledged, or buffered data may remain untransmitted (due to zero window size) before TCP will forcibly close the connection. 0 value means use system default setting.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

natMapper

Default value: no mapper

Defines NAT mapper interface which maps Redis URI object and applied to all Redis connections. Can be used to map internal Redis server IPs to external ones. Available implementations: org.redisson.api.HostPortNatMapper and org.redisson.api.HostNatMapper.

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.4.2. Cluster YAML config format

Below is cluster configuration example in YAML format. All property names matche with ClusterServersConfig and Config object property names.

---
clusterServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  subscriptionMode: "SLAVE"
  nodeAddresses:
  - "redis://127.0.0.1:7004"
  - "redis://127.0.0.1:7001"
  - "redis://127.0.0.1:7000"
  scanInterval: 1000
  pingConnectionInterval: 30000
  keepAlive: false
  tcpNoDelay: true
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.5. Replicated mode

With Replicated mode the role of each node is polled to determine if a failover has occurred resulting in a new master.

Compatible with:

AWS ElastiCache (non clustered)
Azure Redis Cache (non clustered)
Google Cloud Memorystore for Redis High availability

Use Redisson PRO if a single host bounded to multiple slaves or master and slave nodes. Compatible with Aiven Redis hosting.

Programmatic config example:

Config config = new Config();
config.useReplicatedServers()
    .setScanInterval(2000) // master node change scan interval
    // use "rediss://" for SSL connection
    .addNodeAddress("redis://127.0.0.1:7000", "redis://127.0.0.1:7001")
    .addNodeAddress("redis://127.0.0.1:7002");
RedissonClient redisson = Redisson.create(config);

2.5.1. Replicated settings

Replicated connection mode is activated by follow line:

ReplicatedServersConfig replicatedConfig = config.useReplicatedServers();

Replicated ServersConfig settings listed below:

nodeAddresses

Add Redis node address in host:port format. Multiple nodes could be added at once. All nodes (master and slaves) should be defined. For Aiven Redis hosting single hostname is enough. Use rediss:// protocol for SSL connection.

scanInterval

Default value: 1000

Replicated nodes scan interval in milliseconds.

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

Сonnection load balancer for multiple Redis servers. Available implementations:
org.redisson.connection.balancer.CommandsLoadBalancer
org.redisson.connection.balancer.WeightedRoundRobinBalancer
org.redisson.connection.balancer.RoundRobinLoadBalancer
org.redisson.connection.balancer.RandomLoadBalancer

monitorIPChanges

Default value: false

Check each Redis hostname defined in configuration for IP address changes during scan process

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 64

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

subscriptionMode

Default value: MASTER

Set node type used for subscription operation. Available values:

SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

failedSlaveReconnectionInterval

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

database

Default value: 0

Database index used for Redis connection

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

subscriptionsPerConnection

Default value: 5

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.5.2. Replicated YAML config format

Below is replicated configuration example in YAML format. All property names matche with ReplicatedServersConfig and Config object property names.

---
replicatedServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  subscriptionMode: "SLAVE"
  nodeAddresses:
  - "redis://redishost1:2812"
  - "redis://redishost2:2815"
  - "redis://redishost3:2813"
  scanInterval: 1000
  monitorIPChanges: false
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.6. Single instance mode

Single instance mode could be used with any hosting. Supports Azure Redis Cache and Google Cloud Memorystore for Redis.

Programmatic config example:

// connects to 127.0.0.1:6379 by default
RedissonClient redisson = Redisson.create();
Config config = new Config();
config.useSingleServer().setAddress("redis://myredisserver:6379");
RedissonClient redisson = Redisson.create(config);

2.6.1. Single instance settings

Documentation covers Redis single server configuration is here. Multiple IP bindings for single hostname are supported in Proxy mode

Single server connection mode is activated by follow line:
SingleServerConfig singleConfig = config.useSingleServer();

SingleServerConfig settings listed below:

address

Redis server address in host:port format. Use rediss:// protocol for SSL connection.

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

connectionMinimumIdleSize

Default value: 24

Minimum idle Redis connection amount.

connectionPoolSize

Default value: 64

Redis connection maximum pool size.

dnsMonitoringInterval

Default value: 5000

DNS change monitoring interval. Applications must ensure the JVM DNS cache TTL is low enough to support this. Set -1 to disable. Multiple IP bindings for single hostname are supported in Proxy mode.

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

database

Default value: 0

Database index used for Redis connection

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.6.2. Single instance YAML config format

Below is single instance configuration example in YAML format. All property names matche with SingleServerConfig and Config object property names.

---
singleServerConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  address: "redis://127.0.0.1:6379"
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  connectionMinimumIdleSize: 24
  connectionPoolSize: 64
  database: 0
  dnsMonitoringInterval: 5000
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.7. Sentinel mode

Programmatic config example:

Config config = new Config();
config.useSentinelServers()
    .setMasterName("mymaster")
    // use "rediss://" for SSL connection
    .addSentinelAddress("redis://127.0.0.1:26389", "redis://127.0.0.1:26379")
    .addSentinelAddress("redis://127.0.0.1:26319");
RedissonClient redisson = Redisson.create(config);

2.7.1. Sentinel settings

Documentation covers Redis server sentinel configuration is here.

Sentinel connection mode is activated by follow line:
SentinelServersConfig sentinelConfig = config.useSentinelServers();

SentinelServersConfig settings listed below:

checkSentinelsList

Default value: true

Enables sentinels list check during Redisson startup.

dnsMonitoringInterval

Default value: 5000

Interval in milliseconds to check the endpoint’s DNS. Applications must ensure the JVM DNS cache TTL is low enough to support this. Set -1 to disable.

checkSlaveStatusWithSyncing

Default value: true

Check if slave node master-link-status field has status ok.

masterName

Master server name used by Redis Sentinel servers and master change monitoring task.

addSentinelAddress

Add Redis Sentinel node address in host:port format. Multiple nodes at once could be added.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

subscriptionMode

Default value: SLAVE

Set node type used for subscription operation. Available values:

SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

Сonnection load balancer for multiple Redis servers. Available implementations:

org.redisson.connection.balancer.CommandsLoadBalancer
org.redisson.connection.balancer.WeightedRoundRobinBalancer
org.redisson.connection.balancer.RoundRobinLoadBalancer
org.redisson.connection.balancer.RandomLoadBalancer

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 64

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

failedSlaveReconnectionInterval

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

database

Default value: 0

Database index used for Redis connection

password

Default value: null

Password for Redis servers authentication.

username

Default value: null

Username for Redis servers authentication. Requires Redis 6.0+

sentinelPassword

Default value: null

Password for Redis Sentinel servers authentication. Used only if Sentinel password differs from master’s and slave’s.

sentinelUsername

Default value: null

Username for Redis Sentinel servers for authentication. Used only if Sentinel username differs from master’s and slave’s. Requires Redis 6.0+

credentialsResolver

Default value: empty

sentinelsDiscovery

Default value: true

Enables sentinels discovery

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

natMapper

Default value: no mapper

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.7.2. Sentinel YAML config format

Below is sentinel configuration example in YAML format. All property names matche with SentinelServersConfig and Config object property names.

---
sentinelServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  subscriptionMode: "SLAVE"
  sentinelAddresses:
  - "redis://127.0.0.1:26379"
  - "redis://127.0.0.1:26389"
  masterName: "mymaster"
  database: 0
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.8. Master slave mode

Programmatic config example:

Config config = new Config();
config.useMasterSlaveServers()
    // use "rediss://" for SSL connection
    .setMasterAddress("redis://127.0.0.1:6379")
    .addSlaveAddress("redis://127.0.0.1:6389", "redis://127.0.0.1:6332", "redis://127.0.0.1:6419")
    .addSlaveAddress("redis://127.0.0.1:6399");
RedissonClient redisson = Redisson.create(config);

2.8.1. Master slave settings

Documentation covers Redis server master/slave configuration is here.

Master slave connection mode is activated by follow line:
MasterSlaveServersConfig masterSlaveConfig = config.useMasterSlaveServers();

MasterSlaveServersConfig settings listed below:

dnsMonitoringInterval

Default value: 5000

Interval in milliseconds to check the endpoint’s DNS. Applications must ensure the JVM DNS cache TTL is low enough to support this. Set -1 to disable.

masterAddress

Redis master node address in host:port format. Use rediss:// protocol for SSL connection.

addSlaveAddress

Add Redis slave node address in host:port format. Multiple nodes at once could be added. Use rediss:// protocol for SSL connection.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

subscriptionMode

Default value: SLAVE

Set node type used for subscription operation. Available values:

SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

Сonnection load balancer for multiple Redis servers. Available implementations:

org.redisson.connection.balancer.CommandsLoadBalancer
org.redisson.connection.balancer.WeightedRoundRobinBalancer
org.redisson.connection.balancer.RoundRobinLoadBalancer
org.redisson.connection.balancer.RandomLoadBalancer

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 64

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

failedSlaveReconnectionInterval

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

database

Default value: 0

Database index used for Redis connection

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.8.2. Master slave YAML config format

Below is master slave configuration example in YAML format. All property names matche with MasterSlaveServersConfig and Config object property names.

---
masterSlaveServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  subscriptionMode: "SLAVE"
  slaveAddresses:
  - "redis://127.0.0.1:6381"
  - "redis://127.0.0.1:6380"
  masterAddress: "redis://127.0.0.1:6379"
  database: 0
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.9. Proxy mode

Proxy mode supports single or multiple Redis databases (including synced with active-active replication) used for read/write operations. Each Redis hostname might be resolved to more than one IP address.

Depending on value of proxyMode setting there are two modes:

all Redis nodes are primary and used for read/write operation with load balancer
single primary for read/write operation and the rest are idle secondary nodes

Failed nodes detection is managed by scanMode setting.

Compatible with:

This feature is available only in Redisson PRO edition.

Programmatic config example:

Config config = new Config();
// use "rediss://" for SSL connection
config.useProxyServers().addAddress("redis://myredisserver1:6379", "redis://myredisserver2:6379");
RedissonClient redisson = Redisson.create(config);

2.9.1. Proxy mode settings

Proxy servers connection mode is activated by follow line:
ProxyServersConfig proxyConfig = config.useProxyServers();

ProxyServersConfig settings listed below:

addresses

Redis proxy servers addresses in host:port format. If single hostname is defined and DNS monitoring is enabled then all resolved ips are considered as proxy nodes and used by load balancer. Use rediss:// protocol for SSL connection.

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

connectionMinimumIdleSize

Default value: 24

Minimum idle Redis connection amount.

connectionPoolSize

Default value: 64

Redis connection maximum pool size.

scanMode

Default value: PING

Defines scan mode to detect failed Redis nodes. Available values:

PING - Each Redis node is checked using PING command. If Redis node unable to response then it considered as a failed node.
PUBSUB - Messages are sent over pubsub channel per Redis node and should be received by all other Redis nodes. If Redis node unable to subscribe or receive message then it considered as a failed node.

proxyMode

Default value: ALL_ACTIVE

Defines proxy mode.
Available values:

FIRST_ACTIVE - Primary (active) database is a first address in the list of addresses and the rest are idle secondary nodes used after failover.
ALL_ACTIVE - All databases are primary (active) and used for read/write operations.

scanInterval

Default value: 5000

Defines proxy nodes scan interval in milliseconds. 0 means disable.

scanTimeout

Default value: 3000

Defines proxy nodes scan timeout in milliseconds applied per Redis node.

dnsMonitoringInterval

Default value: 5000

DNS change monitoring interval. Applications must ensure the JVM DNS cache TTL is low enough to support this. Set -1 to disable.

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

database

Default value: 0

Database index used for Redis connection

failedNodeReconnectionInterval

When the retry interval reached Redisson tries to connect to the disconnected Redis node. After successful reconnection Redis node is become available for read/write operations execution.

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.9.2. Proxy mode YAML config format

Below is proxy mode configuration example in YAML format. All property names matche with ProxyServersConfig and Config object property names.

---
proxyServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  addresses: "redis://127.0.0.1:6379"
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  connectionMinimumIdleSize: 24
  connectionPoolSize: 64
  database: 0
  dnsMonitoringInterval: 5000
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.10. Multi cluster mode

Supports multiple Redis Cluster setups with active-passive data replication relationship. Replication of the primary Redis Cluster with secondary Redis Cluster is managed by replicationMode setting.

Cluster with all available master nodes becomes the primary. Master nodes availability scan interval is defined by scanInterval setting.

Compatible with:

AWS Redis Global Datastore.

This feature is available only in Redisson PRO edition.

Programmatic config example:

Config config = new Config();
config.useMultiClusterServers()
    .setScanInterval(2000) // cluster state scan interval in milliseconds
    // use "rediss://" for SSL connection
    .addAddress("redis://cluster1:7000", "redis://cluster2:70002");
RedissonClient redisson = Redisson.create(config);

2.10.1. Multi Cluster settings

Multi clusters connection mode is activated by follow line:
ClusterServersConfig clusterConfig = config.useMultiClusterServers();

ClusterServersConfig settings listed below:

checkSlotsCoverage

Default value: true

Enables cluster slots check during Redisson startup.

addresses

Each entry is a Redis cluster setup, which is defined by the Redis hostname of any of nodes in cluster or Redis endpoint. Addresses should be in redis://host:port format. Use rediss:// protocol for SSL connection.

scanInterval

Default value: 5000

Scan interval in milliseconds. Applied to Redis clusters topology scan and primary and secondary clusters scan process. Handles failover between primary and secondary clusters. Cluster with all available master nodes becomes the primary.

slots

Default value: 231

Partitions amount used for data partitioning. Data partitioning supported by Set, Map, BitSet, Bloom filter, Spring Cache, JCache, Micronaut Cache and Hibernate Cache structures.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

datastoreMode

Default value: ACTIVE_PASSIVE

Defines Datastore mode.
Available values:

ACTIVE - only primary (active) cluster is used
ACTIVE_PASSIVE - primary (active) cluster is used for read/write operations and secondary (passive) clusters are used for read operations only
WRITE_ACTIVE_READ_PASSIVE - Primary (active) cluster is used for write operations and secondary (passive) clusters are used for read operations only

subscriptionMode

Default value: SLAVE

Set node type used for subscription operation. Available values:
SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

shardedSubscriptionMode

Default value: AUTO

replicationMode

Default value: NONE

Defines replication of the primary Redis Cluster with secondary Redis Clusters.

Available values:
NONE - No replication executed by Redisson. Replication should be executed on Redis side,
SYNC - Each Redisson method invocation which modifies data is completed only if it has been replicated to all Redis setups,
ASYNC - Each Redisson method invocation which modifies data doesn’t wait for replication to complete on other Redis setups

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

primaryDiscoveryMode

Default value: AUTO

Defines primary Redis Cluster selection mode.

Available values:

FIRST_PRIMARY - Primary database is the first address in the list of addresses
AUTO - Primary database is selected if all master nodes are available

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node.

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 24

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout in milliseconds during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout in milliseconds. Starts to countdown when Redis command was succesfully sent.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval in milliseconds after which another one attempt to send Redis command will be executed.

failedSlaveReconnectionInterval

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

password

Default value: null

Password for Redis server authentication.

username

Default value: null

Username for Redis server authentication. Requires Redis 6.0+

credentialsResolver

Default value: empty

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection.

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

natMapper

Default value: no mapper

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.10.2. Multi Cluster YAML config format

Below is cluster configuration example in YAML format. All property names matche with ClusterServersConfig and Config object property names.

---
multiClusterServersConfig:
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  datastoreMode: "ACTIVE_PASSIVE"
  subscriptionMode: "SLAVE"
  addresses:
  - "redis://cluster1:7004"
  - "redis://cluster2:7001"
  - "redis://cluster3:7000"
  scanInterval: 5000
  pingConnectionInterval: 30000
  keepAlive: false
  tcpNoDelay: true
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"

2.11. Multi Sentinel mode

Supports multiple Redis Sentinel setups with active-passive data replication.

Replication of primary Redis Sentinel setup with secondary Redis Sentinel setups is managed by replicationMode setting. First sentinel host belongs to the active Sentinel setup and others to Passive Sentinel Setups.

This feature is available only in Redisson PRO edition.

Programmatic config example:

Config config = new Config();
config.useMultiSentinelServers()
    .setReplicationMode(ReplicationMode.ASYNC)
    .setMasterName("mymaster")
    // use "rediss://" for SSL connection
    .addSentinelAddress("redis://sentinel_primary_cluster:26389", 
                        "redis://sentinel_secondary_cluster1:26379", 
                        "redis://sentinel_secondary_cluster2:26379")
RedissonClient redisson = Redisson.create(config);

2.11.1. Multi Sentinel settings

Documentation covers Redis server sentinel configuration is here.

Multi Sentinel connection mode is activated by follow line:
MultiSentinelServersConfig sentinelConfig = config.useMultiSentinelServers();

MultiSentinelServersConfig settings listed below:

replicationMode

Default value: NONE

Defines replication of primary Redis Sentinel setup with secondary Redis Sentinel setups.

Available values:

NONE - No replication executed by Redisson. Replication should be executed on Redis side,
SYNC - Each Redisson method invocation which modifies data is completed only if it has been replicated to all Redis setups,
ASYNC - Each Redisson method invocation which modifies data doesn’t wait for replication to complete on other Redis setups

checkSentinelsList

Default value: true

Enables sentinels list check during Redisson startup.

dnsMonitoringInterval

Default value: 5000

Interval in milliseconds to check the endpoint’s DNS. Applications must ensure the JVM DNS cache TTL is low enough to support this. Set -1 to disable.

checkSlaveStatusWithSyncing

Default value: true

Check if slave node master-link-status field has status ok.

masterName

Master server name used by Redis Sentinel servers and master change monitoring task.

addSentinelAddress

Add Redis Sentinel node address in host:port format. Multiple nodes at once could be added.

readMode

Default value: SLAVE

Set node type used for read operation. Available values:

SLAVE - Read from slave nodes, uses MASTER if no SLAVES are available,
MASTER - Read from master node,
MASTER_SLAVE - Read from master and slave nodes

subscriptionMode

Default value: SLAVE

Set node type used for subscription operation. Available values:

SLAVE - Subscribe to slave nodes,
MASTER - Subscribe to master node,

loadBalancer

Default value: org.redisson.connection.balancer.RoundRobinLoadBalancer

subscriptionConnectionMinimumIdleSize

Default value: 1

subscriptionConnectionPoolSize

Default value: 50

slaveConnectionMinimumIdleSize

Default value: 24

Redis ‘slave’ node minimum idle connection amount for each slave node

slaveConnectionPoolSize

Default value: 64

Redis ‘slave’ node maximum connection pool size for each slave node

masterConnectionMinimumIdleSize

Default value: 24

Minimum idle connections amount per Redis master node.

masterConnectionPoolSize

Default value: 64

Redis ‘master’ node maximum connection pool size

idleConnectionTimeout

Default value: 10000

If pooled connection not used for a timeout time and current connections amount bigger than minimum idle connections pool size, then it will closed and removed from pool. Value in milliseconds.

connectTimeout

Default value: 10000

Timeout during connecting to any Redis server.

timeout

Default value: 3000

Redis server response timeout. Starts to countdown when Redis command was succesfully sent. Value in milliseconds.

retryAttempts

Default value: 3

Error will be thrown if Redis command can’t be sended to Redis server after retryAttempts. But if it sent succesfully then timeout will be started.

retryInterval

Default value: 1500

Time interval after which another one attempt to send Redis command will be executed. Value in milliseconds.

failedSlaveReconnectionInterval

Default value: 3000

failedSlaveNodeDetector

Default value: org.redisson.client.FailedConnectionDetector

Defines failed Redis Slave node detector object which implements failed node detection logic via org.redisson.client.FailedNodeDetector interface.

Available implementations:

org.redisson.client.FailedConnectionDetector - marks Redis node as failed if it has ongoing connection errors in defined checkInterval interval in milliseconds. Default is 180000 milliseconds.
org.redisson.client.FailedCommandsDetector - marks Redis node as failed if it has certain amount of command execution errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.
org.redisson.client.FailedCommandsTimeoutDetector - marks Redis node as failed if it has certain amount of command execution timeout errors defined by failedCommandsLimit in defined checkInterval interval in milliseconds.

database

Default value: 0

Database index used for Redis connection

password

Default value: null

Password for Redis servers authentication.

username

Default value: null

Username for Redis servers authentication. Requires Redis 6.0+

sentinelPassword

Default value: null

Password for Redis Sentinel servers authentication. Used only if Sentinel password differs from master’s and slave’s.

sentinelUsername

Default value: null

Username for Redis Sentinel servers for authentication. Used only if Sentinel username differs from master’s and slave’s. Requires Redis 6.0+

credentialsResolver

Default value: empty

sentinelsDiscovery

Default value: true

Enables sentinels discovery

subscriptionsPerConnection

Default value: 5

subscriptionTimeout

Default value: 7500

Defines subscription timeout in milliseconds applied per channel subscription.

clientName

Default value: null

Name of client connection

sslProtocols

Default value: null

Defines array of allowed SSL protocols.
Example values: TLSv1.3, TLSv1.2, TLSv1.1, TLSv1

sslEnableEndpointIdentification

Default value: true

Enables SSL endpoint identification during handshaking, which prevents man-in-the-middle attacks.

sslProvider

Default value: JDK

Defines SSL provider (JDK or OPENSSL) used to handle SSL connections. OPENSSL considered as faster implementation and requires netty-tcnative-boringssl-static to be added in classpath.

sslTruststore

Default value: null

sslTruststorePassword

Default value: null

Defines password for SSL truststore

sslKeystoreType

Default value: null

Defines SSL keystore type.

sslKeystore

Default value: null

sslKeystorePassword

Default value: null

Defines password for SSL keystore

pingConnectionInterval

Default value: 30000

PING command sending interval per connection to Redis. Defined in milliseconds. Set 0 to disable.

keepAlive

Default value: false

Enables TCP keepAlive for connection.

tcpNoDelay

Default value: true

Enables TCP noDelay for connection.

natMapper

Default value: no mapper

nameMapper

Default value: no mapper

Defines Name mapper which maps Redisson object name to a custom name. Applied to all Redisson objects.

commandMapper

Default value: no mapper

Defines Command mapper which maps Redis command name to a custom name. Applied to all Redis commands.

2.11.2. Multi Sentinel YAML config format

Below is sentinel configuration example in YAML format. All property names matche with MultiSentinelServersConfig and Config object property names.

---
multiSentinelServersConfig:
  replicationMode: "ASYNC"
  idleConnectionTimeout: 10000
  connectTimeout: 10000
  timeout: 3000
  retryAttempts: 3
  retryInterval: 1500
  failedSlaveReconnectionInterval: 3000
  failedSlaveNodeDetector: !<org.redisson.client.FailedConnectionDetector> {}
  password: null
  subscriptionsPerConnection: 5
  clientName: null
  loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
  subscriptionConnectionMinimumIdleSize: 1
  subscriptionConnectionPoolSize: 50
  slaveConnectionMinimumIdleSize: 24
  slaveConnectionPoolSize: 64
  masterConnectionMinimumIdleSize: 24
  masterConnectionPoolSize: 64
  readMode: "SLAVE"
  subscriptionMode: "SLAVE"
  sentinelAddresses:
  - "redis://127.0.0.1:26379"
  - "redis://127.0.0.1:26389"
  masterName: "mymaster"
  database: 0
threads: 16
nettyThreads: 32
codec: !<org.redisson.codec.Kryo5Codec> {}
transportMode: "NIO"