Django のキャッシュフレームワーク¶

Memcached¶

Memcached は完全にメモリベースのキャッシュ・サーバで、元々はLiveJournal.comの高負荷を処理するために開発され、その後Danga Interactiveによってオープンソース化されました。FacebookやWikipediaなどのサイトで使用され、データベースへのアクセスを減らし、サイトのパフォーマンスを劇的に向上させます。

Memcached はデーモンとして動作し、指定された量の RAM が割り当てられます。キャッシュにデータを追加、取得、削除するための高速なインターフェイスを提供するだけです。すべてのデータはメモリに直接保存されるので、データベースやファイルシステムの使用によるオーバーヘッドはありません。

Memcached 自体をインストールした後、Memcached バインディングをインストールする 必要があります。Python の Memcached バインディングはいくつかありますが、 Django がサポートしているのは pylibmc と pymemcache です。

Django で Memcached を使用する

• BACKEND を django.core.cache.backends.memcached.PyMemcacheCache または django.core.cache.backends.memcached.PyLibMCCache (選択した memcached バインディングによる) に設定する

• LOCATION を ip:port の値 (ここで、ip は Memcached デーモンの IP アドレス、port は Memcached が起動しているポート)、または、unix:path の値に設定する (ここで、path は Memcached Unix socket ファイルへのパス)。

次の例では、Memcached は localhost (127.0.0.1) port 11211 で起動していて、pymemcache バインディングを使用しています。

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

次の例では、Memcached はローカルの Unix socket ファイル /tmp/memcached.sock 経由で利用可能であり、pymemcache バインディングを使用しています。

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

Memcached の優れた機能の一つは、複数のサーバでキャッシュを共有できることです。つまり、複数のマシンで Memcached デーモンを実行することができ、各マシンでキャッシュの値を重複させることなく、 単一の キャッシュとして扱うことができます。この機能を利用するには、全てのサーバのアドレスを LOCATION に、セミコロンまたはカンマ区切りの文字列、あるいはリストとして記述します。

このインスタンスでは、IP アドレス 172.19.26.240 と 172.19.26.242 で動作する Memcached インスタンスをポート 11211 で共有します:

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

以下の例では、172.19.26.240 (port 11211)、172.19.26.242 (port 11212)、172.19.26.244 (port 11213) の IP アドレスで動作する Memcached インスタンスでキャッシュを共有しています:

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

デフォルトでは、 PyMemcacheCache バックエンドは以下のオプションを設定します( OPTIONS で上書きできます):

"OPTIONS": {
    "allow_unicode_keys": True,
    "default_noreply": False,
    "serde": pymemcache.serde.pickle_serde,
}

Memcachedについての最後のポイントは、メモリベースのキャッシュには欠点があるということです。キャッシュされたデータはメモリに保存されるので、サーバーがクラッシュするとデータは失われます。メモリは永続的なデータ保存用ではないので、メモリベースのキャッシュを唯一のデータ保存用として使わないようにしましょう。明らかに、 Django のキャッシュバックエンドはどれも、永続的な保存には使うべきではありません。これらは全てキャッシュのためのソリューションであって、ストレージではありません。しかし、メモリベースのキャッシュは特に一時的なものであるため、 ここでに記載しておきます。

Redis¶

Redis は、キャッシュに利用できるインメモリ データベースです。はじめに、Redis サーバーがローカルまたはリモートマシン上で起動している必要があります。

Redis サーバを設定した後、Redis の Python バインディングをインストールする必要があります。 redis-py は Django によってネイティブにサポートされているバインディングです。 hiredis-py パッケージも推奨のひとつです。

Redis をキャッシュ バックエンドとして Django で使用するには、次のようにします。

• BACKEND を django.core.cache.backends.redis.RedisCache に設定する。

• LOCATION を、適切なスキーマを使用して Redis インスタンスを指す URL に設定する。利用可能なスキーマの詳細 については、redis-py のドキュメントを参照してください。

たとえば、Redis が localhost (127.0.0.1) port 6379 で起動している場合は、次のように設定します。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
    }
}

Redis サーバーは認証で保護されていることがよくあります。ユーザー名とパスワードを提供するには、LOCATION 内に URL とともに追加します。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://username:password@127.0.0.1:6379",
    }
}

