# Cache

Psono uses a cache for rate limiting and can also cache application data to reduce database queries. A shared Redis cache keeps cache entries and rate limits consistent across server processes and instances. You can connect directly to a standalone Redis server or use Redis Sentinel to discover a highly available Redis primary.

# General settings

Configure the cache in your server's settings.yaml and restart the server after changing these settings.

Setting Default Description
CACHE_ENABLE False Enables caching of application data. Configure a shared cache before enabling this in production.
CACHE_REDIS False Selects Redis as the cache backend, including for rate limiting.
CACHE_REDIS_LOCATION redis://localhost:6379/0 Redis connection URL, or a monitored service URL in Sentinel mode.
THROTTLING True Enables rate limiting. Setting this to False overrides the configured backend with a dummy cache and disables caching too.

CACHE_ENABLE and rate limiting are independent: leaving CACHE_ENABLE: False does not disable rate limiting. Without a configured shared backend, Django uses a local in-memory cache, so rate limits are per process rather than shared across all server instances.

# Standalone Redis

To connect directly to Redis, use its hostname, port, and database in the URL:

CACHE_ENABLE: True
CACHE_REDIS: True
CACHE_REDIS_LOCATION: 'redis://redis.example.com:6379/13'

Sentinel mode defaults to disabled. If switching from Sentinel back to standalone Redis, also set CACHE_REDIS_SENTINEL: False.

The URL path selects the Redis database. Choose a dedicated database, for example 13, to avoid sharing it with other applications. The database must exist within the range configured by Redis; its default configuration provides databases 0 through 15.

If Redis requires authentication, include URL-encoded credentials in the URL:

# Password-only authentication
CACHE_REDIS_LOCATION: 'redis://:redis-password@redis.example.com:6379/13'

# Username and password (Redis ACL authentication)
# CACHE_REDIS_LOCATION: 'redis://redis-user:redis-password@redis.example.com:6379/13'

For a TLS-enabled standalone Redis server, use the rediss:// scheme:

CACHE_REDIS_LOCATION: 'rediss://redis-user:redis-password@redis.example.com:6379/13'

# Redis Sentinel

Sentinel discovers the current Redis primary and follows primary changes after failover. Both cache reads and writes use the primary to avoid stale reads from replicas. Psono connects to an existing Sentinel-managed Redis deployment; it does not configure the Redis servers or Sentinel instances.

Use the monitored service name in the URL and list the Sentinel endpoints:

CACHE_ENABLE: True
CACHE_REDIS: True
CACHE_REDIS_SENTINEL: True
CACHE_REDIS_LOCATION: 'redis://mymaster/13'
CACHE_REDIS_SENTINELS:
  - ['sentinel-1', 26379]
  - ['sentinel-2', 26379]
  - ['sentinel-3', 26379]
  • CACHE_REDIS_SENTINEL enables Sentinel discovery and defaults to False. It requires CACHE_REDIS: True.
  • CACHE_REDIS_LOCATION uses the monitored service name as its hostname, such as mymaster, rather than a Redis server's address. The URL path selects the Redis database, here 13. The service name must match your Sentinel configuration.
  • CACHE_REDIS_SENTINELS is the list of Sentinel hostname and port pairs. It is required when Sentinel mode is enabled. Psono must also be able to reach the Redis addresses returned by Sentinel.

# Authentication

If Redis requires authentication, include its credentials in the location URL:

CACHE_REDIS_LOCATION: 'redis://redis-user:redis-password@mymaster/13'

For password-only authentication, use redis://:redis-password@mymaster/13. URL-encode any special characters in the username or password.

Sentinel authentication is independent of Redis authentication. Configure credentials and other redis-py Sentinel connection arguments with the optional CACHE_REDIS_SENTINEL_KWARGS dictionary, which defaults to {}:

CACHE_REDIS_SENTINEL_KWARGS:
  username: 'sentinel-user'
  password: 'sentinel-password'
  socket_connect_timeout: 5
  socket_timeout: 5

Omit username for password-only Sentinel authentication. These connection arguments apply to Sentinel connections, not to connections to the Redis primary.

# Environment variables

All settings can also be supplied using the PSONO_ prefix. For standalone Redis:

export PSONO_CACHE_ENABLE=True
export PSONO_CACHE_REDIS=True
export PSONO_CACHE_REDIS_LOCATION='redis://redis.example.com:6379/13'

For Sentinel, add the following settings instead of the standalone location. Lists and dictionaries must be JSON-encoded:

export PSONO_CACHE_ENABLE=True
export PSONO_CACHE_REDIS=True
export PSONO_CACHE_REDIS_SENTINEL=True
export PSONO_CACHE_REDIS_LOCATION='redis://mymaster/13'
export PSONO_CACHE_REDIS_SENTINELS='[["sentinel-1",26379],["sentinel-2",26379],["sentinel-3",26379]]'
export PSONO_CACHE_REDIS_SENTINEL_KWARGS='{"password":"sentinel-password","socket_connect_timeout":5,"socket_timeout":5}'

See the environment variable reference for details on the individual variables.