Understand how KV reads scale

Workers KV is a giant dictionary. You store a value under a key and read it back from anywhere in the world. What makes it worth a lesson is how it makes those reads fast.

KV keeps values in central storage and caches them across Cloudflare’s network after reads. When a Worker in Milan asks for a key the local data center has never seen, the read travels to central storage. That’s the slower, cold path. The value then gets cached near Milan, and the next reads there are fast.

So popular keys become fast near the people reading them, without copying every write to every location.

The read itself is one line in a Worker:

const flags = await env.CONFIG.get('feature-flags', 'json')

The first request from a region can take noticeably longer than the thousands that follow it. That’s the design working, not a bug.

What this trades away

Caching on read is why writes propagate lazily. A put is visible immediately where it happened, but other locations can keep serving their cached copy for up to 60 seconds. The store is eventually consistent: every location gets the new value, just not all at the same moment. This whole course keeps coming back to that idea.

That trade decides what KV is for. It fits values read far more often than they change: configuration, user preferences, allow lists, and caches of expensive computation.

It does not fit a counter or a lock that needs atomic updates on one hot key:

// broken: two Workers can both read 41 and both write 42
const count = parseInt(await env.COUNTERS.get('signups') ?? '0', 10)
await env.COUNTERS.put('signups', String(count + 1))

There is no atomic increment, and two data centers may not even agree on the current value. For that job you want a Durable Object or D1.

My advice is to name the required consistency before choosing KV. Write down, in one sentence, what happens in your product if a read returns a value from one minute ago. If the answer is “nothing bad”, KV is a great fit.

Try this: take five values from an application you know and classify each by read frequency, write frequency, and tolerance for a briefly stale result. Mark which ones belong in KV.