Skip to content
Back to Cloud Services

Cloudflare KV Key-Value Store

Globally distributed key-value store with eventual consistency, 25MB values, and edge reads in <10ms.

CloudflareBeginner

Why

KV reads are 1-10ms at the edge with 100k reads/day free. Perfect for config, feature flags, session tokens, and A/B test variants.

Write-once-read-many workloads cost nearly nothing.

When

Use KV for config, feature flags, sessions, rate-limit counters, and cached API responses. Avoid for data needing strong consistency, frequent writes, or relational queries.

How

1. Create namespace — wrangler kv:namespace create CONFIG (returns id) 2. Bind — [[kv_namespaces]] binding="CONFIG" id="..." 3. Write — env.CONFIG.put("key", "value", { expirationTtl: 3600 }) 4. Read — const v = await env.CONFIG.get("key") // string | null 5. List — env.CONFIG.list({ prefix: "user:" }) for prefixed keys 6. Bulk — wrangler kv:key put --namespace-id=... --path=./data.json 7. TTL — expirationTtl (seconds) or expirationDate (epoch), auto-delete

Example

// Feature flags via KV with edge reads export default { async fetch(request: Request, env: Env): Promise<Response> { const flags = JSON.parse(await env.CONFIG.get("feature_flags") || "{}"); if (flags.newCheckout && request.url.includes("/checkout")) { return env.NEW_CHECKOUT.fetch(request); } return env.LEGACY_CHECKOUT.fetch(request); }, }; // Session store with TTL async function setSession(env: Env, token: string, userId: string) { await env.SESSIONS.put(`sess:${token}`, userId, { expirationTtl: 86400 }); } async function getUser(env: Env, token: string) { return env.SESSIONS.get(`sess:${token}`); }

Common Problems

  • ⚠Eventual consistency ~60s — writes propagate globally slowly, stale reads possible
  • ⚠25MB value limit — large JSON must be chunked or moved to R2
  • ⚠list() slow on large namespaces — 1000 keys/call, paginate carefully

Best Practices

  • ✓Use Cache API for cacheable data — free, faster, respects HTTP caching semantics
  • ✓Prefix keys by tenant/region — list({prefix}) enables efficient scoped queries
  • ✓Store JSON not raw values — enables partial updates without read-modify-write races

FAQ

What is Cloudflare KV Key-Value Store and what problem does it solve?

Globally distributed key-value store with eventual consistency, 25MB values, and edge reads in <10ms. It lets developers deploy, store, and scale without self-managing infrastructure — a core reference for cloud service selection.

How do I get started with Cloudflare KV Key-Value Store in 5 minutes?

Two steps to run it: (1) Create namespace — wrangler kv:namespace create CONFIG (returns id); (2) Bind — [[kv_namespaces]] binding="CONFIG" id="...". Validate on the free tier first, then wire into production.

What is the #1 pitfall with Cloudflare KV Key-Value Store?

The most frequent issue is: Eventual consistency ~60s — writes propagate globally slowly, stale reads possible. Run a pre-launch checklist item by item, and add policy/config scanning in CI.

What are the best practices for Cloudflare KV Key-Value Store?

Best practices for Cloudflare KV Key-Value Store include: Use Cache API for cacheable data — free, faster, respects HTTP caching semantics; Prefix keys by tenant/region — list({prefix}) enables efficient scoped queries; Store JSON not raw values — enables partial updates without read-modify-write races. The first one — "Use Cache API for cacheable data — free, faster, respects HTTP caching semantics" — should be a team default baked into your IaC templates.

How do I control cost and avoid bill surprises with Cloudflare KV Key-Value Store?

Three ways to prevent overspend: (1) tag every resource with env/team and enable billing alarms; (2) set budget thresholds to trigger Slack/email alerts; (3) review idle resources in Cost Explorer regularly and clean them up. Most Cloudflare KV Key-Value Store options offer a free tier — validate within free quota before scaling.