RedisBackend

A distributed key-value cache backed by a Redis server. Values are serialized with pickle and stored with optional TTL. Supports key prefixing for multi-tenant or namespaced deployments.

Overview

RedisBackend connects to an external Redis server and implements the CacheBackend protocol. It is the right choice when you need a cache shared across multiple processes, containers, or machines.

When to use it:

• Distributed or multi-node deployments
• Microservice architectures where multiple services share cached data
• Production systems that need server-managed eviction policies (e.g., allkeys-lru)
• High-availability setups with Redis Sentinel or Redis Cluster

Tradeoffs:

• Requires a running Redis server (operational overhead).
• Network latency on every operation (typically sub-millisecond on LAN).
• Values are pickled -- only cache data you trust (see security warning below).

Installation

redis is an optional dependency. Install it with the redis extra:

pip

pip install 'omnicache-ai[redis]'

uv

uv add 'omnicache-ai[redis]'

poetry

poetry add omnicache-ai -E redis

Import guard

If the redis package is not installed, instantiating RedisBackend raises an ImportError with installation instructions. The rest of OmniCache-AI continues to work without it.

Usage

Basic key-value caching

from omnicache_ai.backends.redis_backend import RedisBackend

cache = RedisBackend(url="redis://localhost:6379/0")

# Store a value with a 10-minute TTL
cache.set("user:42:session", {"token": "abc123"}, ttl=600)

# Retrieve it
session = cache.get("user:42:session")  # {"token": "abc123"}

# Check existence
cache.exists("user:42:session")  # True

# Delete a single key
cache.delete("user:42:session")

# Close the connection when done
cache.close()

Key prefixing for multi-tenancy

# Tenant-isolated caches sharing the same Redis instance
tenant_a = RedisBackend(url="redis://localhost:6379/0", key_prefix="tenant_a:")
tenant_b = RedisBackend(url="redis://localhost:6379/0", key_prefix="tenant_b:")

tenant_a.set("config", {"theme": "dark"})
tenant_b.set("config", {"theme": "light"})

tenant_a.get("config")  # {"theme": "dark"}
tenant_b.get("config")  # {"theme": "light"}

# clear() only removes keys matching the prefix
tenant_a.clear()  # Deletes only "tenant_a:*" keys

Using with CacheManager

from omnicache_ai import CacheManager, CacheKeyBuilder
from omnicache_ai.backends.redis_backend import RedisBackend

manager = CacheManager(
    backend=RedisBackend(
        url="redis://redis.internal:6379/0",
        key_prefix="myapp:",
    ),
    key_builder=CacheKeyBuilder(namespace="prod"),
)

manager.set("llm:response:hash", b"cached output", ttl=3600)

Connection URL formats

# Standard TCP connection
cache = RedisBackend(url="redis://localhost:6379/0")

# With authentication
cache = RedisBackend(url="redis://:password@redis-host:6379/0")

# With username and password (Redis 6+)
cache = RedisBackend(url="redis://username:password@redis-host:6379/0")

# TLS connection
cache = RedisBackend(url="rediss://redis-host:6380/0")

# Unix socket
cache = RedisBackend(url="unix:///var/run/redis/redis.sock?db=0")

Pickle security

Values are serialized with pickle. Never connect to an untrusted Redis server or load data written by untrusted sources, as unpickling can execute arbitrary code.

Prefix-aware clear

When key_prefix is set, clear() deletes only keys matching {prefix}* using KEYS + DELETE. Without a prefix, it calls FLUSHDB, which removes all keys in the database -- use with care.

No __len__ method

Unlike InMemoryBackend and DiskBackend, RedisBackend does not implement __len__. Use redis-cli DBSIZE or the Redis INFO command to inspect key counts on the server.

API Reference

Constructor

Parameter	Type	Default	Description
url	str	"redis://localhost:6379/0"	Redis connection URL. Supports redis://, rediss:// (TLS), and unix:// schemes.
key_prefix	str	"" (empty)	String prepended to every key. Useful for namespacing or multi-tenant isolation.

Methods

Method	Signature	Returns	Description
get	get(key: str)	Any | None	Retrieve and unpickle the value for key (with prefix applied). Returns None if the key does not exist or has expired.
set	set(key: str, value: Any, ttl: int | None = None)	None	Pickle and store the value. ttl is in seconds, passed to Redis as the EX parameter. None means no expiry.
delete	delete(key: str)	None	Remove a key from Redis. No-op if the key does not exist.
exists	exists(key: str)	bool	Return True if the key exists in Redis (with prefix applied).
clear	clear()	None	If key_prefix is set, delete all keys matching {prefix}*. Otherwise, flush the entire database (FLUSHDB).
close	close()	None	Close the Redis connection.