Redis Sentinel URL

1.0.1 · active · verified Thu Apr 16

Redis-Sentinel-Url is a Python library that provides a parser and connection factory for Redis connections, specifically supporting both standard `redis://` and the custom `redis+sentinel://` URL schemes. It allows applications to connect to Redis instances via Sentinel for high availability. The library is currently at version 1.0.1, with its last major update addressing password handling, and it appears to be in maintenance mode, offering stable functionality rather than active feature development.

Common errors

```
redis.sentinel.MasterNotFoundError: No master found for 'mymaster'
```
cause The Redis Sentinel cluster could not identify an active master for the specified `service_name` (e.g., 'mymaster'), or the Sentinel instances themselves are unreachable/misconfigured.

fix Verify that your Sentinel instances are running and healthy on the specified `host:port`. Check the `service_name` in your connection URL against your `sentinel.conf` configuration. Ensure network connectivity and correct firewall rules to the Sentinel ports (default 26379).
```
redis.exceptions.ConnectionError: Error 111 connecting to localhost:26379. Connection refused.
```
cause The Python application was unable to establish a TCP connection to the specified Redis Sentinel host and port. This is often a network or server availability issue.

fix Check if the Sentinel process is running on `localhost:26379`. Verify network connectivity between your application and the Sentinel server. Ensure no firewall rules are blocking the connection on port 26379.
```
redis.exceptions.AuthenticationError: Authentication required.
```
cause The Redis master or one of the Sentinel instances requires a password, but none was provided in the connection URL, or an incorrect password was supplied.

fix Include the correct password(s) in your `redis+sentinel://` URL. For the Redis master, use `?password=your_redis_master_password`. For Sentinel authentication (Redis 6.2+), use `?sentinel_password=your_sentinel_password`.

Warnings

breaking Password handling for Redis Sentinel connections was fixed in version 1.0.1. Prior versions (specifically 1.0.0) might have silently failed to pass passwords correctly, leading to authentication errors or unexpected behavior when connecting to password-protected Redis instances or Sentinels.
Fix: Upgrade to version 1.0.1 or higher: `pip install --upgrade Redis-Sentinel-Url`. Ensure your URL includes passwords for both the Redis master (as `password=`) and Sentinel instances (as `sentinel_password=`) if applicable.
gotcha The library relies on the `redis-py` package, and its internal implementation notes indicate a requirement for `redis-py` version 2.9.0 or newer. Using older versions of `redis-py` may lead to compatibility issues or unexpected behavior.
Fix: Ensure `redis-py` is installed and is version 2.9.0 or higher. You can check with `pip show redis` and upgrade with `pip install --upgrade redis`.
gotcha Incorrect configuration of the `redis+sentinel://` URL, especially the `service_name` (often 'mymaster') or sentinel host:port pairs, will prevent successful connection. The library will accurately relay connection errors from the underlying `redis-py` client.
Fix: Double-check your `redis+sentinel://` URL for typos. Verify that the `service_name` matches your Redis Sentinel configuration exactly and that all listed sentinel `host:port` pairs are correct and accessible from the application. Consult your Redis Sentinel configuration (`sentinel.conf`) for details.

Install

pip install Redis-Sentinel-Url Install with pip

Imports

connect

wrong:

import redis_sentinel_url; redis_sentinel_url.create_connection()

correct:

from redis_sentinel_url import connect

The primary connection factory is 'connect', not 'create_connection'.

Quickstart

This quickstart demonstrates how to use `redis_sentinel_url.connect()` to establish connections. It attempts to connect using a `redis+sentinel://` URL, retrieving both the Sentinel client and a `StrictRedis` client for the master. It also illustrates setting and getting a key to confirm functionality. Ensure your `REDIS_SENTINEL_URL` environment variable is correctly configured with your Redis Sentinel setup.

import os
from redis_sentinel_url import connect

# Example Sentinel URL. Replace with your actual Sentinel configuration.
# The 'mymaster' is the service name configured in Redis Sentinel.
# Use os.environ.get for sensitive info like passwords.
REDIS_SENTINEL_URL = os.environ.get(
    'REDIS_SENTINEL_URL',
    'redis+sentinel://localhost:26379,otherhost:26479/mymaster/0?password=your_redis_master_password&sentinel_password=your_sentinel_password'
)

try:
    # Connect returns a (sentinel_client, redis_client) tuple
    sentinel_client, redis_client = connect(REDIS_SENTINEL_URL)

    if sentinel_client:
        print(f"Connected to Redis Sentinel service: {sentinel_client.service_name}")
        # You can get the current master and use it
        master = sentinel_client.master_for(sentinel_client.service_name)
        print(f"Master host: {master.connection_pool.connection_kwargs.get('host')}")
        print(f"Master port: {master.connection_pool.connection_kwargs.get('port')}")
        master.set('mykey', 'hello from sentinel')
        print(f"Set 'mykey': {master.get('mykey').decode('utf-8')}")

    if redis_client:
        # If connecting directly to Redis without Sentinel, redis_client will be present and sentinel_client will be None
        print("Connected directly to Redis.")
        redis_client.set('anotherkey', 'hello from direct redis')
        print(f"Set 'anotherkey': {redis_client.get('anotherkey').decode('utf-8')}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →