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

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

### 2. Configure Binding

```jsonc
{
  "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

```typescript
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

```typescript
// 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

```typescript
// 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

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

### list() - List Keys

```typescript
// 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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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:**

```typescript
// 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 `refer