Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Strategies and Invalidation

Versioned Keys and Namespaces

Invalidate whole groups of Memcached keys at once with a namespace version counter, or version a single entity so stale copies can never be read again.

Memcached cannot delete "all keys that start with category:mugs:", and it cannot list keys. Yet real applications constantly need to invalidate a whole group: every cached page of a category, every fragment belonging to one user, every item of one tenant. The trick that solves this is simple and powerful: put a version number inside the key, and invalidate by changing the version rather than deleting anything.

Namespace versions

Store one small counter per group, say ns:category:mugs. Every key in that group includes the counter's current value:

TEXT
ns:category:mugs            -> 7
category:mugs:v7:page:1     -> cached listing
category:mugs:v7:page:2     -> cached listing

To invalidate the entire group, increment the counter. The next lookup builds keys with v8, which do not exist, so everything misses and is rebuilt. The old v7 entries are never read again and are cleaned up by expiry and eviction, with no explicit delete.

Reading a group key therefore costs two lookups: one for the version and one for the item. You can fetch both in a single multi-get if you cache the version in the process for a second or two, or fetch the version once per request and reuse it for many keys.

Python Invalidate a whole group with one incr

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

One incr call, which is atomic, invalidates any number of keys, even keys you did not know existed.

A reusable helper

Wrap the counter logic in a class so the rest of the code just asks for a key.

Python A Namespace helper class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Gotchas of namespace versions

  • The version key itself can be evicted. If ns:category:mugs disappears, the counter restarts at 1 and old v1 entries could come back to life with stale data. Mitigate by starting the counter from a timestamp or a random number instead of 1, so a reset never reuses a recent version.
  • Wasted memory. Old-version entries sit around until they expire or are evicted. Short TTLs keep that small.
  • An extra lookup per read. Fetch the version once and reuse it, or fetch it together with the first item using multi-get.
  • Race on creation. Use add (not set) to create the counter so two processes do not both reset it.
Python Start versions from a timestamp

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Versioning a single entity

A related idea is to include the entity's own version in its key. If your database rows have an updated_at timestamp or a version column, put it in the key:

TEXT
product:42:v20260115T093000

When the row changes, its version changes, so the new key is a miss and the old key is never read again: no delete is needed, and the delete-and-refill race from the previous lesson disappears, because a stale value is stored under a stale key that nobody asks for. The cost is that you must know the current version before you can build the key, which means a cheap lookup to the database (or a small cached version number) on every read. Frameworks use this for template fragments: the key includes the model's updated_at.

Python Entity-versioned keys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Which to use

Need Technique
Invalidate a group (category, tenant, user) Namespace version counter
Invalidate one entity precisely Delete the key, or version the entity
Deploy changes the value format Version in the key prefix (v3)
Whole cache must go flush_all (last resort)

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a namespace version invalidate many keys at once?

    New lookups build keys with the new version number, which do not exist, so everything misses and is rebuilt.
  2. 2. Why use add to create the namespace counter instead of set?

    set would overwrite an existing version; add only creates it if absent.
  3. 3. What is the danger if the version key itself is evicted and restarts at 1?

    Reusing a version number resurrects old entries. Starting from a timestamp or random number avoids that.
  4. 4. What is an advantage of putting an entity's own version (updated_at) in its key?

    A changed row produces a different key. A late stale write goes to the old key, which is never asked for again.

Summary

  • Memcached has no pattern delete or key listing, so group invalidation uses a version counter inside the keys.
  • Incrementing a namespace counter invalidates the whole group; old entries age out by themselves.
  • Create counters with add, start them from a timestamp, and reuse the fetched version within a request.
  • Entity-versioned keys (updated_at in the key) avoid deletes and the refill race, at the cost of knowing the version first.
  • Use a version prefix in all keys so format changes in a deploy are safe.

Next: Stampede Protection