Cloudflare Workers KV

Status: Production Ready ✅ | Last Verified: 2025-11-21

---

What Is Workers KV?

Global key-value storage on Cloudflare edge:

• Eventually consistent
• Low latency worldwide
• 1GB+ values supported
• TTL expiration
• Metadata support

---

Quick Start (5 Minutes)

1. Create KV Namespace

bunx wrangler kv namespace create MY_NAMESPACE
bunx wrangler kv namespace create MY_NAMESPACE --preview

2. Configure Binding

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-11",
  "kv_namespaces": [
    {
      "binding": "MY_NAMESPACE",
      "id": "<PRODUCTION_ID>",
      "preview_id": "<PREVIEW_ID>"
    }
  ]
}

3. Basic Operations

export default {
  async fetch(request, env, ctx) {
    // Write
    await env.MY_NAMESPACE.put('key', 'value');

    // Read
    const value = await env.MY_NAMESPACE.get('key');

    // Delete
    await env.MY_NAMESPACE.delete('key');

    return new Response(value);
  }
};

Load references/setup-guide.md for complete setup.

---

KV API Methods

put() - Write

// Basic
await env.MY_NAMESPACE.put('key', 'value');

// With TTL (1 hour)
await env.MY_NAMESPACE.put('key', 'value', {
  expirationTtl: 3600
});

// With expiration timestamp
await env.MY_NAMESPACE.put('key', 'value', {
  expiration: Math.floor(Date.now() / 1000) + 3600
});

// With metadata
await env.MY_NAMESPACE.put('key', 'value', {
  metadata: { role: 'admin', created: Date.now() }
});

get() - Read

// Simple get
const value = await env.MY_NAMESPACE.get('key');

// With type
const text = await env.MY_NAMESPACE.get('key', 'text');
const json = await env.MY_NAMESPACE.get('key', 'json');
const buffer = await env.MY_NAMESPACE.get('key', 'arrayBuffer');
const stream = await env.MY_NAMESPACE.get('key', 'stream');

// With metadata
const { value, metadata } = await env.MY_NAMESPACE.getWithMetadata('key');

delete() - Remove

await env.MY_NAMESPACE.delete('key');

list() - List Keys

// Basic list
const { keys } = await env.MY_NAMESPACE.list();

// With prefix
const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

// Pagination
const { keys, cursor } = await env.MY_NAMESPACE.list({
  cursor: previousCursor
});

---

Critical Rules

Always Do ✅

1. Use TTL for temporary data
2. Handle null (key might not exist)
3. Use metadata for small data
4. Paginate lists (max 1000 keys)
5. Use prefixes for organization
6. Cache in Worker (avoid multiple KV calls)
7. Use waitUntil() for async writes
8. Handle eventual consistency
9. Monitor rate limits
10. Use JSON.stringify for objects

Never Do ❌

1. Never assume instant consistency
2. Never exceed 25MB per value
3. Never list all keys without pagination
4. Never skip error handling
5. Never use for real-time data
6. Never exceed rate limits (1000 writes/second)
7. Never store secrets unencrypted
8. Never use as database (no transactions)
9. Never ignore metadata limits (1024 bytes)
10. Never skip TTL for temporary data

---

Common Use Cases

Use Case 1: API Response Caching

const cacheKey = `api:${url}`;
let cached = await env.MY_NAMESPACE.get(cacheKey, 'json');

if (!cached) {
  cached = await fetch(url).then(r => r.json());
  await env.MY_NAMESPACE.put(cacheKey, JSON.stringify(cached), {
    expirationTtl: 300  // 5 minutes
  });
}

return Response.json(cached);

Use Case 2: User Preferences

const userId = '123';
const preferences = {
  theme: 'dark',
  language: 'en'
};

await env.MY_NAMESPACE.put(
  `user:${userId}:preferences`,
  JSON.stringify(preferences),
  {
    metadata: { updated: Date.now() }
  }
);

Use Case 3: Rate Limiting

const key = `ratelimit:${ip}`;
const count = parseInt(await env.MY_NAMESPACE.get(key) || '0');

if (count >= 100) {
  return new Response('Rate limit exceeded', { status: 429 });
}

await env.MY_NAMESPACE.put(key, String(count + 1), {
  expirationTtl: 60  // 1 minute window
});

Use Case 4: List with Prefix

const { keys } = await env.MY_NAMESPACE.list({
  prefix: 'user:',
  limit: 100
});

const users = await Promise.all(
  keys.map(({ name }) => env.MY_NAMESPACE.get(name, 'json'))
);

Use Case 5: waitUntil() Pattern

export default {
  async fetch(request, env, ctx) {
    // Don't wait for KV write
    ctx.waitUntil(
      env.MY_NAMESPACE.put('analytics', JSON.stringify(data))
    );

    return new Response('OK');
  }
};

---

Limits

Storage:

• Max key size: 512 bytes
• Max value size: 25 MB
• Max metadata size: 1024 bytes
• Max keys per namespace: Unlimited

Operations:

• Read: Unlimited
• Write: 1000/second per key
• Delete: 1000/second per key
• List: 100/second

Pricing:

• Free tier: 100,000 reads/day, 1,000 writes/day
• Paid: $0.50/1M reads, $5/1M writes

---

Eventual Consistency

KV is eventually consistent:

• Writes propagate globally (~60 seconds)
• Not suitable for real-time data
• Use D1 for strong consistency

Pattern:

// Write
await env.MY_NAMESPACE.put('key', 'value');

// May not be visible immediately in other regions
const value = await env.MY_NAMESPACE.get('key');  // Might be null

---

Resources

References (references/):

• best-practices.md - Production patterns, caching strategies, rate limit handling, error recovery
• setup-guide.md - Complete setup with Wrangler CLI commands, namespace creation, bindings configuration
• workers-api.md - Complete API reference, consistency model (eventual consistency), limits & quotas, performance optimization

Templates (templates/):

• basic-kv-worker.ts - Basic KV operations (get, put, delete, list)
• cache-pattern.ts - HTTP caching with KV
• session-store.ts - Session management example

---

Official Documentation

• KV Overview: https://developers.cloudflare.com/kv/
• KV API: https://developers.cloudflare.com/kv/api/
• Best Practices: https://developers.cloudflare.com/kv/best-practices/

---

Questions? Issues?

1. Check references/setup-guide.md for complete setup
2. Verify namespace binding configured
3. Handle eventual consistency
4. Check rate limits