レプリケーション・モードで複数のRedisサーバーを設定している場合は、セミコロンまたはカンマ区切りの文字列、あるいはリストとしてサーバーを指定できます。複数のサーバーを使用している場合、書き込み操作は最初のサーバー（リーダー）で実行されます。読み取り操作は、ランダムに選ばれた他のサーバ（レプリカ）で実行されます:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": [
            "redis://127.0.0.1:6379",  # leader
            "redis://127.0.0.1:6378",  # read-replica 1
            "redis://127.0.0.1:6377",  # read-replica 2
        ],
    }
}

データベースのキャッシュ¶

Django はキャッシュデータをデータベース中に保存できます。この仕組みは、高速で適切にインデックス付けされたデータベースサーバーがある場合に、有効に機能します。

データベースのテーブルをキャッシュのバックエンドに使用する場合には、以下のように設定します。

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

他のキャッシュバックエンドとは異なり、データベースキャッシュはデータベースレベルでの期限切れエントリの自動間引き (culling) をサポートしていません。その代わり、 add() や set() 、 touch() が呼び出されるたびに、期限切れのキャッシュエントリが「間引き」されます。

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 は個々のメモリストアを識別するために使用されます。もし locmem キャッシュが1つしかない場合は LOCATION を省略できます。しかし、複数のローカルメモリーキャッシュがある場合は、それらを区別するために少なくとも1つに名前を割り当てる必要があります。

キャッシュは LRU (least-recently-used) 淘汰戦略 (culling strategy) を使用します。

各プロセスはそれ自身のプライベートキャッシュインスタンスを持つことに注意してください。このことは、ローカル・メモリ・キャッシュが特にメモリ効率に優れているわけではないことを意味します。そのため、おそらく本番環境には良い選択ではありません。開発環境には適しています。

ダミーキャッシュ（開発用）¶

最後に、 Django には実際にはキャッシュしない「ダミー」キャッシュが付属しています。何もせずにキャッシュインターフェースを実装しているだけです。

これは、様々な場所で重量級のキャッシュを使用する本番サイトと、開発/テスト用に、キャッシュを行わず、コード変更も最小限に留めたい環境がある場合に便利です。ダミーキャッシュをアクティブにするには、BACKEND を以下のように設定します。

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

独自のキャッシュバックエンドを使う¶

Django は「箱から出してすぐに」多くのキャッシュバックエンドをサポートしていますが、カスタマイズ したキャッシュバックエンドを使いたいこともあるでしょう。Django で外部のキャッシュバックエンドを使用するには、下記のように、 CACHES 設定の BACKEND に Python のインポートパスを使用します:

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

独自のバックエンドを構築する場合は、標準のキャッシュバックエンドをリファレンス実装として使うことができます。コードは Django ソースの django/core/cache/backends/ ディレクトリにあります。

注記：ホストがサポートしていないなど、やむを得ない理由がない限り、Django に付属しているキャッシュバックエンドを使用するべきです。それらは十分にテストされており、よくドキュメント化されています。

キャッシュ引数¶

それぞれのキャッシュバックエンドはキャッシュの動作を制御するために追加の引数を指定できます。これらの引数は CACHES 設定の追加キーとして提供されます。有効な引数は以下の通りです:

• TIMEOUT: キャッシュに使用するデフォルトのタイムアウトを秒単位で指定します。この引数のデフォルトは 300 秒（5分）です。 TIMEOUT に None を指定することで、デフォルトではキャッシュキーの有効期限が切れません。値を 0 にすると、キーはすぐに期限切れになります（事実上 "キャッシュしない"）。

• OPTIONS: キャッシュバックエンドに渡すオプション。有効なオプションのリストはバックエンドによって異なり、サードパーティライブラリにバックされたキャッシュバックエンドはそのオプションを直接キャッシュライブラリに渡します。

  独自の淘汰戦略 (culling strategy) を実装しているキャッシュバックエンド (locmem、filesystem、database バックエンド) では、以下のオプションが有効です:

  • MAX_ENTRIES: 古い値が削除されるまでにキャッシュに保存できる最大エントリ数。この引数のデフォルトは 300 です。

  • CULL_FREQUENCY: MAX_ENTRIES に達したときに間引き (cull) されるエントリの割合。実際の割合は 1 / CULL_FREQUENCY なので、 CULL_FREQUENCY を 2 に設定すると、 MAX_ENTRIES に達したときにエントリの半分をカリングします。この引数は整数で、デフォルトは 3 です。

    CULL_FREQUENCY に 0 という値を指定すると、 MAX_ENTRIES に達したときにキャッシュ全体がダンプされます。一部のバックエンド (特に database) では、キャッシュミスが増える代わりにカリング（間引き）が非常に速くなります。

  Memcached と Redis のバックエンドは、クライアントの動作をより高度に制御できるように、クライアントのコンストラクタにキーワード引数として OPTIONS の内容を渡します。使用例は以下を参照してください。

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

