cloudflare-kv

Cloudflare Workers KV

Status: Production Ready ✅ | Last Verified: 2025-12-27

---

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 (Summary)

Key Limits:

• Key size: 512 bytes max
• Value size: 25 MB max
• Metadata: 1024 bytes max

Rate Limits:

• Writes: 1000/sec per key
• List: 100/sec per namespace
• Reads: Unlimited

For detailed limits, pricing, and optimization strategies, load references/limits-quotas.md

---

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

---

When to Load References

Load specific reference files based on task context:

For Setup & Configuration:

• Load references/setup-guide.md when creating namespaces or configuring bindings

For Performance Optimization:

• Load references/best-practices.md when implementing caching or optimizing performance
• Load references/performance-tuning.md for advanced optimization scenarios, cacheTtl strategies, or benchmarking

For API Usage:

• Load references/workers-api.md when implementing KV operations or need method signatures

For Troubleshooting:

• Load references/troubleshooting.md when debugging errors or consistency issues

For Limits & Quotas:

• Load references/limits-quotas.md when planning capacity or encountering quota errors

For Migration:

• Load references/migration-guide.md when migrating from localStorage, Redis, D1, R2, or other storage solutions

---

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
• troubleshooting.md - Comprehensive error catalog with solutions
• limits-quotas.md - Detailed limits, quotas, pricing, and optimization tips
• migration-guide.md - Complete migration guides from localStorage, Redis, D1, R2, and other storage solutions
• performance-tuning.md - Advanced cacheTtl strategies, bulk operations, key design, benchmarking techniques

Templates (templates/):

• kv-basic-operations.ts - Basic KV operations (get, put, delete, list)
• kv-caching-pattern.ts - HTTP caching with KV
• kv-list-pagination.ts - List with cursor pagination
• kv-metadata-pattern.ts - Metadata usage patterns
• wrangler-kv-config.jsonc - KV namespace bindings

Scripts (scripts/):

• check-versions.sh - Validate KV API endpoints and package versions
• test-kv-connection.sh - Test KV namespace connection and operations
• setup-kv-namespace.sh - Interactive namespace setup wizard
• validate-kv-config.sh - Validate wrangler.jsonc configuration
• analyze-kv-usage.sh - Analyze code for KV usage patterns and optimizations

Commands:

• /cloudflare-kv:setup - Interactive KV namespace setup wizard
• /cloudflare-kv:test - Test KV operations and connection
• /cloudflare-kv:optimize - Analyze and optimize KV usage

Agents:

• kv-optimizer - Analyzes KV usage and suggests performance optimizations
• kv-debugger - Helps debug KV errors and consistency issues

Examples (examples/):

• rate-limiting/ - Complete rate limiting implementation (fixed window, sliding window, token bucket, multi-tier)
• session-management/ - Production session store with TTL expiration, metadata tracking, and admin controls
• api-caching/ - HTTP response caching patterns (cache-aside, stale-while-revalidate, conditional caching, ETag)
• config-management/ - Feature flags, A/B testing, environment configs, version tracking, hot-reload

---

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