Quick Mental Model
KV Namespace = The actual database/storage (has ID like abc123def456)
Binding = Variable name in your code (like TODO, USERS)
Key-Value Store = Simple hash map, not a relational database
Eventually Consistent = Changes take time to propagate globally (up to 60 seconds)
Optimized for reads = Great for caching, not for frequent writes
Configuration
wrangler.jsonc
{
"name": "my-worker",
"kv_namespaces": [
{
"binding": "TODO",
"id": "06779da6940b431db6e566b4846d64db",
"preview_id": "06779da6940b431db6e566b484a6a7"
}
]
}
Development Commands
wrangler dev
wrangler dev --remote
wrangler deploy
Core Operations
Basic String Operations
await env.TODO.put("task:123", "Buy groceries");
let value = await env.TODO.get("task:123");
await env.TODO.delete("task:123");
JSON Operations
const task = { id: 123, title: "Buy groceries", done: false };
await env.TODO.put("task:123", JSON.stringify(task));
let taskJson = await env.TODO.get("task:123");
const task = taskJson ? JSON.parse(taskJson) : null;
const task = await env.TODO.get("task:123", "json");
const task = await env.TODO.get("task:123", "json");
if (task) {
task.done = true;
await env.TODO.put("task:123", JSON.stringify(task));
}
Expiration
Time-based Expiration
await env.TODO.put("session:abc", sessionData, {
expirationTtl: 3600,
});
const midnight = new Date();
midnight.setHours(24, 0, 0, 0);
await env.TODO.put("daily-stats", statsData, {
expiration: Math.floor(midnight.getTime() / 1000),
});
Common TTL Values
60 = 1 minute
300 = 5 minutes
3600 = 1 hour
86400 = 24 hours
604800 = 1 week
await env.TODO.put("user:123", userData, {
metadata: {
version: 1,
lastUpdated: Date.now(),
source: "api",
},
expirationTtl: 3600,
});
const result = await env.TODO.getWithMetadata("user:123", "json");
if (result.value !== null) {
const user = result.value;
const meta = result.metadata;
}
Key Naming Patterns
Good Patterns
"user:123:profile";
"user:123:settings";
"user:123:sessions:abc";
"cache:weather:london:2025-08-09";
"api:github:users:123";
"feature:new-ui:production";
"feature:beta-test:enabled";
"ratelimit:192.168.1.1:2025-08-09-14";
Avoid These
"user 123 profile";
"user@123#profile";
"john_profile";
"userprofilejohn";
Listing Keys
Basic List
const result = await env.TODO.list();
List with Prefix
const userKeys = await env.TODO.list({ prefix: "user:123:" });
let allKeys = [];
let cursor = undefined;
do {
const result = await env.TODO.list({
prefix: "user:",
limit: 100,
cursor: cursor,
});
allKeys.push(...result.keys);
cursor = result.cursor;
} while (result.truncated);
⚠️ Warning: list() only returns key names and metadata, NOT values. Still need get() for actual data.
Error Handling
Safe JSON Reading
try {
const data = await env.TODO.get("user:123", "json");
if (data === null) {
return new Response("Not found", { status: 404 });
}
} catch (error) {
if (error.message.includes("JSON")) {
await env.TODO.delete("user:123");
return new Response("Data corrupted", { status: 422 });
}
return new Response("Service unavailable", { status: 503 });
}
Defensive Patterns
const preferences = (await env.TODO.get("user:123:prefs", "json")) || {
theme: "light",
notifications: true,
};
const theme = (preferences && preferences.theme) || "light";
Common Use Cases
Caching API Responses
const cacheKey = `api:weather:${city}`;
let weather = await env.TODO.get(cacheKey, "json");
if (!weather) {
const response = await fetch(`https://api.weather.com/${city}`);
weather = await response.json();
await env.TODO.put(cacheKey, JSON.stringify(weather), {
expirationTtl: 300,
});
}
return new Response(JSON.stringify(weather));
Session Management
await env.TODO.put(
`session:${sessionId}`,
JSON.stringify({
userId: 123,
loginTime: Date.now(),
}),
{ expirationTtl: 3600 }
);
const session = await env.TODO.get(`session:${sessionId}`, "json");
if (!session) {
return new Response("Session expired", { status: 401 });
}
Feature Flags
await env.TODO.put("feature:new-ui:enabled", "true");
const enabled = (await env.TODO.get("feature:new-ui:enabled")) === "true";
if (enabled) {
}
Rate Limiting
const minute = Math.floor(Date.now() / 60000);
const rateLimitKey = `ratelimit:${ip}:${minute}`;
let requests = await env.TODO.get(rateLimitKey);
requests = requests ? parseInt(requests) + 1 : 1;
if (requests > 100) {
return new Response("Rate limited", { status: 429 });
}
await env.TODO.put(rateLimitKey, requests.toString(), {
expirationTtl: 60,
});
Limits and Gotchas
Size Limits
Reads: Very fast (especially after first access)
Writes: Eventually consistent (up to 60 seconds globally)
List operations: Slow and expensive, avoid in hot paths
Eventually Consistent Behavior
Changes visible immediately at write location
May take 60+ seconds to appear in other regions
Negative lookups (key doesn't exist) are also cached
If you create a key after checking it doesn't exist, other regions might still return null
When NOT to Use KV
❌ Avoid KV for:
Frequent updates to same key (>10/second)
Transactions or atomic operations
Complex queries or relationships
Real-time consistency requirements
Large datasets you need to iterate through
✅ Perfect for:
