Memcached¶

The fastest, most efficient type of cache supported natively by Django, Memcached__ is an entirely memory-based cache server, originally developed to handle high loads at LiveJournal.com and subsequently open-sourced by Danga Interactive. It is used by sites such as Facebook and Wikipedia to reduce database access and dramatically increase site performance.

Memcached работает как демон и захватывает определённый объём оперативной памяти. Его задачей является представление быстрого интерфейса для добавления, получения и удаления определённых данных в кэше. Все данные хранятся прямо в оперативной памяти, таким образом нет никакой дополнительной нагрузки на базу данных или файловую систему.

After installing Memcached itself, you’ll need to install a Memcached binding. There are several Python Memcached bindings available; the two most common are python-memcached and pylibmc.

Для использования Memcached с Django:

• Set BACKEND to django.core.cache.backends.memcached.MemcachedCache or django.core.cache.backends.memcached.PyLibMCCache (depending on your chosen memcached binding)

• Определите для LOCATION значение ip:port (где ip — это IP адрес, на котором работает демон Memcached, port — его порт) или unix:path (где path является путём к файлу-сокету Memcached).

In this example, Memcached is running on localhost (127.0.0.1) port 11211, using the python-memcached binding:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '127.0.0.1:11211',
    }
}

In this example, Memcached is available through a local Unix socket file /tmp/memcached.sock using the python-memcached binding:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': 'unix:/tmp/memcached.sock',
    }
}

When using the pylibmc binding, do not include the unix:/ prefix:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.PyLibMCCache',
        'LOCATION': '/tmp/memcached.sock',
    }
}

Одной из замечательных особенностей Memcached является возможность распределять кэш по нескольким серверам. Это означает, что вы можете запустить демоны Memcached на нескольких машинах и программа будет рассматривать эту группу машин как единый кэш, без необходимости копирования всех значений кэша на каждую машину. Для того, чтобы воспользоваться этой особенностью, укажите адреса всех машин в LOCATION, в виде списка или строки, разделённой запятыми.

В данном примере, кэш распределён по экземплярам Memcached, работающим на IP адресах 172.19.26.240 и 172.19.26.242, на порту 11211 оба:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': [
            '172.19.26.240:11211',
            '172.19.26.242:11211',
        ]
    }
}

В следующем примере, кэш распределён по экземплярам Memcached, работающим на IP адресах 172.19.26.240 (порт 11211), 172.19.26.242 (порт 11212) и на 172.19.26.244 (порт 11213):

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': [
            '172.19.26.240:11211',
            '172.19.26.242:11212',
            '172.19.26.244:11213',
        ]
    }
}

В конце рассказа о Memcached следует сказать, что этот тип кэша имеет один недостаток: Кэш располагается в оперативной памяти и уничтожается при сбое сервера. Очевидно, что оперативная память не предназначена для постоянного хранения информации, поэтому не следует на неё рассчитывать в этом смысле. Несомненно, ни один из модулей кэширования не должен использоваться как постоянное хранилище — они предназначены для кэширования, не для хранения — мы особенно это отмечаем для данного типа кэша.

Кэширование в базу данных¶

Кэширование в базу данных отлично работает в случае, если у вас есть быстрый сервер баз данных с поддержкой индексирования.

Для использования таблицы базы данных в качестве бэкэнда кэша:

• Установите BACKEND в django.core.cache.backends.db.DatabaseCache

• Установите LOCATION в tablename, имя таблицы базы данных. Это имя может быть любым, пока оно не противоречит правилам именования таблиц в вашей базе данных и не занято другой таблицей.

В данном примере, именем таблицы для кэша будет my_cache_table:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
        'LOCATION': 'my_cache_table',
    }
}

python manage.py createcachetable

class CacheRouter:
    """A router to control all database cache operations"""

    def db_for_read(self, model, **hints):
        "All cache read operations go to the replica"
        if model._meta.app_label == 'django_cache':
            return 'cache_replica'
        return None

    def db_for_write(self, model, **hints):
        "All cache write operations go to primary"
        if model._meta.app_label == 'django_cache':
            return 'cache_primary'
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        "Only install the cache model on primary"
        if app_label == 'django_cache':
            return db == 'cache_primary'
        return None

Кэширование на файловую систему¶

Файловый бэкэнд сериализует и сохраняет каждое закэшированное значение в отдельном файле. Для использования этого бэкэнда, установите BACKEND в "django.core.cache.backends.filebased.FileBasedCache", а для LOCATION укажите подходящий каталог. Например, для хранения закэшированных данных в /var/tmp/django_cache, используйте такую настройку:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
    }
}

