Cloudflare Workers KV

Globally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.

Overview

KV provides:

Eventual consistency (60s global propagation)
Read-optimized performance
25 MiB value limit per key
Auto-replication to Cloudflare edge
Metadata support (1024 bytes)

Use cases: Config storage, user sessions, feature flags, caching, A/B testing

When to Use KV

Need	Recommendation
Strong consistency	→ Durable Objects
SQL queries	→ D1
Object storage (files)	→ R2
High read, low write volume	→ KV ✅
Sub-10ms global reads	→ KV ✅

Quick comparison:

Feature	KV	D1	Durable Objects
Consistency	Eventual	Strong	Strong
Read latency	<10ms	~50ms	<1ms
Write limit	1/s per key	Unlimited	Unlimited
Use case	Config, cache	Relational data	Coordination

Quick Start

wrangler kv namespace create MY_NAMESPACE
# Add binding to wrangler.jsonc

// Write
await env.MY_KV.put("key", "value", { expirationTtl: 300 });

// Read
const value = await env.MY_KV.get("key");
const json = await env.MY_KV.get<Config>("config", "json");

Core Operations

Method	Purpose	Returns
`get(key, type?)`	Single read	`string \| null`
`get(keys, type?)`	Bulk read (≤100)	`Map<string, T \| null>`
`put(key, value, options?)`	Write	`Promise<void>`
`delete(key)`	Delete	`Promise<void>`
`list(options?)`	List keys	`{ keys, list_complete, cursor? }`
`getWithMetadata(key)`	Get + metadata	`{ value, metadata }`

Consistency Model

Write visibility: Immediate in same location, ≤60s globally
Read path: Eventually consistent
Write rate: 1 write/second per key (429 on exceed)

Reading Order

Task	Files to Read
Quick start	README → configuration.md
Implement feature	README → api.md → patterns.md
Debug issues	gotchas.md → api.md
Batch operations	api.md (bulk section) → patterns.md
Performance tuning	gotchas.md (performance) → patterns.md (caching)

In This Reference

configuration.md - wrangler.jsonc setup, namespace creation, TypeScript types
api.md - KV methods, bulk operations, cacheTtl, content types
patterns.md - Caching, sessions, rate limiting, A/B testing
gotchas.md - Eventual consistency, concurrent writes, value limits

README.md