Skip to content

SYSTEM Cited by 7 sources

Cloudflare Workers KV

Workers KV is Cloudflare's edge-distributed, eventually-consistent key-value store exposed as a first-class Workers binding (developers.cloudflare.com/kv). Reads are served from cache at Cloudflare edge POPs; writes propagate globally.

Two modes: classic vs Instant (2026-10-01)

As of 2026-10-01, Workers KV has two modes selected at namespace creation, exposing the same API over two different engines (Source: sources/2026-10-01-cloudflare-introducing-workers-kv-instant-powered-by-quicksilver):

  • Classic KV (default) — the eventually-consistent, edge-cached engine described throughout this page. Good for larger values written occasionally, read frequently; TTL-bounded staleness.
  • KV Instant ("mode": "instant") — powered by Quicksilver v2, Cloudflare's internal globally-replicated KV store ("nearly every request to Cloudflare looks up at least one key in Quicksilver"). Built for small, infrequently-updated, read-on-every-request configuration on the hot path (flags, settings).

This is a per-namespace realization of concepts/latency-critical-vs-latency-tolerant-workload inside one product: Instant is the latency-critical engine, classic KV the latency-tolerant / large / write-heavy one. "Each mode is designed for a very different type of data and access pattern."

Performance (Instant vs classic):

Metric KV Instant Classic KV
p99 reads (all) 1.62 ms 287 ms
p99 reads (cached) N/A 160 ms
Median write replication 107 ms (to 300+ edge locations) <1 s
p99 write replication 256 ms 4.38 s

Instant mode trade-offs (API + cost):

  • Single system of record for writes — writes funnel through one authoritative writer then fan out globally (leader/follower); this buys instant global visibility (no TTL) and strictly-ordered updates, and forces a one-write-per-namespace-per-second limit (classic KV's limit is per key). The per-namespace limit "makes it easier for you to reason about update order."
  • Inverted cost model — reads 60% cheaper ($0.20/M vs $0.50/M), but storage $100/MB-month (vs $0.50/GB-month) and Class A writes $0.10/op (vs $5.00/M). Read-heavy small-data workloads only.
  • Namespace caps — 1 MB total / 10,000 keys / 300-byte keys.
  • No metadata — getWithMetadata returns null; put carries no metadata.
  • list returns all keys, no pagination — one Class A op regardless of key count (tractable because of the 10,000-key cap).

See Quicksilver for the engine. KV Instant is the first customer-facing exposure of Quicksilver after "people have asked us for years."

Role

  • Low-latency read path for small values (config, feature flags, tokens, pre-computed content).
  • Eventually consistent: writes visible globally in seconds.
  • Binding-based access from Workers; no client-side KV driver.

Local / remote parity

KV is one of the binding types exposed through Local Explorer's local mirror of the Cloudflare API at /cdn-cgi/explorer/api, backed by local on-disk state managed by Miniflare (Source: sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare). Local namespaces are GUI-introspectable, seedable, and callable through the same KV API shape as remote.

As auth-token store (Artifacts, 2026-04-16)

In Artifacts, KV is the auth-token-tracking store used by the front-end Worker on every Git request: the token embedded in the HTTPS URL / header is looked up in KV before the request is routed to the per-repo Durable Object. Sits alongside R2 (pack-file snapshots) and DO SQLite (hot git objects) in the Artifacts storage stratification. Canonical wiki instance of KV as the edge-replicated low-latency authn lookup tier in front of a per-unit DO. See do-backed-git-server.

Seen in

  • sources/2026-10-01-cloudflare-introducing-workers-kv-instant-powered-by-quicksilver — canonical wiki instance of KV Instant mode (the Quicksilver-powered engine): same API, 100× faster p99 reads (1.62 ms), ~250 ms p99 global write replication to 300+ POPs, no TTL, single-system-of-record write path. Establishes KV + KV Instant as two modes for two data/access patterns under one API, and is the first customer-facing exposure of Quicksilver. The "config on the hot path" answer to the eventual-consistency ceiling that classic KV hit on the Browser Run allocation path below.
  • sources/2026-05-13-cloudflare-browser-run-now-running-on-cloudflare-containers-its-faster — canonical wiki instance of KV's eventual-consistency ceiling on an allocation hot path. Browser Run previously stored container-allocation state in KV. Under demand spikes from AI agent builders, KV's eventual-consistency window (recently reduced 60s → 30s minimum cache TTL via 2026-01-30 KV changelog, but explicitly "still too high" for this workload) caused race conditions and overallocation: "You might check KV, see a container as 'available,' but by the time you route to it (30 seconds later), it's already claimed." Migration to D1 + Queues resolved the failure mode at the cost of more architectural moving parts. KV remains useful for non-claim observability views in this architecture; the claim hot path is the specific surface KV doesn't fit. Canonical wiki instance of concepts/eventual-consistency
  • the pre-migration substrate for transactional-db-over-eventually-consistent-kv-for-claim.
  • sources/2025-11-18-cloudflare-outage-on-november-18-2025 — Workers KV returned significantly elevated HTTP 5xx during the outage because its "front end" gateway is served by the core proxy. At 13:05 UTC teams bypassed the core proxy for Workers KV (fallback to a prior core-proxy version), reducing impact on KV itself and on every downstream service relying on KV (notably Cloudflare Access and the Cloudflare Dashboard). Canonical wiki instance of Workers KV as a hub of control-plane dependency at Cloudflare: when KV is unavailable, the knock-on effects are fleet-wide.
  • sources/2026-04-13-cloudflare-building-a-cli-for-all-of-cloudflare — KV as a binding introspectable via Local Explorer.
  • sources/2026-04-16-cloudflare-artifacts-versioned-storage-that-speaks-git — KV as the auth-token store in front of per-repo DOs.
  • sources/2026-02-24-cloudflare-how-we-rebuilt-nextjs-with-ai-in-one-week — KV as the default ISR cache substrate for vinext via KVCacheHandler: setCacheHandler(new KVCacheHandler(env.MY_KV_NAMESPACE)). Also the destination of vinext's TPR pre-rendered output ("Pre-rendered 184 pages in 8.3 s → KV cache"). Canonical wiki instance of KV as an ISR cache tier + pluggable cache handler substrate.
  • sources/2026-04-17-cloudflare-introducing-flagship-feature-flags-built-for-the-age-of-ai — KV as the edge-replicated read tier for feature-flag configuration in Flagship (private beta 2026-04-17). From the post: "When you create or update a flag, the control plane writes the change atomically to a Durable Object … Within seconds, the updated flag config is synced to Workers KV, Cloudflare's globally distributed key-value store, where it's replicated across Cloudflare's network. When a request evaluates a flag, Flagship reads the flag config directly from KV at the edge — the same Cloudflare location already handling the request." Load- bearing property named by the post: "caching is managed for you, reads are local, and you don't need a persistent connection to keep things up to date. Cloudflare KV is a great primitive for this!" — KV replaces the in-process rules cache of traditional local-evaluation flag SDKs as the distribution primitive, because Workers isolates are not long-lived processes and an SDK-resident cache would have to bootstrap from scratch on every cold isolate. Canonical wiki instance of KV as the eventually-consistent edge-replicated config-read tier in the do-plus-kv-edge-config-distribution pattern (sibling of Artifacts' auth-token role but here KV holds the config, not auth).
Last updated · 766 distilled / 2,225 read