🧹 Cache Invalidation

Why It's Hard

"There are only two hard things in Computer Science: cache invalidation and naming things." — Phil Karlton

It's a joke, but it's on the syllabus for a reason. Invalidation is hard because it forces you to track something slippery: every cache entry that might be affected by a change, across code that may live in different files, services, or even data centers. Miss one, and a user sees a deleted product. Clear too many, and you throw away the performance you built the cache for.

Invalidation vs. expiration

Two related but distinct ideas — you'll use both together:

The consistency spectrum

Not all data needs the same rigor. Match your effort to the cost of being wrong:

• Strong consistency — the cache must never disagree with the source (account balances, permissions). Invalidate aggressively on every write.
• Eventual consistency — brief staleness is fine and self-corrects (a "likes" count). A short TTL is often enough.
• Weak consistency — staleness barely matters (a view counter, a trending list). A long TTL and a lazy refresh will do.

TTL: The Baseline

The simplest invalidation strategy is to not invalidate at all — just let every key expire on a timer. It requires zero coordination and is the right default for anything that tolerates a little staleness.

// A cached read where the ONLY invalidation is the TTL
async function getUserProfile(userId) {
  const key = `user:${userId}:profile`;

  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const profile = await db.users.findOne({ _id: userId });
  if (profile) {
    // After 30 minutes this entry disappears and the next read reloads it.
    await redis.set(key, JSON.stringify(profile), { EX: 1800 });
  }
  return profile;
}

Event-Based Invalidation

When staleness isn't acceptable, tie invalidation to the write. The rule of thumb: the code that changes the data is responsible for clearing its cache. Update the database, then delete the affected keys in the same operation.

// Express route: update a product and invalidate its cache
app.put('/api/products/:id', async (req, res) => {
  try {
    const { id } = req.params;

    // 1. Write to the source of truth
    const updated = await db.products.findOneAndUpdate(
      { _id: id },
      { $set: req.body },
      { returnDocument: 'after' }
    );
    if (!updated) return res.status(404).json({ error: 'Not found' });

    // 2. Clear every cache entry this product could appear in
    await redis.del([
      `product:${id}`,                          // the product itself
      `products:category:${updated.category}`,  // its category listing
      'products:featured',                      // the featured list
      'products:recent'                         // the recents list
    ]);

    res.json(updated);
  } catch (err) {
    console.error('Update failed:', err);
    res.status(500).json({ error: 'Update failed' });
  }
});

Advantages: the cache is consistent almost immediately after a change. Trade-offs: you must track which keys to clear, and it couples every write path to your cache layout.

Versioned Keys

What if you never had to delete anything? With versioned keys, you bump a version number when data changes, which instantly makes every old key unreachable. The stale entries still exist for a moment, but nobody looks them up — and their TTL sweeps them away.

class VersionedCache {
  constructor(redis) {
    this.redis = redis;
  }

  // The real cache key includes the current version, e.g. user:5:profile:v3
  async versionedKey(baseKey) {
    const version = (await this.redis.get(`ver:${baseKey}`)) || '1';
    return `${baseKey}:v${version}`;
  }

  async get(baseKey) {
    const key = await this.versionedKey(baseKey);
    const raw = await this.redis.get(key);
    return raw ? JSON.parse(raw) : null;
  }

  async set(baseKey, data, ttl = 3600) {
    const key = await this.versionedKey(baseKey);
    await this.redis.set(key, JSON.stringify(data), { EX: ttl });
  }

  // "Invalidate" = bump the version. Old vN keys are now orphaned
  // and expire on their own. No delete, no scan, no race.
  async invalidate(baseKey) {
    return this.redis.incr(`ver:${baseKey}`);
  }
}

// Usage
const cache = new VersionedCache(redis);
await cache.set('user:5:profile', profile);   // writes ...:v1
await cache.invalidate('user:5:profile');     // version -> 2
// Next read builds ...:v2, misses, and reloads fresh data.

Invalidating Groups of Keys

Sometimes one change should clear many related keys — every cached page of a category, say. The instinct is KEYS pattern, and it's a trap: KEYS scans the entire database and blocks Redis's single thread while it does. Use SCAN, which iterates in small non-blocking chunks.