Если вы используете Windows, то подставьте букву диска в начало пути, вот так:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': 'c:/foo/bar',
    }
}

Путь до каталога должен быть абсолютным, т.е. он должен начинаться от корня файловой системы. Завершающий слэш не имеет значения.

Убедитесь, что каталог, на который указывает этот параметр, либо существует и доступен для чтения и записи, либо что он может быть создан пользователем системы, под которым работает ваш веб-сервер. Продолжая приведенный выше пример, если ваш сервер работает от имени пользователя «apache», убедитесь, что каталог «/var/tmp/django_cache» существует и доступен для чтения и записи пользователю «apache», или что он может быть создан пользователем «apache».

Кэширование в оперативной памяти¶

Это стандартный кэш, который применяется, если другой не определён в вашем файле конфигурации. Если вам требуется высокая скорость работы кэша, но у вас нет возможности развернуть Memcached, рассмотрите вариант использования кэша в оперативной памяти. Этот кэш по-процессный (см. далее) и потокобезопасный. Для его использования надо параметру конфигурации BACKEND присвоить значение "django.core.cache.backends.locmem.LocMemCache". Например:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
        'LOCATION': 'unique-snowflake',
    }
}

Параметр конфигурации LOCATION используется для идентификации отдельных хранилищ в памяти. Если у вас только один такой кэш, то вы можете пропустить этот параметр. Однако, в случае нескольких кэшей, вам потребуется назначить имя хотя бы для одного из них, для их различия.

Кэш использует стратегию отбраковки наименее недавно использованных данных (LRU).

Обратите внимание, что каждый процесс будет иметь свой собственный экземпляр частного кэша, что означает, что межпроцессное кэширование невозможно. Это также означает, что кэш локальной памяти не особенно эффективен с точки зрения использования памяти, поэтому он, вероятно, не является хорошим выбором для производственных сред. Это приятно для развития.

Псевдокэширование (для разработки)¶

Наконец, Django поставляется с «псевдо» кэшем, который не выполняет собственно кэширование. Он просто реализует интерфейс кэша, не делая больше ничего.

Он полезен в случае, когда у вас есть боевой сайт , который плотно использует кэширование в различных местах, а также окружение разработки или тестирование, где кэшировать ничего не надо. Для активации псевдо кэширования, установите BACKEND:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.dummy.DummyCache',
    }
}

Использование собственного модуля кэширования¶

Несмотря на то, что Django предоставляет ряд модулей кэширования, вам может потребоваться использовать свой кэширующий модуль. Для подключения внешнего кэширующего модуля используйте путь до него в качестве значения BACKEND параметра конфигурации CACHES, вот так:

CACHES = {
    'default': {
        'BACKEND': 'path.to.backend',
    }
}

If you’re building your own backend, you can use the standard cache backends as reference implementations. You’ll find the code in the django/core/cache/backends/ directory of the Django source.

Следует отметить, если нет важной причины для использования собственного кэширующего модуля, вы должны использовать кэширующие модули, поставляемые с Django. Они протестированы и просты в использовании.

Параметры кэша¶

После определения типа кэша и имени для каждого из них, для каждого модуля можно указать дополнительные аргументы для управления поведением кэша. Эти аргументы представляются в виде дополнительных ключей в параметре конфигурации CACHES. Приведём список допустимых аргументов:

• TIMEOUT: время устаревания кэша по умолчанию, в секундах. По умолчанию 300 секунд (5 минут). Вы можете установить TIMEOUT в None, тогда кэш никогда не устареет. Если указать 0, все ключи будут сразу устаревать (таким образом можно заставить «не кэшировать»).

• OPTIONS: Любая опция, которая должна быть передана модулю. Список допустимых опций варьируется от модуля к модулю и передается непосредственно в библиотеку для кэширования.

  Модули кэширования, которые реализуют собственную стратегию очистки (т.е., модули locmem, filesystem и database) учитывают следующие опции:

  • MAX_ENTRIES: максимальное количество элементов в кэше перед началом удаления старых значений. Обычно, 300 элементов.

  • CULL_FREQUENCY: Часть элементов, которые надо удалить при достижении MAX_ENTRIES. Обычное соотношение — 1/CULL_FREQUENCY, таким образом, надо установить CULL_FREQUENCY в 2, чтобы удалять половину значений кэша при достижении MAX_ENTRIES. Аргумент должен быть целым числом и по умолчанию равен 3.

    Значение 0 для CULL_FREQUENCY означает, что весь кэш должен быть сброшен при достижении MAX_ENTRIES. Это делает очистку значительно быстрее для определенных бэкендов(в частности database) ценой увеличения промахов кэша.

  Memcached backends pass the contents of OPTIONS as keyword arguments to the client constructors, allowing for more advanced control of client behavior. For example usage, see below.

• KEY_PREFIX: Строка, которая автоматически включается (предваряет, по умолчанию) во все ключи кэша, используемые сервером Django.

  Обратитесь к документации на кэш для подробностей.

• VERSION: Номер версии про умолчанию для ключей кэша, созданных сервером Django.

  Обратитесь к документации на кэш для подробностей.

• KEY_FUNCTION Строка, содержащая путь до функции, которая определяет правила объединения префикса, версии и ключа в итоговый ключ кэша.

  Обратитесь к документации на кэш для подробностей.

В этом примере, модуль кэширования на файловую систему настроен на таймаут в 60 секунд и ёмкость в 1000 элементов:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.filebased.FileBasedCache',
        'LOCATION': '/var/tmp/django_cache',
        'TIMEOUT': 60,
        'OPTIONS': {
            'MAX_ENTRIES': 1000
        }
    }
}

Here’s an example configuration for a python-memcached based backend with an object size limit of 2MB:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '127.0.0.1:11211',
        'OPTIONS': {
            'server_max_value_length': 1024 * 1024 * 2,
        }
    }
}

Вот пример конфигурации для бэкенда на основе pylibmc, который включает двоичный протокол, аутентификацию SASL и режим поведения ketama:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.PyLibMCCache',
        'LOCATION': '127.0.0.1:11211',
        'OPTIONS': {
            'binary': True,
            'username': 'user',
            'password': 'pass',
            'behaviors': {
                'ketama': True,
            }
        }
    }
}

Определение кэша уровня представления в URLconf¶

Примеры из предыдущей секции содержат жёсткое определение кэширования представления, так как декоратор cache_page меняет поведение функции my_view. Такое подход связывает ваше представление с системой кэширования, что не всегда подходит по нескольким причинам. Например, вы можете пожелать распространять представления людям, которые захотят использовать их вне системы кэширования. Решением такой проблемы является указание кэширования в URLconf для каждого представления, а не у каждой функции.

Сделать это несложно: просто оберните функцию представления с помощью cache_page, при обращении к ней в URLconf. Вот так выглядела старая конфигурация URL:

urlpatterns = [
    path('foo/<int:code>/', my_view),
]

Вот так должно быть в случае, когда my_view обёрнута с помощью cache_page:

from django.views.decorators.cache import cache_page

urlpatterns = [
    path('foo/<int:code>/', cache_page(60 * 15)(my_view)),
]

Доступ к кэшу¶

django.core.cache.caches¶

Вы можете иметь доступ к кэшам, определённым в параметре конфигурации CACHES, через словарно-подобный объект django.core.cache.caches. Повторяющиеся запросы по одинаковому псевдониму в одном и том же потоке будут возвращать одинаковый результат.

>>> from django.core.cache import caches
>>> cache1 = caches['myalias']
>>> cache2 = caches['myalias']
>>> cache1 is cache2
True

Если указанного именованного ключа не существует, то будет вызвано исключение InvalidCacheBackendError.

Для обеспечения потоковой независимости, каждый поток будет получать разные экземпляры бэкэнда кэша.

django.core.cache.cache¶

As a shortcut, the default cache is available as django.core.cache.cache:

>>> from django.core.cache import cache

Этот объект эквивалентен caches['default'].

Использование¶

Базовый интерфейс:

cache.set(key, value, timeout=DEFAULT_TIMEOUT, version=None)¶

>>> cache.set('my_key', 'hello, world!', 30)

cache.get(key, default=None, version=None)¶

>>> cache.get('my_key')
'hello, world!'

key должен быть str, а value может быть любым поддающимся выбору объектом Python.

Аргумент timeout является необязательным и обычно равен аргументу timeout соответствующего бэкенда кэша из параметре конфигурации CACHES (читайте выше). Аргумент определяет период в секундах, в течение которого значение должно храниться в кэше. Передав None в timeout можно закэшировать данные навсегда. При timeout равном 0 значение никогда не будет кэшироваться.

If the object doesn’t exist in the cache, cache.get() returns None:

