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
}

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.