Installation

Setup

Add cacheops to your INSTALLED_APPS before any apps that use it.

Setup redis connection and enable caching for desired models:

CACHEOPS_REDIS={'host':'localhost',# redis-server is on same machine'port':6379,# default redis port'db':1,# SELECT non-default redis database# using separate redis db or redis instance# is highly recommended'socket_timeout':3,}CACHEOPS={# Automatically cache any User.objects.get() calls for 15 minutes# This includes request.user or post.author access,# where Post.author is a foreign key to auth.User'auth.user':('get',60*15),# Automatically cache all gets, queryset fetches and counts# to other django.contrib.auth models for an hour'auth.*':('all',60*60),# Enable manual caching on all news models with default timeout of an hour# Use News.objects.cache().get(...)# or Tags.objects.filter(...).order_by(...).cache()# to cache particular ORM request.# Invalidation is still automatic'news.*':('just_enable',60*60),# Automatically cache count requests for all other models for 15 min'*.*':('count',60*15),}

Additionally, you can tell cacheops to degrade gracefully on redis fail with:

CACHEOPS_DEGRADE_ON_FAILURE=True

There is also a possibility to make all cacheops methods and decorators no-op, e.g. for testing:

CACHEOPS_FAKE=True

Usage

Automatic caching.

It’s automatic you just need to set it up.

Manual caching.

You can force any queryset to use cache by calling it’s .cache() method:

Article.objects.filter(tag=2).cache()

Here you can specify which ops should be cached for queryset, for example, this code:

will cache count call in Paginator but not later articles fetch.
There are three possible actions - get, fetch and count. You can
pass any subset of this ops to .cache() method even empty - to turn off caching.
There is, however, a shortcut for it:

qs=Article.objects.filter(visible=True).nocache()qs1=qs.filter(tag=2)# hits databaseqs2=qs.filter(category=3)# hits it once more

It is useful when you want to disable automatic caching on particular queryset.

You can also override default timeout for particular queryset with .cache(timeout=...)
or make queryset only write cache, but don’t try to fetch it with .cache(write_only=True).

Function caching.

You can cache and invalidate result of a function the same way as a queryset.
Cache of the next function will be invalidated on any Article change, addition
or deletion:

We added extra here to make different keys for calls with same category but different
count. Cache key will also depend on function arguments, so we could just pass count as
an argument to inner function. We also omitted timeout here, so a default for the model
will be used.

Another possibility is to make function cache invalidate on changes to any one of several models:

You can pass timeout, extra and several samples the same way as to @cached_as().

Invalidation

Cacheops uses both time and event-driven invalidation. The event-driven one
listens on model signals and invalidates appropriate caches on Model.save(), .delete()
and m2m changes.

Invalidation tries to be granular which means it won’t invalidate a queryset
that cannot be influenced by added/updated/deleted object judging by query
conditions. Most of the time this will do what you want, if it won’t you can use
one of the following:

It have several improvements upon django built-in file cache, both about high load.
First, it is safe against concurrent writes. Second, it’s invalidation is done as separate task,
you’ll need to call this from crontab for that to work:

/path/manage.py cleanfilecache

Django templates integration

Cacheops provides tags to cache template fragments for Django 1.4+. They mimic @cached_as
and @cached decorators, however, they require explicit naming of each fragment:

CAVEATS

Conditions other than __exact, __in and __isnull=True don’t make invalidation
more granular.

Conditions on TextFields, FileFields and BinaryFields don’t make it either.
One should not test on their equality anyway.

Update of “selected_related” object does not invalidate cache for queryset.

Mass updates don’t trigger invalidation.

ORDER BY and LIMIT/OFFSET don’t affect invalidation.

Doesn’t work with RawQuerySet.

Conditions on subqueries don’t affect invalidation.

Doesn’t work right with multi-table inheritance.

Aggregates are not implemented yet.

Here 1, 2, 3, 5 are part of design compromise, trying to solve them will make
things complicated and slow. 7 can be implemented if needed, but it’s
probably counter-productive since one can just break queries into simpler ones,
which cache better. 4 is a deliberate choice, making it “right” will flush
cache too much when update conditions are orthogonal to most queries conditions.
6 can be cached as SomeModel.objects.all() but @cached_as() someway covers that
and is more flexible. 8 is postponed until it will gain more interest or a champion willing to
implement it emerge.

Performance tips

Here come some performance tips to make cacheops and Django ORM faster.

When you use cache you pickle and unpickle lots of django model instances, which could be slow. You can optimize django models serialization with django-pickling.

Constructing querysets is rather slow in django, mainly because most of QuerySet methods clone self, then change it and return a clone. Original queryset is usually thrown away. Cacheops adds .inplace() method, which makes queryset mutating, preventing useless cloning:

Note that this is a micro-optimization technique. Using it is desirable in most hot places, but not everywhere.

More to 2, there is a bug in django 1.4-,
which sometimes makes queryset cloning very slow. You can use any patch from this ticket to fix it.

Use template fragment caching when possible, it’s way more fast because you don’t need to generate anything. Also pickling/unpickling a string is much faster than list of model instances.

Run separate redis instance for cache with disabled persistence. You can manually call SAVE or BGSAVE to stay hot upon server restart.

If you filter queryset on many different or complex conditions cache could degrade performance (comparing to uncached db calls) in consequence of frequent cache misses. Disable cache in such cases entirely or on some heuristics which detect if this request would be probably hit. E.g. enable cache if only some primary fields are used in filter.

Caching querysets with large amount of filters also slows down all subsequent invalidation on that model. You can disable caching if more than some amount of fields is used in filter simultaneously.

Writing a test

Writing a test for an issue you are having can speed up its resolution a lot. Here is how you do that. I am supposing you have some application code causing it.