>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get('my_key')
None

If you need to determine whether the object exists in the cache and you have stored a literal value None, use a sentinel object as the default:

>>> sentinel = object()
>>> cache.get('my_key', sentinel) is sentinel
False
>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get('my_key', sentinel) is sentinel
True

cache.get() can take a default argument. This specifies which value to return if the object doesn’t exist in the cache:

>>> cache.get('my_key', 'has expired')
'has expired'

cache.add(key, value, timeout=DEFAULT_TIMEOUT, version=None)¶

To add a key only if it doesn’t already exist, use the add() method. It takes the same parameters as set(), but it will not attempt to update the cache if the key specified is already present:

>>> cache.set('add_key', 'Initial value')
>>> cache.add('add_key', 'New value')
>>> cache.get('add_key')
'Initial value'

Если вам надо определить сохранил ли метод add() значение в кэше, вы можете проверить значение, которое он возвращает. True указывает, что значение было сохранено, а False – наоборот.

cache.get_or_set(key, default, timeout=DEFAULT_TIMEOUT, version=None)¶

If you want to get a key’s value or set a value if the key isn’t in the cache, there is the get_or_set() method. It takes the same parameters as get() but the default is set as the new cache value for that key, rather than returned:

>>> cache.get('my_new_key')  # returns None
>>> cache.get_or_set('my_new_key', 'my new value', 100)
'my new value'

You can also pass any callable as a default value:

>>> import datetime
>>> cache.get_or_set('some-timestamp-key', datetime.datetime.now)
datetime.datetime(2014, 12, 11, 0, 15, 49, 457920)

cache.get_many(keys, version=None)¶

There’s also a get_many() interface that only hits the cache once. get_many() returns a dictionary with all the keys you asked for that actually exist in the cache (and haven’t expired):

>>> cache.set('a', 1)
>>> cache.set('b', 2)
>>> cache.set('c', 3)
>>> cache.get_many(['a', 'b', 'c'])
{'a': 1, 'b': 2, 'c': 3}

cache.set_many(dict, timeout)¶

To set multiple values more efficiently, use set_many() to pass a dictionary of key-value pairs:

>>> cache.set_many({'a': 1, 'b': 2, 'c': 3})
>>> cache.get_many(['a', 'b', 'c'])
{'a': 1, 'b': 2, 'c': 3}

Аналогично методу cache.set(), метод set_many() принимает необязательный параметр timeout.

На поддерживаемых бэкэндах (memcached) set_many() возвращает список ключей, которые не удалось вставить.

cache.delete(key, version=None)¶

You can delete keys explicitly with delete() to clear the cache for a particular object:

>>> cache.delete('a')
True

delete() возвращает True, если ключ был успешно удален, False в противном случае.

cache.delete_many(keys, version=None)¶

If you want to clear a bunch of keys at once, delete_many() can take a list of keys to be cleared:

>>> cache.delete_many(['a', 'b', 'c'])

cache.clear()¶

Finally, if you want to delete all the keys in the cache, use cache.clear(). Be careful with this; clear() will remove everything from the cache, not just the keys set by your application.

>>> cache.clear()

cache.touch(key, timeout=DEFAULT_TIMEOUT, version=None)¶

cache.touch() sets a new expiration for a key. For example, to update a key to expire 10 seconds from now:

>>> cache.touch('a', 10)
True

Как и другие методы, аргумент timeout является необязательным и по умолчанию равен опции TIMEOUT соответствующего бэкэнда в настройке CACHES.

touch() возвращает True, если клавиша была успешно нажата, False в противном случае.

cache.incr(key, delta=1, version=None)¶

cache.decr(key, delta=1, version=None)¶

You can also increment or decrement a key that already exists using the incr() or decr() methods, respectively. By default, the existing cache value will be incremented or decremented by 1. Other increment/decrement values can be specified by providing an argument to the increment/decrement call. A ValueError will be raised if you attempt to increment or decrement a nonexistent cache key.:

>>> cache.set('num', 1)
>>> cache.incr('num')
2
>>> cache.incr('num', 10)
12
>>> cache.decr('num')
11
>>> cache.decr('num', 5)
6

cache.close()¶

Можно закрыть подключение к кэшу методом close(), если бэкенд кэширования предоставляет его.

>>> cache.close()

Прификсы ключей кэша¶

Если ваш кэш разделяется между несколькими серверами или между окружениями разработки и продакшена, возможна ситуация, когда данные, закэшированные одним сервером, будут использованы другим сервером. Если формат закэшированных данных различен между серверами, то это может привести к трудно выявляемым проблемам.

Чтобы избежать такой ситуации, Django предоставляет возможность назначения префиксов для всех ключей кэша, используемых сервером. При работе с ключом Django автоматически добавляет к нему префикс, определённый параметром конфигурации KEY_PREFIX.

Назначив различные префиксы для каждого экземпляра Django с помощью параметра конфигурации KEY_PREFIX, вы гарантируете отсутствие коллизий в значениях кэша.

Версионирование кэша¶

При изменении работающего кода, который использует закэшированные значения, может потребоваться сброс всех закэшированных данных. Простым способом является отчистка всего кэша, но это может привести к потере закэшированных данных, которые всё ещё верны и полезны.

Django предоставляет отличный способ выделения отдельных значений в кэше. Система кэширования Django обладает глобальным идентификатором версии, определённым в параметре кэша VERSION. Значение этого параметра автоматически объединяется с префиксом кэша и пользователем, которые предоставил ключ, получая итоговый ключ для обращения к кэшу.

By default, any key request will automatically include the site default cache key version. However, the primitive cache functions all include a version argument, so you can specify a particular cache key version to set or get. For example:

>>> # Set version 2 of a cache key
>>> cache.set('my_key', 'hello world!', version=2)
>>> # Get the default version (assuming version=1)
>>> cache.get('my_key')
None
>>> # Get version 2 of the same key
>>> cache.get('my_key', version=2)
'hello world!'

The version of a specific key can be incremented and decremented using the incr_version() and decr_version() methods. This enables specific keys to be bumped to a new version, leaving other keys unaffected. Continuing our previous example:

>>> # Increment the version of 'my_key'
>>> cache.incr_version('my_key')
>>> # The default version still isn't available
>>> cache.get('my_key')
None
# Version 2 isn't available, either
>>> cache.get('my_key', version=2)
None
>>> # But version 3 *is* available
>>> cache.get('my_key', version=3)
'hello world!'

Преобразование ключа кэша¶

Как описано в предыдущих двух разделах, система кэширования никогда не использует напрямую ключ, предоставленный пользователем. Ключ всегда комбинируется с префиксом кэша и версией ключа. По-умолчанию, эти три части объединяются через двоеточия, создавая итоговый ключ:

def make_key(key, key_prefix, version):
    return '%s:%s:%s' % (key_prefix, version, key)

Если вам потребуется объединить эти части другим способом или создать ключ другим способом (т.е. приняв хеш ключа за сам ключ), вы можете указать функцию, которая будет выполнять эту работу.

Параметр кэша KEY_FUNCTION определяет путь в точечной нотации к функции, соответствующей прототипу make_key() из предыдущего примера. При наличии такой функции она будет использоваться вместо стандартной функции построения итогового ключа.

Предупреждения о проблемах с ключами¶

Memcached, наиболее используемый в продакшене бэкенд кэширования, не поддерживает ключи длиной более 250 символов или содержащих пробелы или управляющие символы. Использование таких ключей приводит к вызову исключения. Для обеспечения уверенности в портируемости кода между кэширующими бэкендами и для уменьшения количества неприятных сюрпризов, другие встроенные кэширующие бэкенды выбрасывают предупреждение (django.core.cache.backends.base.CacheKeyWarning), если используемый ключ может привести к ошибке при работе с Memcached.

Если вы используете на продакшене кэширующий бэкенд, который может принимать широкий диапазон ключей (собственный бэкенд или один из встроенных бэкендов, кроме Memcached), и не желаете видеть подобные предупреждения, вы можете заглушить CacheKeyWarning с помощью следующего кода в модуле management одного из ваших приложений:

import warnings

from django.core.cache import CacheKeyWarning

warnings.simplefilter("ignore", CacheKeyWarning)

Если вам требуется изменить логику проверки ключа для одного из встроенных бэкендов кэширования, вы можете унаследовать свой класс от него и переопределить метод validate_key. Затем следуйте инструкциям по использованию собственного бэкенда кэширования. Например, для реализации подобного для бэкенда locmem, поместите следующий код в модуль:

from django.core.cache.backends.locmem import LocMemCache

class CustomLocMemCache(LocMemCache):
    def validate_key(self, key):
        """Custom validation, raising exceptions or warnings as needed."""
        ...

…и используйте путь в точечной нотации к этому классу в ключе BACKEND параметра конфигурации CACHES.