Skip to content
GlitchTip Open source error tracking for your Django apps

Configuration

Basic setup

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "valkey://your-valkey-host:6379/1",
    },
}

URL schemes

Scheme Description
valkey:// Standard Valkey connection
redis:// Standard Redis connection
valkeys:// TLS-encrypted Valkey connection
rediss:// TLS-encrypted Redis connection
sentinel:// Valkey/Redis Sentinel

Options

Options are set in the OPTIONS dictionary:

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "valkey://your-valkey-host:6379/1",
        "OPTIONS": {
            "SERIALIZER": "msgpack",
            "COMPRESS_MIN_LEN": 1024,
        },
    },
}

SERIALIZER

Default: "msgpack"

Choose the serialization format:

  • "msgpack" (default) — Fast and secure. Uses ormsgpack. Cannot execute arbitrary code on deserialization.
  • "pickle" — For projects that need to cache arbitrary Python objects (Django models, custom classes, etc.).

Warning

Pickle can execute arbitrary code on deserialization. Only use it if you trust all data in your cache.

COMPRESS_MIN_LEN

Default: 1024

Values larger than this threshold (in bytes) are automatically compressed with zstd. Set to 0 to disable compression.

"OPTIONS": {
    "COMPRESS_MIN_LEN": 2048,  # compress values larger than 2KB
}

IGNORE_EXCEPTIONS

Default: False

When True, connection failures degrade to cache misses instead of raising: get returns the default, set/delete/touch return False, incr returns 0, get_many returns {}, and set_many reports every key as failed. Use this when a down cache server should degrade gracefully rather than take requests down with it.

"OPTIONS": {
    "IGNORE_EXCEPTIONS": True,
}

Only connection-level errors are swallowed — data errors (e.g. incr on a non-integer value) always raise.

Note

With the default IGNORE_EXCEPTIONS: False, the resilience wrapper is stripped from the hot path at init time by rebinding the undecorated methods onto the cache instance. A side effect: patching methods on the ValkeyCache class (e.g. mock.patch.object(ValkeyCache, "get")) does not affect already-created instances. Patch the instance instead (mock.patch.object(cache, "get")), which works and restores correctly.

CLIENT_SIDE_CACHE

Default: disabled

Opt-in server-assisted client-side caching (requires Valkey/Redis 6.0+ and RESP3). Repeated gets of hot keys are served from an in-process cache that the server invalidates on writes:

"OPTIONS": {
    "CLIENT_SIDE_CACHE": {
        "ENABLED": True,
        "MAX_SIZE": 10_000,   # cached entries (default)
        "TTL": 300,           # seconds (default)
    },
}

cache.get_raw_client().cache_statistics() returns (hits, misses, invalidations) or None when disabled. Not supported in cluster mode.

DRIVER_CLASS

Default: the bundled RustValkeyDriver

Advanced hook for downstream Rust extensions: accepts a driver class or a dotted-path string implementing ValkeyDriverProtocol (see django_vcache/backend.py). Lets an application that ships its own Rust extension route the cache through a driver living in that extension's .so, so the cache shares one tokio runtime and connection with the app's other Rust I/O instead of running two runtimes side by side.

"OPTIONS": {
    "DRIVER_CLASS": "myapp._rust.ValkeyDriver",
}

Pick one driver source per process — the bundled driver and a downstream .so each carry their own tokio runtime, so mixing them runs two runtimes.

CLUSTER_MODE

Default: False

Enable for Valkey/Redis Cluster deployments. The LOCATION should point to one of the cluster's nodes; the driver automatically discovers the rest.

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "valkey://your-cluster-node-1:6379/0",
        "OPTIONS": {
            "CLUSTER_MODE": True,
        },
    },
}

Note

Distributed locking (cache.lock() and cache.alock()) is not supported in cluster mode. Attempting to use these methods will raise NotImplementedError.

Sentinel

Use a sentinel:// URL to connect via Valkey/Redis Sentinel. The URL format is:

sentinel://sentinel-host:26379/master-name/db

Example:

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "sentinel://sentinel-host:26379/mymaster/1",
    },
}

The driver automatically re-discovers the master on failover.

Authentication

Sentinel returns only the master's host and port on discovery — never its credentials — so a password-protected master must be authenticated separately. The URL userinfo carries the master's credentials:

sentinel://:master-password@sentinel-host:26379/master-name/db
sentinel://master-user:master-password@sentinel-host:26379/master-name/db

This covers the common topology of unauthenticated Sentinels in front of a password-protected master. When the Sentinel nodes themselves require authentication, supply their credentials separately with the sentinel_username / sentinel_password query parameters — these are distinct from the master credentials:

sentinel://:master-password@sentinel-host:26379/master-name/db?sentinel_password=sentinel-password

Credentials in the URL must be percent-encoded if they contain reserved characters (@, :, /, etc.).

IPv6 Sentinel hosts must be bracketed:

sentinel://[2001:db8::1]:26379,[2001:db8::2]:26379/master-name/db

TLS certificates

Use a valkeys:// or rediss:// URL scheme with ssl_ca_certs to connect over TLS:

CACHES = {
    "default": {
        "BACKEND": "django_vcache.backend.ValkeyCache",
        "LOCATION": "valkeys://your-valkey-host:6380/1",
        "OPTIONS": {
            "ssl_ca_certs": "/path/to/ca.crt",
            "ssl_certfile": "/path/to/client.crt",  # optional, for mTLS
            "ssl_keyfile": "/path/to/client.key",    # optional, for mTLS
        },
    },
}

ssl_ca_certs

Path to a PEM file containing the CA certificate used to verify the server's certificate. This is required for TLS connections — mount your CA certificate into the container and reference it here.

ssl_certfile / ssl_keyfile

Paths to PEM files for mutual TLS (mTLS) client authentication. Both must be provided together. Only needed when the server requires client certificate authentication.

ssl_cert_reqs

Default: "required"

Set to "none" to skip certificate verification entirely (uses TLS encryption without validating the server's certificate). This is useful for self-signed certificates when you don't have access to the CA cert:

"OPTIONS": {
    "ssl_cert_reqs": "none",
}

Environment variables

VCACHE_TOKIO_WORKER_THREADS

Default: 1

Worker-thread count for the driver's tokio runtime. One thread is optimal for the driver's own workload (I/O-bound tasks on a multiplexed connection); raise it only if you push additional CPU-heavy work onto this runtime from Rust.

Applies only to vcache's own runtime. When a downstream extension installs a runtime provider (set_runtime_provider, see DRIVER_CLASS), that shared runtime's own configuration governs sizing — for combined workloads (cache + database pool + app I/O on one pool) a larger, CPU-count-sized pool is the sensible default, and this variable has no effect.

VCACHE_MAX_IDLE_BLOCKING_CONNS

Default: 4

Each in-flight blocking operation (BLMOVE/BLMPOP, used by task queues such as django-vtasks) holds a dedicated connection, checked out of an idle pool. This caps how many idle connections are retained for reuse. If you run more than this many concurrent blocking consumers per process, raise it to match, or completions beyond the cap will drop and recreate connections on every cycle.