coredis: Async Redis Client

6.5.1 · active · verified Sat Apr 11

coredis is a fast, async, and fully-typed Redis client for Python, offering support for Redis Cluster, Sentinel, and various Redis modules. It is built with structured concurrency using `anyio`, supporting both `asyncio` and `trio`. The library is actively maintained with frequent releases, often multiple times a month for bug fixes and minor features, with major architectural rewrites released periodically. The current version is 6.5.1.

Warnings

breaking Version 6.0.0 introduced a major architectural rewrite, migrating the entire library to `anyio` for structured concurrency, supporting both `asyncio` and `trio`. This requires significant changes to existing applications built on 5.x, especially regarding connection management and asynchronous patterns.
Fix: Refer to the official 'Migrating from 5.x to 6.0' guide in the coredis documentation for detailed upgrade instructions. Update your async code to follow `anyio`'s structured concurrency patterns, typically using `async with client:` for resource management.
breaking Several submodules for application patterns (e.g., Pub/Sub, Pipeline, Stream, Cache, Lock) were moved from `coredis.commands.*` or directly under `coredis` to `coredis.patterns` in version 6.0.0rc3.
Fix: Update your import statements to reflect the new `coredis.patterns` module path. For example, `from coredis.pipeline import Pipeline` becomes `from coredis.patterns import Pipeline`.
gotcha Version 6.5.0 introduced a regression where batch request cancellations were suppressed, potentially leading to unexpected behavior in certain scenarios.
Fix: Upgrade to coredis version 6.5.1 or newer to fix this regression.
gotcha In versions prior to 6.2.0, if `__aenter__` failed during connection pool initialization, the connection pool could become unusable as its counter would be stuck.
Fix: Upgrade to coredis version 6.2.0 or newer to ensure proper connection pool task group cleanup and recovery from initialization errors.
gotcha In versions prior to 6.1.0, there was an incorrect initialization of the connection capacity limiter, leading to a module-level shared capacity limiter instead of an instance-specific one.
Fix: Upgrade to coredis version 6.1.0 or newer to resolve this issue and ensure correct connection capacity limiting.
gotcha In versions prior to 5.7.0, username and password provided as keyword arguments to `from_url` might not have been correctly used if no credentials were found within the URL string itself.
Fix: Upgrade to coredis version 5.7.0 or newer. Ensure the URL contains credentials (e.g., `redis://user:password@host:port`) or pass them explicitly and correctly.

Install

pip install coredis Install coredis

Imports

Redis
```
from coredis import Redis
```
RedisCluster
```
from coredis import RedisCluster
```
Sentinel
```
from coredis import Sentinel
```
TCPLocation
```
from coredis.connection import TCPLocation
```
Used for specifying startup nodes for RedisCluster.
Pipeline, PubSub, Lock, Streams, Cache
```
from coredis.patterns import Pipeline, PubSub
```
Prior to v6.0.0rc3, these patterns were directly under `coredis` or `coredis.commands`. They were moved to `coredis.patterns`.

Quickstart

This quickstart demonstrates connecting to a single Redis instance, performing basic `SET`, `GET`, `INCR` operations, and using a command pipeline. It leverages `anyio.run` to execute the asynchronous code and uses `os.environ.get` for flexible Redis URL configuration.

import anyio
import coredis
import os

async def main() -> None:
    # Connect to Redis. Use a URL from an environment variable or default to localhost
    redis_url = os.environ.get('COREDIS_URL', 'redis://localhost:6379/0')
    # Optionally, decode responses to get Python strings instead of bytes
    client = coredis.Redis.from_url(redis_url, decode_responses=True)

    async with client:
        # Clear the database (use with caution in production!)
        print(f"Flushing database...")
        await client.flushdb()

        # Basic SET and GET operations
        print(f"Setting 'mykey' to 'hello'")
        await client.set("mykey", "hello")
        value = await client.get("mykey")
        print(f"Value of 'mykey': {value}")
        assert value == "hello"

        # Increment a numerical value
        print(f"Incrementing 'counter'")
        await client.set("counter", 1)
        assert await client.incr("counter") == 2
        print(f"Value of 'counter' after increment: {await client.get('counter')}")

        # Using a pipeline for multiple commands in a single round trip
        print("Running a pipeline...")
        async with client.pipeline() as pipeline:
            pipeline.incr("pipeline_counter")
            pipeline.get("pipeline_counter")
            pipeline.delete(["pipeline_counter"])
            results = await pipeline.execute()
            print(f"Pipeline results: {results}") # Expected: [1, '1', 1] (if decode_responses=True)

if __name__ == "__main__":
    # coredis uses anyio, supporting asyncio and trio. Specify your preferred backend.
    anyio.run(main, backend="asyncio")

view raw JSON →