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.

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",
}