Revised multi-database client documentation · redis/redis-py@78df745 (original) (raw)

1

`Multi-database client (Active-Active)

2

`=====================================

3

4

The multi-database client lets you connect your application to multiple logical Redis databases at once

5

and operate them as a single, resilient endpoint. It continuously monitors health, detects failures,

6

and fails over to the next healthy database using a configurable strategy. When the previous primary

7

becomes healthy again, the client can automatically fall back to it.

4

The multi-database client allows your application to connect to multiple Redis databases, which are typically replicas of each other.

5

It is designed to work with Redis Software and Redis Cloud Active-Active setups.

6

The client continuously monitors database health, detects failures, and automatically fails over to the next healthy database using a configurable strategy.

7

When the original database becomes healthy again, the client can automatically switch back to it.

8

9

`Key concepts

10

`------------

`@@ -19,7 +19,7 @@ Key concepts

19

20

`- Health checks:

21

` A set of checks determines whether a database is healthy in proactive manner.

22

By default, an "ECHO" check runs against the database (all cluster nodes must

22

By default, an "PING" check runs against the database (all cluster nodes must

23

` pass for a cluster). You can add custom checks. A Redis Enterprise specific

24

` "lag-aware" health check is also available.

25

`@@ -29,19 +29,18 @@ Key concepts

29

` fine-grain tuned configuration of triggering fail over based on organic traffic.

30

31

`- Failover strategy:

32

The default strategy is weight-based. It prefers the highest-weight healthy database.

32

The default strategy is based on staticly configured weights. It prefers the highest weighted healthy database.

33

34

`- Command retry:

35

` Command execution supports retry with backoff. Low-level client retries are disabled and a global retry

36

` setting is applied at the multi-database layer.

37

38

`- Auto fallback:

39

If configured with a positive interval, the client periodically attempts to fall back to a higher-priority

39

If configured with a positive interval, the client periodically attempts to fall back to a higher-weighted

40

` healthy database.

41

42

`- Events:

43

The client emits events like "active database changed" and "commands failed". Pub/Sub re-subscription

44

on database switch is handled automatically.

43

The client emits events like "active database changed" and "commands failed". In addition it resubscribes to Pub/Sub channels automatically.

45

44

46

45

`Synchronous usage

47

46

`-----------------

`@@ -147,7 +146,7 @@ The asyncio API mirrors the synchronous one and provides async/await semantics.

147

146

`MultiDBClient

148

147

`^^^^^^^^^^^^^

149

148

150

`` -

The client exposes the same API as the Redis or RedisCluster client, making it fully interchangeable and ensuring a seamless upgrade for your application. Additionally, it supports runtime reconfiguration, allowing you to add features such as health checks, failure detectors, or even new databases without restarting.

149

`` +

The client exposes the same API as the Redis or RedisCluster client, making it fully interchangeable and ensuring a simple migration of your application code. Additionally, it supports runtime reconfiguration, allowing you to add features such as health checks, failure detectors, or even new databases without restarting.

151

150

152

151

`Configuration

153

152

`-------------

`@@ -274,16 +273,16 @@ define one of the health check policies to evaluate probes result.

274

273

`HealthCheckPolicies.HEALTHY_MAJORITY - Majority of probes should be successful.

275

274

`HealthCheckPolicies.HEALTHY_ANY - Any of probes should be successful.

276

275

277

EchoHealthCheck (default)

276

PingHealthCheck (default)

278

277

`^^^^^^^^^^^^^^^^^^^^^^^^^

279

278

280

The default health check sends the ECHO command

279

The default health check sends the PING command

281

280

`to the database (and to all nodes for clusters).

282

281

283

282

`Lag-Aware Healthcheck (Redis Enterprise Only)

284

283

`^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

285

284

286

This is a special type of healthcheck available for Redis Software and Redis Cloud

285

This is a special type of healthcheck available for Redis (Enterprise) Software

287

286

`that utilizes a REST API endpoint to obtain information about the synchronization

288

287

`lag between a given database and all other databases in an Active-Active setup.

289

288

`@@ -296,7 +295,7 @@ reverse proxy behind an actual REST API endpoint.

296

295

297

296

`from redis.multidb.client import MultiDBClient

298

297

`from redis.multidb.config import MultiDbConfig, DatabaseConfig

299

from redis.multidb.healthcheck import EchoHealthCheck, LagAwareHealthCheck

298

from redis.multidb.healthcheck import PingHealthCheck, LagAwareHealthCheck

300

299

`from redis.retry import Retry

301

300

`from redis.backoff import ExponentialWithJitterBackoff

302

301

`@@ -313,7 +312,7 @@ reverse proxy behind an actual REST API endpoint.

313

312

`health_check_url="https://cluster.example.com",

314

313

` ),

315

314

` ],

316

Add custom checks (in addition to default EchoHealthCheck)

315

Add custom checks (in addition to default PingHealthCheck)

317

316

`health_checks=[

318

317

`# Redis Enterprise REST-based lag-aware check

319

318

` LagAwareHealthCheck(

`@@ -358,15 +357,13 @@ You can add custom health checks for specific requirements:

358

357

`Failure Detection (Reactive Monitoring)

359

358

`-----------------

360

359

361

The failure detector monitor actual command failures and marks databases as unhealthy

362

when failures count and failure rate exceed thresholds within a sliding time window

363

of a few seconds. This catches issues that proactive health checks might miss during

364

real traffic. You can extend the list of failure detectors by providing your own

365

`` -

implementation, configuration defined in the MultiDBConfig class.

360

The failure detector monitors command failures and marks a database as unhealthy when its failure rate exceeds a defined threshold within a sliding time window.

361

Under real traffic conditions, this reactive detection mechanism likely triggers earlier than proactive health checks.

362

`` +

You can extend the set of failure detectors by implementing your own and configuring it through the MultiDBConfig class.

366

363

367

By default failure detector is configured for 1000 failures and 10% failure rate

368

threshold within a 2 seconds sliding window, this could be adjusted regarding

369

your application specifics and traffic.

364

By default the failure detector is configured for 1000 failures and a 10% failure rate

365

threshold within a 2 seconds sliding window. This could be adjusted regarding

366

your application specifics and traffic pattern.

370

367

371

368

`.. code-block:: python

372

369

`@@ -388,13 +385,13 @@ your application specifics and traffic.

388

385

` CustomFailureDetector()

389

386

` )

390

387

391

Failover and auto fallback

388

Failover and automatic fallback

392

389

`--------------------------

393

390

394

Weight-based failover chooses the highest-weight database whose circuit is CLOSED. If no database is

395

`` -

healthy it returns TemporaryUnavailableException. This exception indicates that application can

396

`` -

still send requests for some time (depends on configuration (failover_attempts * failover_delay)

397

`` -

120 seconds by default) until NoValidDatabaseException will be thrown.

391

Weight-based failover chooses the highest-weighted database with a CLOSED circuit. If no database is

392

`` +

healthy it returns TemporaryUnavailableException. This exception indicates that the application should

393

`` +

retry sending requests for a configurable period of time (the configuration (failover_attempts * failover_delay)

394

`` +

defaults to 120 seconds). If none of the databases became available, then a NoValidDatabaseException is thrown.

398

395

399

396

`` To enable periodic fallback to a higher-priority healthy database, set auto_fallback_interval (seconds):

400

397

`@@ -518,4 +515,4 @@ Troubleshooting

518

515

` are configured properly.

519

516

520

517

`- Pub/Sub not receiving messages after failover:

521

Ensure you are using the client’s Pub/Sub helper. The client re-subscribes automatically on switch.

518

Ensure you are using the client’s Pub/Sub helper. The client re-subscribes automatically on switch.