KV vs Durable Objects for Edge State

This guide is part of KV and Durable Object Caching at the Edge. It is a decision framework for the recurring question: should this piece of edge state live in Cloudflare Workers KV or in a Durable Object? The answer hinges on consistency, latency, write throughput, and cost — and choosing wrong produces stale reads, lost updates, or a bill you did not expect.

The problem

You are storing something from a Worker — a counter, a session flag, a cached fragment, a feature-flag map, a rate-limit window — and Cloudflare gives you two primitives that both look like “edge storage.” The KV store is the obvious default because it is simple and globally fast. But a class of workloads silently breaks on KV: anything that needs to read its own writes, increment atomically, or serialize access. Those belong in a Durable Object. Picking the right one upfront is far cheaper than migrating after a data-integrity incident.

Root cause: two different consistency models

KV and Durable Objects are not two flavors of the same database. They are built on opposite trade-offs.

KV is a globally replicated, read-optimized, eventually consistent store. A read is served from a replica in the local Point of Presence, so it is fast everywhere — single-digit milliseconds when warm. The cost is consistency: a write propagates to all edge locations within roughly 60 seconds, and read-after-write is not guaranteed even in the same isolate. Writes to a single key are rate-limited to about one per second. KV shines for read-heavy data that tolerates short staleness.

A Durable Object is a single, globally unique instance addressed by id. Every request for a given id is routed to the same instance, so all access is serialized and strongly consistent. You can read your own writes immediately, increment a counter without races, and hold a lock. The cost is locality: that single instance lives in one place, so a request from a distant region pays an extra network hop, and you pay for the duration the object stays active plus its storage operations.

The decision table

Step 1: Classify the access pattern

Ask three questions in order.

1. Does correctness depend on reading your own writes immediately? If yes → Durable Object. A rate-limit counter, a seat-reservation tally, or a one-time-token check cannot tolerate the ~60s KV window.
2. Do many writers touch the same key concurrently? If yes → Durable Object. KV’s ~1 write/s per-key limit and lack of atomic increment make concurrent writers lose updates.
3. Is it read-heavy, shared, and tolerant of short staleness? If yes → KV. Cached API responses, rendered fragments, and feature-flag maps that change rarely are textbook KV.

Step 2: Sketch the KV implementation

KV is the right call for a feature-flag map read on every request and updated rarely:

interface Env {
  FLAGS: KVNamespace;
}

export default {
  async fetch(_req: Request, env: Env): Promise<Response> {
    // Eventual consistency is fine: a flag change appearing within ~60s is acceptable.
    const flags = await env.FLAGS.get<Record<string, boolean>>("global", "json");
    const enabled = flags?.newCheckout ?? false;
    return new Response(JSON.stringify({ enabled }), {
      headers: { "content-type": "application/json" },
    });
  },
};

There is no coordination here — just a fast global read. KV is the cheaper, simpler choice.

Step 3: Sketch the Durable Object implementation

A per-user request counter must be exact, so it lives in a Durable Object addressed by user id:

export class RequestCounter implements DurableObject {
  constructor(private state: DurableObjectState) {}

  async fetch(_request: Request): Promise<Response> {
    // Serialized access: no two requests for this id run concurrently here.
    const current = (await this.state.storage.get<number>("count")) ?? 0;
    const next = current + 1;
    await this.state.storage.put("count", next);
    return new Response(JSON.stringify({ count: next }), {
      headers: { "content-type": "application/json" },
    });
  }
}

interface Env {
  COUNTER: DurableObjectNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const userId = new URL(request.url).searchParams.get("user") ?? "anon";
    const id = env.COUNTER.idFromName(userId); // same user → same instance
    return env.COUNTER.get(id).fetch(request);
  },
};

Because idFromName(userId) deterministically maps a user to one instance, the read-modify-write is race-free. The same pattern underpins token-bucket rate limiting at the edge.

Local vs production divergence

The trap is testing a concurrent-write workload on KV locally, seeing it pass because local KV is immediately consistent, and shipping a race that only appears under production’s eventual model.

Validation with Vitest

Assert the Durable Object increments atomically under sequential calls:

import { env, runInDurableObject } from "cloudflare:test";
import { describe, it, expect } from "vitest";

describe("RequestCounter", () => {
  it("increments without losing updates", async () => {
    const id = env.COUNTER.idFromName("user-1");
    const stub = env.COUNTER.get(id);
    const r1 = await stub.fetch("https://do/").then((r) => r.json());
    const r2 = await stub.fetch("https://do/").then((r) => r.json());
    expect(r1).toEqual({ count: 1 });
    expect(r2).toEqual({ count: 2 });
  });
});

Pitfalls

• Using KV as a counter. Concurrent get then put on KV loses increments and trips the ~1 write/s limit. Counters belong in a Durable Object.
• Putting read-heavy global config in a Durable Object. A single instance becomes a global bottleneck and a cross-region hop for every reader. Use KV for read-mostly shared data.
• Ignoring Durable Object cost shape. You pay for active duration; a chatty object kept alive by constant traffic costs more than the equivalent KV reads. Model it.
• Assuming KV read-after-write. Even same-isolate reads after a KV write may return the old value. Never gate logic on it.
• One Durable Object for everything. Sharding all state into a single id serializes unrelated traffic. Address objects by a natural key (user, room, tenant) to spread load.

Production deployment checklist

• Access pattern classified: read-your-writes or atomic → Durable Object; read-mostly shared → KV
• No counters, locks, or rate-limit windows stored in KV
• Durable Objects addressed by a natural key to avoid a single global bottleneck
• KV writes to any single key kept under ~1 write/s
• Durable Object cost modeled against active duration, not just request count
• Concurrency tested against production consistency, not just local emulation
• Values within limits (KV 25 MB per value)

Frequently Asked Questions

Related

• KV and Durable Object caching at the edge
• Caching API responses in Cloudflare KV
• Multi-tier CDN cache architecture
• Rate limiting and abuse prevention at the edge