以下は、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,
            },
        },
    }
}

以下は pymemcache ベースのバックエンドの設定例です。クライアントのプーリングを有効にし (クライアントの接続を維持することでパフォーマンスを向上させることができます)、memcache/ネットワークのエラーをキャッシュミスとして扱い、接続ソケットに TCP_NODELAY フラグを設定します。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "127.0.0.1:11211",
        "OPTIONS": {
            "no_delay": True,
            "ignore_exc": True,
            "max_pool_size": 4,
            "use_pooling": True,
        },
    }
}

以下は、redis を使用したバックエンドの設定例です。この設定では、データベース 10 を選択し（デフォルトでは Redis は16個の論理データベースを提供しています）、カスタムの connection pool class を設定します（デフォルトでは redis.ConnectionPool が使用されます）。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
        "OPTIONS": {
            "db": "10",
            "pool_class": "redis.BlockingConnectionPool",
        },
    }
}

ビューごとのキャッシュを URLconf で指定する¶

前のセクションの例では、 cache_page が my_view 関数を変更するため、ビューがキャッシュされることをハードコードしていました。この方法では、ビューをキャッシュシステムに結合することになり、いくつかの理由から理想的ではありません。例えば、キャッシュのない別のサイトでビュー関数を再利用したい場合や、キャッシュされずにビューを使いたい人にビューを配布したい場合などです。このような問題の解決策は、ビュー関数そのものではなく URLconf でビューごとのキャッシュを指定することです。

URLconf でビュー関数を参照するときに cache_page でラップすることで、これを実現できます。以下は以前の古い URLconf です。

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 という Dict のようなオブジェクトでアクセスできます。同じスレッドで同じエイリアスを繰り返しリクエストすると、同じオブジェクトが返されます。

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

指定したキーが存在しない場合、 InvalidCacheBackendError が発生します。

スレッドセーフを実現するために、キャッシュバックエンドの異なるインスタンスがスレッドごとに返されます。

django.core.cache.cache¶

ショートカットとして、デフォルトのキャッシュは 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 はオプションで、デフォルトは CACHES 設定 (上記で説明) にある適切なバックエンドの timeout 引数です。これはキャッシュに保存される秒数です。 timeout に None を渡すと、値は永遠にキャッシュされます。 timeout に 0 を渡すと、値はキャッシュされません。

オブジェクトがキャッシュに存在しない場合、 cache.get() は None を返します:

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

オブジェクトがキャッシュに存在するかどうかを判断する必要があり、リテラル値 None を保存した場合は、デフォルトとして sentinel オブジェクトを使用します:

>>> 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() は default 引数を取ることができます。これは、オブジェクトがキャッシュに存在しない場合に返す値を指定します:

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

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

キーがまだ存在しない場合にのみキーを追加するには、 add() メソッドを使用します。このメソッドは set() と同じパラメータを受け取りますが、指定したキーがすでに存在する場合はキャッシュを更新しようとしません:

>>> 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)¶

キーの値を取得したり、そのキーがキャッシュにない場合に値を設定したい場合は、 get_or_set() メソッドが使えます。これは get() と同じパラメータを受け取りますが、そのキーのデフォルトの戻り値が設定されます:

>>> cache.get("my_new_key")  # returns None
>>> cache.get_or_set("my_new_key", "my new value", 100)
'my new 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)¶

一度だけキャッシュをヒットする get_many() インターフェースもあります。 get_many() は、キャッシュに実際に存在する (そして有効期限が切れていない) キーをすべて含む辞書を返します:

>>> 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)¶

より効率的に複数の値を指定するには、 set_many() を使用してキーと値のペアの辞書を渡します:

>>> 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)¶

