Skip to content

Commit 07bf3b0

Browse files
uglideuglide
authored
[automatic failover] Update failover docs (#4314)
Update failover docs - Add migration guide from 6.x to 7.0 - Add instructions on optional deps - Clean up wording to refer to multiDbClient instead of connection provider
1 parent 158e726 commit 07bf3b0

File tree

1 file changed

+69
-19
lines changed

1 file changed

+69
-19
lines changed

‎docs/failover.md‎

Lines changed: 69 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Automatic Failover and Failback with Jedis
22

3+
> API was significantly changed in 7.0.0. Please follow the migration guide below.
4+
>
5+
> This feature is experimental and may change in future versions.
6+
37
Jedis supports failover and failback for your Redis deployments. This is useful when:
48
1. You have more than one Redis deployment. This might include two independent Redis servers or two or more Redis databases replicated across multiple [active-active Redis Enterprise](https://docs.redis.com/latest/rs/databases/active-active/) clusters.
59
2. You want your application to connect to and use one deployment at a time.
@@ -24,6 +28,51 @@ The remainder of this guide describes:
2428
We recommend that you read this guide carefully and understand the configuration settings before enabling Jedis failover
2529
in production.
2630

31+
## Migration from 6.x to 7.x
32+
33+
In Jedis 6.x, failover was supported using special constructor for `UnifiedJedis`.
34+
In Jedis 7.x, failover is supported using `MultiDbClient` and `MultiDbConfig.builder`:
35+
```java
36+
// Jedis 6.x
37+
JedisClientConfig config = DefaultJedisClientConfig.builder().user("cache").password("secret").build();
38+
39+
ClusterConfig[] clientConfigs = new ClusterConfig[2];
40+
clientConfigs[0] = new ClusterConfig(new HostAndPort("redis-east.example.com", 14000), config);
41+
clientConfigs[1] = new ClusterConfig(new HostAndPort("redis-west.example.com", 14000), config);
42+
43+
MultiClusterClientConfig.Builder builder = new MultiClusterClientConfig.Builder(clientConfigs);
44+
// ...
45+
MultiClusterPooledConnectionProvider provider = new MultiClusterPooledConnectionProvider(builder.build());
46+
UnifiedJedis client = new UnifiedJedis(provider);
47+
48+
// Jedis 7.x
49+
// MultiClusterClientConfig was renamed to MultiDbConfig and MultiDbClient with convenient builder was added
50+
MultiDbConfig multiConfig = MultiDbConfig.builder()
51+
.database(DatabaseConfig.builder(east, config).weight(1.0f).build())
52+
.database(DatabaseConfig.builder(west, config).weight(0.5f).build())
53+
.build();
54+
// Use MultiDbClient instead of UnifiedJedis
55+
MultiDbClient multiDbClient = MultiDbClient.builder().multiDbConfig(multiConfig).build();
56+
```
57+
For more details on configuration options see sections below.
58+
59+
## Installing optional dependencies
60+
61+
Jedis failover support is provided by optional dependencies.
62+
To use failover, add the following dependencies to your project:
63+
```xml
64+
<dependency>
65+
<groupId>io.github.resilience4j</groupId>
66+
<artifactId>resilience4j-circuitbreaker</artifactId>
67+
<version>1.7.1</version>
68+
</dependency>
69+
<dependency>
70+
<groupId>io.github.resilience4j</groupId>
71+
<artifactId>resilience4j-retry</artifactId>
72+
<version>1.7.1</version>
73+
</dependency>
74+
```
75+
2776
## Basic usage
2877

2978
To configure Jedis for failover, you specify a weighted list of Redis databases.
@@ -41,18 +90,19 @@ Let's look at one way of configuring Jedis for this scenario.
4190
First, start by defining the initial configuration for each Redis database available and prioritize them using weights.
4291

4392
```java
44-
JedisClientConfig config = DefaultJedisClientConfig.builder().user("cache").password("secret")
45-
.socketTimeoutMillis(5000).connectionTimeoutMillis(5000).build();
93+
JedisClientConfig config = DefaultJedisClientConfig.builder()
94+
.user("cache").password("secret")
95+
.socketTimeoutMillis(5000).connectionTimeoutMillis(5000).build();
4696

4797
// Custom pool config per database can be provided
4898
ConnectionPoolConfig poolConfig = new ConnectionPoolConfig();
49-
poolConfig.setMaxTotal(8);
50-
poolConfig.setMaxIdle(8);
51-
poolConfig.setMinIdle(0);
52-
poolConfig.setBlockWhenExhausted(true);
53-
poolConfig.setMaxWait(Duration.ofSeconds(1));
54-
poolConfig.setTestWhileIdle(true);
55-
poolConfig.setTimeBetweenEvictionRuns(Duration.ofSeconds(1));
99+
poolConfig.setMaxTotal(8);
100+
poolConfig.setMaxIdle(8);
101+
poolConfig.setMinIdle(0);
102+
poolConfig.setBlockWhenExhausted(true);
103+
poolConfig.setMaxWait(Duration.ofSeconds(1));
104+
poolConfig.setTestWhileIdle(true);
105+
poolConfig.setTimeBetweenEvictionRuns(Duration.ofSeconds(1));
56106

57107
HostAndPort east = new HostAndPort("redis-east.example.com", 14000);
58108
HostAndPort west = new HostAndPort("redis-west.example.com", 14000);
@@ -65,7 +115,7 @@ MultiDbConfig.Builder multiConfig = MultiDbConfig.builder()
65115
The configuration above represents your two Redis deployments: `redis-east` and `redis-west`.
66116

67117
Continue using the `MultiDbConfig.Builder` builder to set your preferred retry and failover configuration.
68-
Then build a `MultiDbClient`.
118+
Then build a `MultiDbClient`:
69119

70120
```java
71121
// Configure circuit breaker for failure detection
@@ -96,14 +146,14 @@ MultiDbClient multiDbClient = MultiDbClient.builder()
96146
In the configuration here, we've set a sliding window size of 1000 and a failure rate threshold of 50%.
97147
This means that a failover will be triggered only if both 500 out of any 1000 calls to Redis fail (i.e., the failure rate threshold is reached) and the minimum number of failures is also met.
98148

99-
You can now use this `MultiDbClient` instance, and the connection management and failover will be handled transparently.
149+
You can now use this `MultiDbClient` instance in your application to execute Redis commands.
100150

101151
## Configuration options
102152

103153
Under the hood, Jedis' failover support relies on [resilience4j](https://resilience4j.readme.io/docs/getting-started),
104154
a fault-tolerance library that implements [retry](https://resilience4j.readme.io/docs/retry) and [circuit breakers](https://resilience4j.readme.io/docs/circuitbreaker).
105155

106-
Once you configure Jedis for failover using the `MultiDbConnectionProvider`, each call to Redis is decorated with a resilience4j retry and circuit breaker.
156+
Once you configure a `MultiDbClient`, each call to Redis is decorated with a resilience4j retry and circuit breaker.
107157

108158
By default, any call that throws a `JedisConnectionException` will be retried up to 3 times.
109159
If the call fail then the circuit breaker will record a failure.
@@ -136,13 +186,13 @@ For failover, Jedis uses a circuit breaker to detect when a Redis database has f
136186
Failover configuration is encapsulated in `MultiDbConfig.CircuitBreakerConfig` and can be provided using the `MultiDbConfig.Builder.failureDetector()`.
137187
Jedis uses the following circuit breaker settings:
138188

139-
| Setting | Default value | Description |
140-
|-----------------------------------------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
141-
| Sliding window size | 2 | The size of the sliding window. Units depend on sliding window type. The size represents seconds. |
142-
| Threshold min number of failures | 1000 | Minimum number of failures before circuit breaker is tripped. |
143-
| Failure rate threshold | `10.0f` | Percentage of calls within the sliding window that must fail before the circuit breaker transitions to the `OPEN` state. |
144-
| Circuit breaker included exception list | [JedisConnectionException] | A list of Throwable classes that count as failures and add to the failure rate. |
145-
| Circuit breaker ignored exception list | null | A list of Throwable classes to explicitly ignore for failure rate calculations. | |
189+
| Setting | Default value | Description |
190+
|-----------------------------------------|----------------------------|--------------------------------------------------------------------------------------------------------------------------|
191+
| Sliding window size | 2 | The size of the sliding window. Units depend on sliding window type. The size represents seconds. |
192+
| Threshold min number of failures | 1000 | Minimum number of failures before circuit breaker is tripped. |
193+
| Failure rate threshold | `10.0f` | Percentage of calls within the sliding window that must fail before the circuit breaker transitions to the `OPEN` state. |
194+
| Circuit breaker included exception list | [JedisConnectionException] | A list of Throwable classes that count as failures and add to the failure rate. |
195+
| Circuit breaker ignored exception list | null | A list of Throwable classes to explicitly ignore for failure rate calculations. | |
146196

147197
### Health Check Configuration and Customization
148198

0 commit comments

Comments
 (0)