Changelog

Requirements

redis-py >= 2.4.5 redis >= 2.4 hiredis python >= 2.5

1. Run pip install django-redis-cache.

2. Modify your Django settings to use redis_cache.

# When using TCP connections
CACHES = {
    'default': {
        'BACKEND': 'redis_cache.RedisCache',
        'LOCATION': [
            '<host>:<port>',
            '<host>:<port>',
            '<host>:<port>',
        ],
        'OPTIONS': {
            'DB': 1,
            'PASSWORD': 'yadayada',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
            'CONNECTION_POOL_CLASS': 'redis.BlockingConnectionPool',
            'CONNECTION_POOL_CLASS_KWARGS': {
                'max_connections': 50,
                'timeout': 20,
            }
            'MAX_CONNECTIONS': 1000,
            'PICKLE_VERSION': -1,
        },
    },
}

# When using unix domain sockets
# Note: ``LOCATION`` needs to be the same as the ``unixsocket`` setting
# in your redis.conf
CACHES = {
    'default': {
        'BACKEND': 'redis_cache.RedisCache',
        'LOCATION': '/path/to/socket/file',
        'OPTIONS': {
            'DB': 1,
            'PASSWORD': 'yadayada',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
            'PICKLE_VERSION': 2,
        },
    },
}

# For Master-Slave Setup, specify the host:port of the master
# redis-server instance.
CACHES = {
    'default': {
        'BACKEND': 'redis_cache.RedisCache',
        'LOCATION': [
            '<host>:<port>',
            '<host>:<port>',
            '<host>:<port>',
        ],
        'OPTIONS': {
            'DB': 1,
            'PASSWORD': 'yadayada',
            'PARSER_CLASS': 'redis.connection.HiredisParser',
            'PICKLE_VERSION': 2,
            'MASTER_CACHE': '<master host>:<master port>',
        },
    },
}

Usage

django-redis-cache shares the same API as django’s built-in cache backends, with a few exceptions.

cache.delete_pattern

Delete keys using glob-style pattern.

example:

>>> from news.models import Story
>>>
>>> most_viewed = Story.objects.most_viewed()
>>> highest_rated = Story.objects.highest_rated()
>>> cache.set('news.stories.most_viewed', most_viewed)
>>> cache.set('news.stories.highest_rated', highest_rated)
>>> data = cache.get_many(['news.stories.highest_rated', 'news.stories.most_viewed'])
>>> len(data)
2
>>> cache.delete_pattern('news.stores.*')
>>> data = cache.get_many(['news.stories.highest_rated', 'news.stories.most_viewed'])
>>> len(data)
0

cache.clear

Same as django’s cache.clear, except that you can optionally specify a version and all keys with that version will be deleted. If no version is provided, all keys are flushed from the cache.

cache.reinsert_keys

This helper method retrieves all keys and inserts them back into the cache. This is useful when changing the pickle protocol number of all the cache entries. As of django-redis-cache < 1.0, all cache entries were pickled using version 0. To reduce the memory footprint of the redis-server, simply run this method to upgrade cache entries to the latest protocol.

Thundering Herd Protection

A common problem with caching is that you can sometimes get into a situation where you have a value that takes a long time to compute or retrieve, but have clients accessing it a lot. For example, if you wanted to retrieve the latest tweets from the twitter api, you probably want to cache the response for a number of minutes so you don’t exceed your rate limit. However, when the cache entry expires you can have mulitple clients that see there is no entry and try to simultaneously fetch the latest results from the api.

The way to get around this problem you pass in a callable and timeout to get_or_set, which will check the cache to see if you need to compute the value. If it does, then the cache sets a placeholder that tells future clients to serve data from the stale cache until the new value is created.

Example:

tweets = cache.get_or_set('tweets', twitter.get_newest, timeout=300)

Running Tests

make test