Workers KV makes reads fast by making writes slow and consistency optional

Evidence status

Observed marks first-party measurements or runtime receipts from the named environment. Derived marks arithmetic calculated from cited inputs. Specified marks vendor or standards documentation. Implemented and deployed name code and live-state evidence, respectively. Reproduced means the stated procedure was rerun. Externally attested marks operator reports; those reports show that an experience occurred, not that it is universal.

Cloudflare's own Workers lead calls the database use a misuse

Kenton Varda, who leads the Workers team, answered a developer who had adopted KV as their datastore:

KV is not a distributed database and is really not intended as a database alternative at all. It's more meant for distributing bits of config globally. Cost aside, writes are way too slow for database-ish use

He pointed at Durable Object SQLite storage and at Hyperdrive instead. Take the sentence literally: bits of config. Flags, routing tables, rendered snapshots, allow-lists, prompt blocks. Not carts, not counters, not sessions that mutate, not anything two writers touch.

[[widget:0]]

Eventual consistency, in the exact words of the reference

The Workers Binding API reference states the write behaviour without softening it:

Due to the eventually consistent nature of KV, concurrent writes to the same key can end up overwriting one another.

and

Writes are immediately visible to other requests in the same global network location, but can take up to 60 seconds (or the value of the cacheTtl parameter of the get() or getWithMetadata() methods) to be visible in other parts of the world.

The read reference is equally blunt: get() and getWithMetadata() "may return stale values". The concepts page adds the trap most people miss — a miss is cached too:

Negative lookups indicating that the key does not exist are also cached, so the same delay exists noticing a value is created as when a value is changed.

So a location that asked for flag:new_checkout before you created it will keep answering null for up to sixty seconds after the key exists. Nothing retries on your behalf.

What a reader in another region actually sees after a write

"Usually" is the documentation's word, not a hedge added here: "At the Cloudflare global network location at which changes are made, these changes are usually immediately visible. However, this is not guaranteed and therefore it is not advised to rely on this behaviour." There is no read-after-write guarantee anywhere in KV, including at the writing location.

The safety rule, applied to real states

The rates, and the one that is ten times the others

Fetched from Cloudflare's KV pricing page today. All rates are per operation on a per-key basis; a bulk read of 50 keys is 50 billable reads.

Two consequences worth stating flatly. A write costs the same as ten reads. And a miss is billable: "All operations incur charges, including fetches for non-existent keys that return a null (Workers API) or HTTP 404 (REST API)." A cache-aside pattern that checks KV before hitting a database pays for every check, hit or miss. Egress is free.

Free-plan writes are the real cliff. One thousand writes a day is roughly one write every ninety seconds, sustained. Any per-request write pattern exhausts it before lunch.

[[widget:1]]

kondro's 2021 arithmetic still prices out correctly in 2026

Five years ago, on a Hacker News thread about R2 pricing, a commenter laid out the KV objection:

Workers KV is also eventually-consistent with no guarantee of read-after-write, which is a pretty big limitation compared to alternatives (S3 even has immediately-consistent list operations now after write).

The same comment put KV at $5 per million writes and $0.50 per million reads, called the reads pricier than S3's, and set that against Durable Object storage at $1 per million 4 KB writes with the Durable Object runtime cost stacked on top. Checked against today's published pages:

The one number that moved in KV's favour is nothing to do with KV: Durable Object storage now includes 50 million row writes a month against KV's 1 million. For a write-heavy key, a Durable Object is now cheaper and correct.

R2 is the other comparison people make and get wrong in KV's favour. R2 Class B operations — the reads — are $0.36 per million, cheaper than KV's $0.50, with 10 million a month free and 10 GB of storage free against KV's 1 GB. R2 loses on latency, not on price.

Bounding writes by putting the edge cache in front of KV

The write rate, not the read rate, is what turns a KV bill into a surprise. An operator running a share-link backend described the defence, in a thread about a Durable Object alarm loop that had burned $34,000 in eight days:

The key property is that caches.default with Cache-Control: max-age=3600 becomes a natural throttle — at most 24 cache misses per day per key, so KV writes are bounded by (keys × 24) regardless of traffic.