delete() で明示的にキーを削除することで、特定のオブジェクトのキャッシュをクリアできます:

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

delete() はキーの削除に成功すると True を返し、失敗すると False を返します。

cache.delete_many(keys, version=None)¶

一度にたくさんのキーをクリアしたい場合は、 delete_many() にクリアしたいキーのリストを渡します:

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

cache.clear()¶

最後に、キャッシュ内のすべてのキーを削除したい場合は、cache.clear() を使用してください。ただし、この操作には注意が必要です。clear() はアプリケーションによって設定されたキーだけでなく、 キャッシュ内のすべて を削除します。

>>> cache.clear()

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

cache.touch() はキーの有効期限を設定します。例えば、キーの有効期限を10秒後に更新する場合:

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

他のメソッドと同様に、 timeout 引数はオプションで、デフォルトは CACHES 設定の適切なバックエンドの TIMEOUT オプションです。

touch() はキーが正しく touch された場合は True を返し、そうでない場合は False を返します。

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

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

incr() メソッドまたは decr() メソッドを使用して、既に存在するキーをインクリメント/デクリメントすることもできます。デフォルトでは、既存のキャッシュの値が 1 だけインクリメント/デクリメントされます。インクリメント/デクリメントの呼び出しに引数を指定することで、1以外のインクリメント/デクリメント値を指定できます。存在しないキャッシュ・キーをインクリメントまたはデクリメントしようとすると、ValueError が発生します:

>>> 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 キャッシュ設定で指定できる、システム全体のバージョン識別子があります。この設定の値は、自動的にキャッシュ・プレフィックスとユーザが指定したキャッシュ・キーと組み合わされ、最終的なキャッシュ・キーが得られます。

デフォルトでは、どのようなキャッシュキーのリクエストも自動的にサイトのデフォルトのキャッシュキーのバージョンを含みます。しかし、基本的なキャッシュ関数には version 引数が含まれているので、特定のキャッシュキーのバージョンを指定できます。たとえば:

>>> # 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!'

特定のキーのバージョンは incr_version() メソッドと decr_version() メソッドで増減できます。これにより、特定のキーのバージョンを新しいものに変更できます。先ほどの例の続きで、下記のようにします:

>>> # 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!'

キャッシュキーの変換¶

前の2つのセクションで説明したように、ユーザから提供されたキャッシュ・キーはそのまま使用されるわけではありません。このキーは、キャッシュ・プレフィックスおよびキーバージョンと組み合わされて最終的なキャッシュ・キーとなります。デフォルトでは、3 つの部分はコロンで結合されて最終的な文字列となります:

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

各部分をさまざまな方法で組み合わせたり、最終的なキーに他の処理を施したりしたい場合は（例えば、キーの部品のハッシュダイジェストを取るなど）、独自のキー関数を作成できます。

KEY_FUNCTION キャッシュ設定では、上記の make_key() のプロトタイプにマッチする関数へのドット区切りパスを指定します。指定された場合、デフォルトのキー結合関数の代わりにこのカスタムキー関数が使用されます。

キャッシュキーの警告¶

最も一般的に使用されているキャッシュバックエンドである Memcached は、 250 文字より長いキャッシュキーや、空白文字や制御文字を含むキャッシュキーを許可しておらず、そのようなキーを使用すると例外が発生します。キャッシュ移植可能なコードを推奨し、不快な驚きを最小化するために、他の組み込みキャッシュバックエンドは、 memcached でエラーを引き起こすようなキーが使用された場合、警告 (django.core.cache.backends.base.CacheKeyWarning) を出します。

より広い範囲のキーを使用できるバックエンド (カスタムバックエンド、または非emcachedの組み込みバックエンド) を使用していて、警告を出さずにより広い範囲のキーを使用したい場合は、 INSTALLED_APPS の management モジュールにあるこのコードで CacheKeyWarning を無効にできます:

import warnings

from django.core.cache import CacheKeyWarning

warnings.simplefilter("ignore", CacheKeyWarning)

組み込みのバックエンドに対してカスタムキーバリデーションのロジックを提供したい場合は、そのバックエンドをサブクラス化して validate_key メソッドだけをオーバーライドし、 using a custom cache backend の説明に従ってください。たとえば、 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."""
        ...

...そして、このクラスへのドット区切りパスを CACHES 設定の BACKEND 部分で使用します。