Skip to content

PATTERN Cited by 2 sources

DO-plus-KV edge config distribution

A DO-plus-KV edge config distribution is the recurring Cloudflare architecture for hot-read, rare-write configuration surfaces: a per-unit Durable Object holds the source of truth (SQLite-backed, single-writer, with an embedded changelog); a globally-replicated Workers KV holds a synced copy that edge isolates read from on every request. Writes are atomic at the DO; reads are edge-local from KV.

The pattern

   ┌──────────────┐     write (atomic)       ┌────────────┐
   │ Control plane├──────────────────────────▶│  DO (per   │
   │ (dashboard,  │                           │  app/unit) │
   │  API, agent) │                           │  SQLite    │
   └──────────────┘                           │  config +  │
                                              │  changelog │
                                              └─────┬──────┘
                                                    │  sync "within seconds"
                                                    ▼
                                              ┌────────────┐
                                              │ Workers KV │
                                              │ (global,   │
                                              │  replicated│
                                              │  across    │
                                              │  edge POPs)│
                                              └─────┬──────┘
                                                    │  edge-local read
                                                    ▼
                                              ┌────────────┐
                                              │ Request on │
                                              │ Worker     │
                                              │ isolate at │
                                              │ edge POP   │
                                              └────────────┘

Why not just KV? Why not just DO?

KV alone can't be the source of truth — it's eventually consistent across POPs; two concurrent control-plane writes to the same key would race. Audit trails ("field-level diffs") require a transactional single-writer.

DO alone can't be the read path — every request would have to route to the unique DO instance for that app (which lives in one Cloudflare region), blowing up request latency and defeating the edge. DOs are single-writer by construction; they're a chokepoint for writes, not a global-read surface.

Pairing gives both:

  • DO = write-side consistency — atomic, single-writer, holds the changelog. One canonical instance per app/unit.
  • KV = edge-local reads — replicated globally, cached by the platform, read in-isolate with no outbound hop.

The trade-off is bounded staleness: writes take "within seconds" to propagate DO → KV. Acceptable for config, feature flags, auth-token tables, plan metadata — not for anything that needs read-your-writes across regions.

Load-bearing guarantees

  • Atomic write — the DO absorbs the control-plane write. No partial-state readers.
  • Eventual fan-out — async DO → KV replication; the exact SLO isn't published ("within seconds") but the window is bounded.
  • Local reads forever — once KV has the new value, every edge POP serves it from local cache; no long-lived SDK process required. This is especially load-bearing on Workers where isolates can be evicted between requests (see patterns/in-isolate-rule-evaluation).
  • Changelog co-located with source of truth — the DO is the natural home for an audit trail because it's single-writer and all writes flow through it.

Canonical instances

Cloudflare Flagship (2026-04-17)

Flagship is the reference instantiation. From the launch post:

"When you create or update a flag, the control plane writes the change atomically to a Durable Object — a SQLite-backed, globally unique instance that serves as the source of truth for that app's flag configuration and changelog. 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." (Source: sources/2026-04-17-cloudflare-introducing-flagship-feature-flags-built-for-the-age-of-ai)

Per-app DO + global KV + in-isolate evaluator = flag service.

Cloudflare Artifacts (2026-04-16)

Artifacts uses the sibling shape patterns/do-backed-git-server but with a different KV-side role: one DO per Git repo holds the repository; KV stores auth tokens that the front-end Worker looks up on every Git request before routing to the DO. Source of truth for repo content = DO; source of truth for auth-token → repo binding = KV (replicated, eventually consistent, tolerable for auth-lookup cache because tokens are revocable and short-lived).

Where the pattern doesn't fit

  • Strong-consistency cross-region reads — KV's eventual-consistency window blocks this. Use DO directly and accept the routing hop.
  • Very large values — KV has per-entry size limits; big blobs go to R2 (see Artifacts' pack-file spillover).
  • High write rate per key — DO single-writer serialises all writes to one key-space; concurrent writers serialize through one DO.

Relationship to adjacent patterns

  • patterns/in-isolate-rule-evaluation — the read-side complement: the evaluator runs in the same V8 isolate as the request handler, reading config out of edge-local KV.
  • patterns/do-backed-git-server — sibling architecture where the DO itself holds per-unit state (a full Git repo) and KV plays the cross-cutting auth-table role.
  • patterns/global-configuration-push — an orthogonal config-distribution shape Cloudflare uses elsewhere (fleet- wide push-based delivery, seconds to fleet); DO-plus-KV is the pull-from-edge-local-cache alternative, which doesn't require every edge node to be push-addressable.

Seen in

Last updated · 200 distilled / 1,178 read