The mechanism, step by step:

1. The Worker checks caches.default first. A hit returns without touching KV at all — no read charge, no write charge.
2. Only a miss reaches KV. Only a miss can trigger the refresh write.
3. Cache-Control: max-age=3600 means a given key can only miss once an hour per cache location.
4. Therefore the write count per key is bounded by the number of cache expiries, not by the number of requests. Traffic can multiply by a thousand and the write bill does not move.

What it costs you: freshness. A value written now is invisible behind that cache for up to an hour, on top of KV's own propagation window. You are choosing a bounded bill over a bounded staleness, and you cannot have both.

This codebase runs the same pattern with a shorter window. functions/_middleware.js sets LASTGOOD_REFRESH_MS = 120000 and refreshLastGood() returns early when the stored snapshot is younger than that, so any one path writes its snapshot at most once per two minutes no matter how many misses arrive. The edge cache in front carries public, max-age=120, s-maxage=600, stale-while-revalidate=86400 for article pages. The measured result is in the last section: 12,231 writes a day across 6,568 snapshot keys, against a theoretical ceiling of 6,568 × 720 = 4.7 million.

The per-key boundaries, and the error you get at each one

The key-size limit is the one that bites in production because it fails late and looks like something else. A pull request against Cloudflare's own vinext framework describes it exactly:

When the assembled key exceeds Cloudflare KV's 512-byte key limit, handler.get throws a 414 before the wrapped function runs — so control-flow signals like notFound()/redirect() never fire, and the user sees a generic 200 error boundary instead of a 404.

Their fix is the one to copy: budget for your prefix (they used 480 bytes to leave room for <appPrefix>:cache:), keep short keys verbatim so they stay debuggable, and hash only the overflowing part.

An eventually-consistent store cannot hold a lock, and this application's locks are only safe because nobody is racing

The honest answer first. A lock needs compare-and-set: test that nobody holds it and take it, atomically, with no window between the test and the take. KV has no such primitive. get() then put() is two operations with a gap, and the reference already told you what happens in that gap — concurrent writes to the same key overwrite one another, last write wins, no error returned to the loser.

Three KV locks run in this application, all with the same shape:

• locks:deploy:loop-safe-miscsubjects — functions/_lib/fn_runners.js, the deployLease runner. Reads the key, returns ERR:deploy_lease:held: if a live lease exists, otherwise writes a lease with a random nonce and expirationTtl: 1800. Release requires presenting the matching nonce, so a stale holder cannot free somebody else's lease. scripts/ship.mjs takes this lease before every deploy.
• selftest:lock — functions/api/selftest.js. Same read-then-write, expirationTtl: 1800, with a 1,500,000 ms staleness window on the stored timestamp so an abandoned run does not block the next one forever.
• fclaim:* — advisory file claims so two coding agents do not edit the same file, default lease 90 minutes.

Each of these is a genuine race. Two acquire calls landing inside the same second both read no lease, both write, and the second write wins silently. What makes the pattern survivable here, and the condition must be said out loud:

These locks are safe only because contention is near zero. A deploy happens a few times a day, initiated by a human or one agent. A self-test run is a scheduled singleton. Two agents claiming the same file inside the same second is a coincidence, not a workload. Change any of those assumptions — a deploy fired by webhook on every push, a self-test on a one-minute cron — and the lock stops working, quietly, with no error to tell you.

The codebase already contains the correction for the case where contention is real. functions/_lib/idem_claim.js guards invoke idempotency, where duplicate parallel calls are the normal case rather than a coincidence, and its opening comment records why it is not in KV:

KV get→fire→put races: parallel identical calls all miss, all fire.

It uses INSERT OR IGNORE on a D1 table instead, where the primary key does the atomic test-and-set that KV cannot. That is the rule generalised: if two writers can plausibly arrive together, the lock goes in D1 or a Durable Object, not KV. Cloudflare's own guidance says the same thing — "KV is not ideal for applications where you need support for atomic operations or where values must be read and written in a single transaction."

[[widget:2]]

The topology teams settle on: authority elsewhere, KV as the replicated read copy

Asked how they ran a global read path, one operator described the shape that keeps recurring:

Cloudflare Workers KV has the simplest model, with a central-db that transparently and eventually only replicates read-only, hot-data specific to a DC but writes continue to incur heavy penalty

Their production system used DynamoDB in a single region as the source of truth, DynamoDB Streams pushing changes into Workers KV, and reads served from KV at the edge. Writes never touched KV directly. The reasons they gave were operations per second, cost and latency — and avoiding lock-in.

The generalised topology, and it is the one to copy:

1. Authority — a store with transactions: D1, a Durable Object, Postgres behind Hyperdrive, DynamoDB. All writes land here and here only.
2. Propagation — a change feed, a queue, or the write path itself pushes the new value into KV as a side effect. One writer per key, which is exactly what the reference recommends: "It is a common pattern to write data from a single process with Wrangler, Durable Objects, or the API. This avoids competing concurrent writes because of the single stream."
3. Read — every edge read hits KV. It is allowed to be a minute stale because the authority, not KV, is what anybody reconciles against.

Two field reports bracket the tradeoff. On the positive side, the author of an edge feature-flag system:

I mostly use KV for storing flags specific to each project (which gets replicated automatically). Everything else goes to D1 (replication isn't needed here).

On the negative side, the bind that pushes people into KV whether it fits or not:

You can use KV, with its trade-off of eventual consistency, or use something like FaunaDB or Firebase, but that means that the request has to wait for the request to the backing service.

Both are true at once. KV is the only storage on the platform that is already next to the Worker; everything else is a network hop. That is the whole reason people put things in it that do not belong there.

And a measured case of KV in the cache role paying off: an operator repeatedly tripping D1's 5 million daily row-read limit put a KV layer in front and reported back a week later — "I implemented KV-layered caching" — with reads down more than 80% and back under the limit. That is KV doing the job it is for. See D1 in this stack for the read-accounting model that makes those limits bite.

Where each kind of state belongs

The Cache API row deserves its own sentence because it is the cheapest option on the table and the most often skipped: caches.default costs nothing per operation, is not durable, and is scoped to one Cloudflare location. Put it in front of KV, as above, and it is what bounds the write bill.

Symptom, cause, fix

Measured on this account today

Five measurements taken against the live namespace bound as KV in wrangler.toml. Account id and namespace ids are redacted below; substitute your own. The consistency probe wrote two obviously-named temporary keys, tmp_consistency_probe_20260725 and tmp_consistency_probe_b_20260725, and both were deleted afterwards and verified gone (HTTP 404).

1. Namespaces on the account — 6.

npx wrangler kv namespace list

2. Keys in the production namespace — 6,773, of which 6,568 are page snapshots.

npx wrangler kv key list --namespace-id <NAMESPACE_ID> --remote > keys.json
python3 -c "import json;d=json.load(open('keys.json'));print(len(d))"

Prefix breakdown: lastgood: 6,568, sync: 35, trail: 33, share_use: 25, mcp_oauth: 18, idem: 6, then singletons. The longest key name measured 110 bytes against the 512-byte limit.

3. Stored bytes — 164.70 MB across the 1,041 snapshot keys that carry size metadata. refreshLastGood() writes {ts, bytes, ct} as KV metadata, so list() returns the size of every value it wrote without reading any of them.

python3 -c "import json;d=json.load(open('keys.json'));b=[k['metadata']['bytes'] for k in d if k.get('metadata',{}).get('bytes')];print(len(b),sum(b),max(b))"

Median value 155,154 bytes, largest 2,140,072 bytes — 8% of the 25 MiB ceiling. Extrapolating that mean across all 6,568 snapshot keys puts the namespace at roughly 1.01 GB, which is the 1 GB included allowance almost exactly; the overage at $0.50/GB-month is about half a cent. Treat the extrapolation as an estimate: the 5,527 older keys without metadata were not measured.

4. Seven days of real operations — 899,100 reads, 85,620 writes, 740 deletes, 160 lists. From Cloudflare's GraphQL analytics API, 2026-07-19 to 2026-07-26.

POST https://api.cloudflare.com/client/v4/graphql
{"query":"query { viewer { accounts(filter: {accountTag: \"<ACCOUNT_ID>\"}) {
  kvOperationsAdaptiveGroups(limit: 100, filter: {
    datetime_geq: \"2026-07-19T00:00:00Z\", datetime_leq: \"2026-07-26T00:00:00Z\",
    namespaceId: \"<NAMESPACE_ID>\"}) { sum { requests } dimensions { actionType } } } } }"}

The arithmetic that matters:

Writes are 8.7% of the operations and 48.5% of the gross cost. Extrapolated to a month: 3.85 million reads against the 10 million included, and 366,943 writes against the 1 million included — so the actual invoice line is $0.00. The write allowance is the binding constraint, with 2.7× headroom: 12,231 writes a day today, 33,333 a day before the meter starts.

[[widget:3]]

5. Write, then read, and time the gap — visible in 0.21 s and 0.30 s across two trials.

# seed the negative lookup at the reading location
for i in $(seq 1 6); do curl -s -o /dev/null -w "%{http_code} " \
  "https://miscsubjects.com/api/kv?key=tmp_consistency_probe_b_20260725" \
  -H "x-terminal-key: $TERMINAL_KEY"; sleep 2; done       # 404 404 404 404 404 404

npx wrangler kv key put tmp_consistency_probe_b_20260725 probe-b \
  --namespace-id <NAMESPACE_ID> --remote                   # real 1.14s

# poll every 0.5s until it appears
for i in $(seq 1 200); do code=$(curl -s -o /tmp/pb.txt -w "%{http_code}" \
  "https://miscsubjects.com/api/kv?key=tmp_consistency_probe_b_20260725" \
  -H "x-terminal-key: $TERMINAL_KEY"); \
  [ "$code" = "200" ] && break; sleep 0.5; done            # t+0.21s VISIBLE probe-b

Both trials converged in well under a second, including the trial that deliberately seeded six cached negative lookups first. This does not demonstrate read-after-write consistency and must not be read as one. It measures one reading location, close to the writer, twice. The documented window is a worst case, and the reference says explicitly that even same-location visibility "is not guaranteed". A system that happens to converge fast today is not a system you can design against.

Ten repeat reads of the same key through the deployed Worker, end to end over HTTPS from a laptop: minimum 136 ms, median 202 ms, maximum 260 ms. Almost all of that is network round trip, not KV — Cloudflare's own instrumentation puts the 90th percentile of KV Worker invocations "in less than 12 ms", and reports that the hottest 0.03% of keys, which serve over 40% of global KV requests, "resolve in under a millisecond".

An independent benchmark run from Cloudflare's Washington DC location (150 samples per metric, KV through the binding against Upstash Redis over HTTPS, same Worker, same request) put KV's hot read at 2.6 ms p50 — twice as fast as the competitor — and KV's single write at 171.8 ms p50, twenty-eight times slower. That single pair of numbers is the whole argument of this page in measured form: KV's reads are the best on the platform and its writes are the worst.

For where KV sits among the other bindings in this stack, see the Cloudflare stack index, Workers as the runtime and D1 as the relational store.

The next read-only inventory still shows snapshots dominating the namespace

Wrangler 4.103.0 listed the production namespace at 2026-07-26T05:45:59.424Z. Listing reads namespace metadata; it did not write, delete or fetch any value.

Largest prefix groups: lastgood: 6,568 · (singleton) 54 · sync: 35 · trail: 33 · share_use: 25 · mcp_oauth: 18. The inventory reproduces the architectural claim directly: 97% of all keys are regenerable lastgood: page snapshots, not transactional state.

Run the same inventory without exposing the namespace id in a transcript:

npx wrangler kv namespace list
npx wrangler kv key list --namespace-id <NAMESPACE_ID> --remote > keys.json
python3 -c "import json; d=json.load(open('keys.json')); print(len(d), max(len(k['name'].encode()) for k in d))"

The first number is the key count. The second is the longest key name in bytes.