Caching.

Do the slow work once, then remember the answer.

A cache is a small, fast store that sits in front of a slow one. Before doing the expensive work, you check whether you already have the answer. If you do, that’s a hit, and you skip the work. If you don’t, that’s a miss: you do the work and keep a copy for next time.

This isn’t a simulation. Each lookup races two real paths on Cloudflare: one straight to a Postgres database, one through a Workers KV cache. Look a city up once to watch it miss, then again to watch it hit. Everyone shares the same cache.

Live caching demo

Races
0
Hit rate
—
Median hit
—
Median database
—
Replay
4× slower

Client you

City to look up

One press sends both paths at once.

Direct · no cache

Cache Workers KV · 60 s TTL

  • LONemptyLondon: not held
  • CARemptyCardiff: not held
  • EDIemptyEdinburgh: not held
  • BERemptyBerlin: not held
  • LISemptyLisbon: not held
  • OSLemptyOslo: not held

Workers KV · 60 s TTL

Database Neon Postgres

Neon Postgres

Idle · 630,720 rows

The race server-timed, replayed 4× slower

Straight to the database
—
Through the cache
—
  • Cache read
  • Database query
  • Cache write

No race yet

The answer nothing yet

Each lookup asks for a city’s whole 2025: every reading, summarised. Pick a city to fetch its report.

Your races newest first

Your races collect here. Try the same city twice.

Everyone on this page shares the cache, so a city someone else just looked up may already be warm.

How it's wired.

One lookup, two paths, one starting line
  1. Lookup

    Your click sends one POST to /api/concepts/caching/lookups. The Worker starts both paths at the same moment with Promise.all, so they race on the same machine, from the same starting line.

  2. Cache

    The cached path asks Workers KV for the city’s report first. If a copy is there and younger than 60 seconds, that’s a hit, and the path is finished.

  3. Database

    On a miss, and always on the direct path, Postgres reads all 105,120 of the city’s readings for 2025 and works out the report: the mean, the percentiles, the extremes, the rain and the months.

  4. Write-back

    On the way back, the cached path drops a copy in KV with a 60-second TTL. That one write is what makes the next lookup fast, for everyone.

  5. Timings

    The server times every hop with performance.now() and sends the timings back. The rig replays them four times slower, at their true proportions.

The race · application/use-cases.ts
// same Worker, same moment
const [direct, cached] = await Promise.all([
  directPath(deps, city),
  cachedPath(deps, city),
]);
Read-through · application/use-cases.ts
const found = await cache.read(city);
if (found && isFresh(found, now))
  return found.report; // hit

// miss: do the work, keep a copy
const report = await db.compute(city);
await cache.write(city, cacheCopy(report, now));
return report;

When to reach for one.

Slow to make, safe to reuse
Expensive reads
Reports, dashboards and search results that take real work to compute but change slowly.
Hot keys
The home page, the top product, the trending post. A thousand people asking for the same thing.
Slow or rate-limited APIs
A payment provider’s exchange rates or a weather service’s forecast: ask once, answer many times.
Rendered pages
Whole HTML responses held at the edge, so most visitors never reach your server at all.
What a cache doesn't promise
A cache serves the past.
For up to 60 seconds, this cache hands back a report even if the readings have changed. Choosing how stale an answer may be, and how you’ll invalidate it, is most of the work. This demo’s data never changes, which is the easy case.
Workers KV is eventually consistent.
A copy written in London can take up to a minute to appear in Sydney, and an evict takes as long to spread. Visitors in different places can see different answers for a while.
Your driver may be caching already.
Cloudflare’s Hyperdrive, which connects this Worker to Postgres, caches read queries for 60 seconds by default. The report query calls now(), which Hyperdrive never caches, so the direct path really does reach the database.
The first visitor pays.
Every copy starts as a miss, and a miss is slower than no cache at all. When many people miss the same key at once, they all hit the database together. That’s a cache stampede, and this demo doesn’t guard against it.
The Worker’s clock only moves during I/O.
To blunt timing attacks, a Worker’s clock stands still while code runs and jumps forward across network calls. Every hop timed here is a network call, so the numbers are fair. They leave out your own network trip, which the rig shows separately as the round trip.
Clear thinking. Deliberate engineering.© 2026 Owain Williams