Understand how KV reads scale

Workers KV looks like a giant dictionary: you store a value under a key and read it back from anywhere in the world. The interesting part is how it makes those reads fast.

KV stores values in central systems and caches them through 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 is the slower, cold path. The value then gets cached near Milan, and the next reads there are fast. Popular keys become fast near their readers without copying every write synchronously 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 is 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 — a theme this whole course keeps returning to.

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 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: 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.

Now classify five values from an application you know — by read frequency, write frequency, and tolerance for a briefly stale result — and mark which ones belong in KV.