// ❌ NEVER in production — blocks the whole server
// const keys = await redis.keys('product:category:5:*');

// ✅ SCAN iterates lazily; delete matches as you go
async function invalidatePattern(pattern) {
  let deleted = 0;
  for await (const key of redis.scanIterator({ MATCH: pattern, COUNT: 100 })) {
    await redis.del(key);
    deleted++;
  }
  console.log(`Invalidated ${deleted} keys matching ${pattern}`);
  return deleted;
}

// Clear every cached listing page for a category
await invalidatePattern('products:category:5:page:*');

// On cache write, record the key under its group tag
await redis.set('products:category:5:page:1', json, { EX: 3600 });
await redis.sAdd('tag:category:5', 'products:category:5:page:1');

// On invalidate, clear exactly the tagged keys
async function invalidateTag(tag) {
  const keys = await redis.sMembers(tag);
  if (keys.length) await redis.del(keys);
  await redis.del(tag);
}
await invalidateTag('tag:category:5');

Coordinating Across Services

In a single app, deleting a key is a local call. In a microservice or multi-instance deployment, the service that changes the data may not be the one holding the stale cache. Redis pub/sub broadcasts an invalidation event so every instance clears its copy.

const CHANNEL = 'cache:invalidate';

// --- Publisher: any service that mutates data ---
async function publishInvalidation(type, id) {
  const message = JSON.stringify({ type, id, at: Date.now() });
  await redis.publish(CHANNEL, message);
}

// --- Subscriber: every instance that holds a cache ---
async function startInvalidationListener() {
  // A subscriber connection can't run normal commands, so duplicate the client.
  const subscriber = redis.duplicate();
  await subscriber.connect();

  await subscriber.subscribe(CHANNEL, async (message) => {
    const { type, id } = JSON.parse(message);
    await redis.del(`${type}:${id}`);

    // Clear related derived keys too
    if (type === 'product') {
      await redis.del(['products:featured', 'products:recent']);
    }
    console.log(`Invalidated ${type}:${id} from broadcast`);
  });

  console.log('Listening for invalidation events');
}

// When the order service updates a product:
await db.products.updateOne({ _id: id }, { $set: changes });
await publishInvalidation('product', id);   // every instance clears its cache

Practice & Quiz

async function updateUser(userId, changes) {
    await db.users.updateOne({ _id: userId }, { $set: changes });
    // TODO: invalidate `user:${userId}` and `user:${userId}:profile`
}

async function updateUser(userId, changes) {
    await db.users.updateOne({ _id: userId }, { $set: changes });
    await redis.del([`user:${userId}`, `user:${userId}:profile`]);
}

async function clearCategory(catId) {
    const keys = await redis.keys(`category:${catId}:*`); // ❌
    if (keys.length) await redis.del(keys);
}

async function clearCategory(catId) {
    for await (const key of redis.scanIterator({
        MATCH: `category:${catId}:*`, COUNT: 100
    })) {
        await redis.del(key);
    }
}

Best Practices & Pitfalls

✅ Do

• Keep invalidation logic next to the write that causes it.
• Use a consistent, hierarchical key naming scheme so related keys are easy to find and clear.
• Always keep a TTL as a safety net, even with active invalidation.
• Be pessimistic: when unsure whether a change affects a key, clear it — a cache miss beats stale data.
• Prefer versioned keys or tag sets over pattern scans for grouped invalidation.

❌ Don't

• Run KEYS in production — use SCAN or tracked tag sets.
• Forget derived and aggregated data (lists, search results, counts) when clearing a record.
• Rely on plain pub/sub for guaranteed delivery — subscribers that are down miss the message.
• Invalidate a hugely popular key without stampede protection (recall last lesson's lock and stale-while-revalidate).
• Over-invalidate: clearing far more than changed quietly destroys your hit rate.

Summary

📚 Additional Resources

• redis.io — Keyspace notifications
• redis.io — SCAN command reference
• redis.io — Redis Pub/Sub
• Martin Fowler — Two Hard Things

🚀 What's Next?

Write-behind caching and cross-service invalidation both leaned on a queue to do work reliably in the background. That idea deserves its own lesson: Queue Systems — decoupling slow or async work from the request/response cycle.