Redis-Py-Cluster

2.1.3 · maintenance · verified Thu Apr 09

redis-py-cluster is a Python client library designed for communicating with Redis Clusters, building upon the core functionality of the redis-py library. The current version is 2.1.3. While it was a primary solution for Redis Cluster connectivity, its development has seen an irregular cadence, with the last major release in May 2021, as cluster support has since been integrated directly into the `redis-py` library itself.

Warnings

breaking The `redis-py` library (version 4.1.0 and later) now includes native support for Redis Cluster, effectively superseding `redis-py-cluster`. New projects or upgrades of `redis-py` should consider migrating to `redis.cluster.RedisCluster` for direct cluster support.
Fix: For new projects or when upgrading `redis-py` to 4.1.0+, use `from redis.cluster import RedisCluster` instead of `from rediscluster import RedisCluster`.
breaking In version 2.0.0, the main client class was renamed from `StrictRedisCluster` to `RedisCluster`. Code using the old class name will no longer work.
Fix: Update all instantiations from `StrictRedisCluster(...)` to `RedisCluster(...)`.
gotcha The `redis-py-cluster` 2.x.x series requires `redis-py` versions strictly within `3.0.0 <= redis < 4.0.0`. Using `redis-py` versions outside this range can lead to compatibility issues or errors.
Fix: Ensure your `redis` dependency is pinned to `redis>=3.0.0,<4.0.0` if using `redis-py-cluster` 2.x.x. Check the `redis-py-cluster` documentation for specific `redis-py` version requirements if using other major versions.
deprecated Version 2.1.x is the last major release line to support Python 2.7. Future major versions (e.g., 3.0.x) will require Python 3.5+.
Fix: Migrate to Python 3.5+ for continued support and future compatibility. For new projects, consider using `redis-py`'s native cluster support on Python 3.
gotcha In Python 3, Redis responses are typically bytes. To receive Python strings (Unicode), you must instantiate the client with `decode_responses=True`.
Fix: When creating `RedisCluster`, pass `decode_responses=True` as an argument: `rc = RedisCluster(startup_nodes=nodes, decode_responses=True)`.
gotcha In version 2.1.3, the default `max_connection` in `ClusterBlockingConnectionPool` was changed to 50 to prevent issues with infinite loops in the queue mechanism.
Fix: If you rely on a specific connection pool size, explicitly set `max_connections` when initializing `ClusterBlockingConnectionPool` or `RedisCluster` if it uses this pool type.
gotcha Support for using read replicas for read commands within pipelines was improved in 2.1.3, but the release notes indicate this feature 'might be unstable to use as own risk'.
Fix: Exercise caution when using read replicas with pipelines. Test thoroughly in your environment and consider alternatives if stability issues arise.

Install

pip install redis-py-cluster Install stable version

Imports

RedisCluster
```
from rediscluster import RedisCluster
```
The class `StrictRedisCluster` was renamed to `RedisCluster` in version 2.0.0.
ClusterPipeline
```
from rediscluster import ClusterPipeline
```
Introduced in 2.1.1, `ClusterPipeline` is exposed for pipelined commands.

Quickstart

This quickstart demonstrates how to connect to a Redis Cluster using `redis-py-cluster`, set a key-value pair, and retrieve it. It highlights the use of `startup_nodes` for initial cluster discovery and `decode_responses=True` for handling string decoding in Python 3. For multi-key commands, ensure keys hash to the same slot, often achieved using Redis hash tags (e.g., `{user1}name`, `{user1}email`).

import os
from rediscluster import RedisCluster

# Configure startup nodes for the Redis Cluster
# In a real scenario, use actual hostnames/IPs and ports
# For local testing, ensure a Redis Cluster is running on these ports
startup_nodes = [
    {"host": os.environ.get('REDIS_CLUSTER_HOST_1', '127.0.0.1'), "port": os.environ.get('REDIS_CLUSTER_PORT_1', '7000')},
    # {"host": "127.0.0.1", "port": "7001"}, # Add more nodes as needed
]

try:
    # Initialize RedisCluster client with decode_responses=True for Python 3 strings
    rc = RedisCluster(startup_nodes=startup_nodes, decode_responses=True, skip_full_coverage_check=True)

    # Test connection and basic operations
    rc.set("mykey", "Hello, Redis Cluster!")
    value = rc.get("mykey")
    print(f"Retrieved value: {value}")

    # Example of a multi-key operation (keys must hash to the same slot)
    # This example might fail if 'mykey' and 'myotherkey' don't hash to the same slot.
    # In a real cluster, you'd use Redis hash tags {key}. See documentation.
    # For this quickstart, we'll stick to single key for simplicity.
    # rc.mset({"mykey": "val1", "{mykey}other": "val2"})
    # vals = rc.mget(["mykey", "{mykey}other"])
    # print(f"Retrieved multiple values: {vals}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure a Redis Cluster is running and accessible at the specified startup nodes.")
    print("For example, using Docker: docker run -p 7000:7000 -p 7001:7001 -p 7002:7002 -p 7003:7003 -p 7004:7004 -p 7005:7005 --name redis-cluster-node-1 redislabs/redismod")
    print("Then manually create the cluster if not using a managed service.")

view raw JSON →