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
One press sends both paths at once.
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.
How it's wired.
One lookup, two paths, one starting line- Lookup
Your click sends one
POSTto/api/concepts/caching/lookups. The Worker starts both paths at the same moment withPromise.all, so they race on the same machine, from the same starting line. - 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.
- 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.
- 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.
- 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.
// same Worker, same moment
const [direct, cached] = await Promise.all([
directPath(deps, city),
cachedPath(deps, city),
]);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.
The small print.
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.