Using Cloudflare Workers KV for Edge‑Side Key‑Value Storage

Why use Cloudflare Workers KV for edge data

When a Workers script needs data that is read frequently but updated rarely, storing it in a centralized database adds network round‑trips that can erase the latency advantage of running at the edge. Cloudflare Workers KV provides a globally replicated key‑value store that lives in every Cloudflare data center, so a read can be served from the location closest to the user with sub‑millisecond delay.

Setting up a KV namespace and binding it to a Worker

1. Create a namespace. In the Cloudflare dashboard go to Workers & Pages → KV → Create a namespace, or run wrangler kv:namespace create MY_KV and note the generated ID.
2. Add the binding to your project’s wrangler.toml:

name = "my-worker"
main = "src/index.js"

[[kv_namespaces]]
binding = "MY_KV"
id = ""

The binding value becomes the variable name you use in your Worker code.

Example Worker script

The following script demonstrates a simple read‑write API. A GET request returns the value for a key; a POST request stores the request body as the value with an optional TTL.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    const key = url.pathname.slice(1); // strip leading slash

    if (request.method === "GET") {
      const value = await env.MY_KV.get(key);
      if (value === null) {
        return new Response("Key not found", { status: 404 });
      }
      return new Response(value, { headers: { "Content-Type": "text/plain" } });
    }

    if (request.method === "POST") {
      const payload = await request.text();
      // with a TTL of one hour (3600 seconds)
      await env.MY_KV.put(key, payload, { expirationTtl: 3600 });
      return new Response("Stored", { status: 200 });
    }

    return new Response("Method not allowed", { status: 405 });
  },
};

Limits and common pitfalls

• Eventual consistency: A write may take a few seconds to propagate to all edge locations. A read performed immediately after a write from a different POP can return the stale value. Do not rely on KV for use‑cases that require read‑after‑write consistency.
• Payload size: Both keys and values are limited to 1 MiB. Larger blobs should be stored in Cloudflare R2 or another object store.
• Write throughput: Each namespace sustains about 200 write operations per second (burstable). Exceeding this rate results in HTTP 429 responses; implement retry‑with‑backoff or consider sharding across multiple namespaces.
• Storage capacity: A single namespace can hold up to 10 GB of data. For larger datasets, split logical groups into separate namespaces.
• Forgotten binding: If the namespace ID is missing or incorrectly copied into wrangler.toml, the Worker will throw a binding error at runtime. Verify the binding by checking the Workers dashboard → Settings → Variables.
• TTL mismanagement: Keys without an explicit TTL remain until manually deleted. If you intend data to expire, always pass expirationTtl (or expiration) when calling put.

Verifying the setup

After deploying the Worker, you can confirm that reads and writes work as expected:

1. Write a value: curl -X POST -d "test-value" https://.workers.dev/test-key
2. Read the value: curl https://.workers.dev/test-key should return "test-value".
3. In the Cloudflare dashboard, navigate to Workers & Pages → KV → → Management to see the key appear and check its size and TTL.

If you receive a 429 error during repeated writes, you have hit the write‑rate limit; reduce the request frequency or distribute writes across additional namespaces.