Cloudflare Workers KV in Practice: A Complete Guide to Distributed Key-Value Storage

At 3 AM, I found myself staring at the latency curve in my Cloudflare Dashboard. That red line was still hovering above 200ms—despite using Workers, despite the code being optimized, why was every user request still taking so long?

The problem was the database. Every session query had to travel from the edge node to a data center in Europe and back. Even though Workers execution took only 5ms, network transmission was eating up all the time.

Later I realized: Workers themselves are stateless. You need a storage solution that truly “lives at the edge”—Cloudflare Workers KV.

In this article, I want to share all the pitfalls I’ve encountered, the benchmarks I’ve run, and the code I’ve written. From what KV actually is and why it achieves sub-10ms latency, to complete implementations for session storage and API cache. I’ll also discuss when to use KV versus when D1 or R2 might be a better fit—this choice is actually quite critical.

What is KV — Understanding Distributed Edge Storage

Simply put, KV is a “pocket memory” Cloudflare provides for Workers. This memory isn’t stored in some fixed data center—it’s distributed across 300+ edge nodes worldwide. A user request from Tokyo? The data might already be waiting in Tokyo’s edge node. A request from Frankfurt? The data could already be cached in Frankfurt.

Cloudflare Workers KV is a globally distributed key-value store designed specifically for edge computing. It has three core characteristics:

Ultra-fast reads. Hot keys achieve cache hit latency between 500µs to 10ms—honestly, I was skeptical when I first saw this number until I ran my own benchmarks, which confirmed stable single-digit millisecond latency.

Global replication. When you write a piece of data, it gets replicated to all edge nodes worldwide. This differs from Redis clusters—KV’s data model is “write once, read anywhere,” making it ideal for read-heavy workloads.

High throughput. A single key can handle thousands of reads per second (RPS) because data is cached at the edge, eliminating the need to fetch from origin each time.

Cloudflare Storage Ecosystem Comparison

KV is just one piece of the Cloudflare storage matrix. Let’s look at the complete picture:

Storage Service	Data Model	Best For	Write Limit	Latency Characteristics
KV	Key-Value	Session, Cache, Config	1 RPS/key	hot keys 500µs-10ms
D1	SQL (SQLite)	User data, Orders, Reports	No hard limit	Depends on location, typically 50-200ms
R2	Object Storage	Files, Images, Videos	No hard limit	Fast downloads, uploads depend on file size
Durable Objects	Stateful Objects	Collaborative editing, WebSocket	No hard limit	Requires routing to specific node

Looking at this table, you might wonder: What does “1 RPS/key” mean? I’ll explain this in detail later—simply put, each key can only be written once per second, which is KV’s most critical limitation to keep in mind.

KV Use Case Quick Reference

When should you consider KV? Here’s a simple guideline:

Recommended for KV:

• Session storage (user login state)
• API response cache (third-party API return values)
• Rate limiting counters
• Feature flags / configuration data
• Redirect mapping (URL redirect rules)

Not recommended for KV:

• Frequently written data (e.g., real-time counters exceeding 1 RPS)
• Complex data requiring SQL queries (user tables, order tables—use D1)
• Large file storage (images, videos—use R2)
• Financial transaction data requiring strong consistency (use Durable Objects)

Cloudflare’s official documentation states it clearly: KV is suitable for scenarios with “high read rates, low modification frequency, and no need for immediate consistency.” Authentication frameworks like OpenAuth also use KV as their default session storage—I’ll provide complete implementation code for this later.

KV Architecture Deep Dive — Why It’s So Fast

KV’s speed isn’t magic—it’s the result of a three-layer cache architecture.

Imagine you’re buying something at a convenience store. In the ideal scenario, the item is right on the shelf next to the counter—you just reach out and grab it (edge cache). A bit slower, the item is in the back warehouse, and the clerk has to go get it (regional cache). The slowest scenario: the item is at the central warehouse, and you have to wait for a truck to deliver it (central store).

KV’s architecture has these three layers:

Request → Edge Cache (Fastest)
           ↓ Miss
         Regional Cache
           ↓ Miss
         Central Store (Slowest)

According to Cloudflare’s October 2025 blog data, approximately 30% of requests can be resolved directly at the cache layer. This means one-third of reads never need to travel back to central storage—latency naturally drops.

Performance Data: From Official to Real-World Testing

Cloudflare’s official documentation provides reference data:

• Hot keys (frequently accessed keys): 500µs to 10ms
• Cold keys (first access or rarely accessed): Higher latency, requires origin fetch

Honestly, I was skeptical about the “500µs” figure at first. So I tested it myself:

// Simple latency test code
const start = Date.now();
await env.KV.get("test-key");
const latency = Date.now() - start;
console.log(`Latency: ${latency}ms`);

After 100 tests, hot keys averaged 5-8ms latency. Cold keys took 50ms+ on first access, but dropped significantly on the second access—the cache kicked in.

In 2025, Cloudflare overhauled KV. According to official blog data, operation speed improved 3x. Two main changes:

1. Workers connect directly to KV, bypassing the original Front Line layer
2. Simplified internal data transfer paths

This change also created cascading benefits for other Cloudflare services that depend on KV (like Turnstile, Waiting Room).

Consistency Model: The Cost of Eventual Consistency

KV is an eventually consistent storage. What does this mean?

When you write a piece of data, it doesn’t immediately appear at all edge nodes. Propagation takes time—official documentation doesn’t give exact numbers, but in practice, cross-region propagation typically takes a few seconds to tens of seconds.

This characteristic is problematic in some scenarios but completely irrelevant in others:

Problematic Scenarios:

• User just logged in, session written to KV, but another request hits a different edge node and can’t read the session—login “fails”
• Real-time collaborative editing, User A makes changes, User B immediately reads but doesn’t see the latest content

Non-Problematic Scenarios:

• Feature flags configuration—waiting a few seconds for changes to take effect is completely OK
• API cache—caching third-party API return values for a few minutes, propagation delay doesn’t matter
• Redirect mapping—URL rules updating a few seconds slower, users barely notice

If your scenario requires immediate consistency, KV might not be suitable. In this case, Durable Objects would be a better choice—it routes to a specific node, guaranteeing state consistency.

Wrangler CLI Configuration in Practice

Theory covered, let’s get hands-on.

KV configuration has two parts: creating a namespace, then binding it to your Worker in wrangler.toml.

Creating a Namespace

A namespace is a “container” for KV—each namespace can store countless key-value pairs, but an account can only have 1000 namespaces total (this limit was raised from 200 to 1000 in early 2025).

# Create production namespace
wrangler kv namespace create MY_KV

# Output looks like this:
# Created namespace with id "abc123def456..."
# Add the following to your wrangler.toml:
# [[kv_namespaces]]
# binding = "MY_KV"
# id = "abc123def456..."

You’ll also need a preview namespace for local development testing:

# Create preview namespace
wrangler kv namespace create MY_KV --preview

# Output similar to:
# Created preview namespace with id "preview_abc123..."

wrangler.toml Configuration Explained

Add the id from the output above to your wrangler.toml:

name = "my-worker"
main = "src/index.ts"

[[kv_namespaces]]
binding = "MY_KV"
id = "abc123def456..."        # production namespace
preview_id = "preview_abc123..." # preview namespace (for local development)

The binding name is important. It determines how you access KV in your Worker code:

// binding = "MY_KV", so in code it's env.MY_KV
const value = await env.MY_KV.get("some-key");

REST API vs Workers Binding API

There are two ways to access KV data:

Workers Binding API (recommended):

• Use env.MY_KV.get() directly in Worker
• No additional network requests, fastest speed
• Completely free (only counts toward Worker execution time)

REST API:

• Access KV via HTTP requests
• Requires authentication token, suitable for external system calls
• Subject to Cloudflare REST API overall rate limits

Honestly, most scenarios should use the Binding API. REST API is mainly for:

• External systems needing to read/write KV data
• Batch importing data in CI/CD workflows
• Temporary debugging and operations

Common Wrangler KV Commands

Wrangler provides a set of command-line tools for convenient KV data operations:

# Write data
wrangler kv key put --namespace-id=abc123 "my-key" "my-value"

# Read data
wrangler kv key get --namespace-id=abc123 "my-key"

# Delete data
wrangler kv key delete --namespace-id=abc123 "my-key"

# List all keys (supports prefix filtering)
wrangler kv key list --namespace-id=abc123 --prefix="session:"

These commands are useful during debugging, but in production environments, Worker code operations are more efficient.

TypeScript Code in Practice

Finally, the code section. I’ll give you complete, runnable examples.

Basic CRUD Operations

Let’s start with the most basic create, read, update, delete:

// src/index.ts
interface Env {
  MY_KV: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const path = url.pathname;

    // Write data
    if (path === "/put") {
      const key = url.searchParams.get("key") || "default";
      const value = url.searchParams.get("value") || "hello";
      
      await env.MY_KV.put(key, value);
      return new Response(`Saved: ${key} = ${value}`);
    }

    // Read data
    if (path === "/get") {
      const key = url.searchParams.get("key") || "default";
      const value = await env.MY_KV.get(key);
      
      if (value === null) {
        return new Response("Key not found", { status: 404 });
      }
      return new Response(value);
    }

    // Delete data
    if (path === "/delete") {
      const key = url.searchParams.get("key") || "default";
      await env.MY_KV.delete(key);
      return new Response(`Deleted: ${key}`);
    }

    // List keys (with prefix)
    if (path === "/list") {
      const prefix = url.searchParams.get("prefix") || "";
      const keys = await env.MY_KV.list({ prefix });
      
      const keyList = keys.keys.map(k => k.name).join("\n");
      return new Response(keyList || "No keys found");
    }

    return new Response("Try /put, /get, /delete, or /list");
  },
};

This code can be run directly with Wrangler:

wrangler dev
# Test write
curl "http://localhost:8787/put?key=test&value=helloworld"
# Test read
curl "http://localhost:8787/get?key=test"

Complete Session Storage Implementation

This is one of KV’s most common use cases. Here’s complete session management code:

// src/session.ts
interface SessionData {
  userId: string;
  email: string;
  createdAt: number;
  expiresAt: number;
}

interface Env {
  SESSION_KV: KVNamespace;
}

const SESSION_TTL = 3600; // 1 hour expiration

class SessionManager {
  private kv: KVNamespace;

  constructor(kv: KVNamespace) {
    this.kv = kv;
  }

  // Create session
  async create(userId: string, email: string): Promise<string> {
    const sessionId = crypto.randomUUID();
    const sessionData: SessionData = {
      userId,
      email,
      createdAt: Date.now(),
      expiresAt: Date.now() + SESSION_TTL * 1000,
    };

    // Write to KV with TTL (auto-expire)
    await this.kv.put(
      `session:${sessionId}`,
      JSON.stringify(sessionData),
      { expirationTtl: SESSION_TTL }
    );

    return sessionId;
  }

  // Read session
  async get(sessionId: string): Promise<SessionData | null> {
    const raw = await this.kv.get(`session:${sessionId}`);
    if (!raw) return null;

    try {
      return JSON.parse(raw) as SessionData;
    } catch {
      return null;
    }
  }

  // Delete session (logout)
  async delete(sessionId: string): Promise<void> {
    await this.kv.delete(`session:${sessionId}`);
  }

  // Refresh session (extend expiration)
  async refresh(sessionId: string): Promise<boolean> {
    const session = await this.get(sessionId);
    if (!session) return false;

    session.expiresAt = Date.now() + SESSION_TTL * 1000;
    await this.kv.put(
      `session:${sessionId}`,
      JSON.stringify(session),
      { expirationTtl: SESSION_TTL }
    );

    return true;
  }
}

// Worker entry point
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const sessionManager = new SessionManager(env.SESSION_KV);
    const url = new URL(request.url);

    // Login (create session)
    if (url.pathname === "/login" && request.method === "POST") {
      const body = await request.json();
      const sessionId = await sessionManager.create(
        body.userId as string,
        body.email as string
      );
      
      return new Response(JSON.stringify({ sessionId }), {
        headers: { "Content-Type": "application/json" },
      });
    }

    // Verify session
    if (url.pathname === "/verify") {
      const sessionId = url.searchParams.get("sessionId");
      if (!sessionId) {
        return new Response("Missing sessionId", { status: 400 });
      }

      const session = await sessionManager.get(sessionId);
      if (!session) {
        return new Response("Session not found", { status: 401 });
      }

      return new Response(JSON.stringify(session), {
        headers: { "Content-Type": "application/json" },
      });
    }

    // Logout
    if (url.pathname === "/logout") {
      const sessionId = url.searchParams.get("sessionId");
      if (sessionId) {
        await sessionManager.delete(sessionId);
      }
      return new Response("Logged out");
    }

    return new Response("Not found", { status: 404 });
  },
};

Key points:

1. TTL auto-expiration: The expirationTtl parameter lets KV automatically delete expired data—no manual cleanup needed
2. Key prefix: Using session: as a prefix makes batch queries easy and distinguishes different data types
3. JSON serialization: KV only stores strings, complex objects need manual JSON.stringify/parse

API Response Cache Implementation

Another common scenario: caching third-party API return values to reduce call frequency and latency.

// src/api-cache.ts
interface Env {
  CACHE_KV: KVNamespace;
}

const DEFAULT_CACHE_TTL = 300; // 5 minute cache

async function cachedFetch(
  kv: KVNamespace,
  cacheKey: string,
  url: string,
  ttl: number = DEFAULT_CACHE_TTL
): Promise<Response> {
  // Try reading from cache first
  const cached = await kv.get(cacheKey, "text");
  
  if (cached) {
    console.log(`Cache hit: ${cacheKey}`);
    return new Response(cached, {
      headers: {
        "Content-Type": "application/json",
        "X-Cache": "HIT",
      },
    });
  }

  // Cache miss, call real API
  console.log(`Cache miss: ${cacheKey}`);
  const response = await fetch(url);
  const body = await response.text();

  // Write to cache (using cacheTtl to optimize read performance)
  await kv.put(cacheKey, body, {
    expirationTtl: ttl,
    // cacheTtl: let edge cache longer, reduce origin fetches
  });

  return new Response(body, {
    headers: {
      "Content-Type": "application/json",
      "X-Cache": "MISS",
    },
  });
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);
    const apiUrl = url.searchParams.get("api");

    if (!apiUrl) {
      return new Response("Missing api parameter", { status: 400 });
    }

    // Use API URL as cache key
    const cacheKey = `api:${apiUrl}`;
    
    return cachedFetch(env.CACHE_KV, cacheKey, apiUrl);
  },
};

cacheTtl Parameter Optimization

This is the most easily overlooked parameter in KV performance optimization.

cacheTtl controls the survival time of edge cache. The default value is 60 seconds, meaning repeated reads of the same key within 60 seconds can be retrieved directly from edge cache without going to origin.

For hot data, you can set cacheTtl higher:

// High-frequency configuration data, set longer edge cache
await env.MY_KV.get("config:feature-flags", {
  cacheTtl: 3600, // 1 hour edge cache
});

This way, even if KV’s central store data hasn’t changed, edge nodes will cache for 1 hour. For feature flags where “changes don’t need to take effect immediately,” this is incredibly useful.

KV vs D1 vs R2 — Storage Selection Decision Guide

Honestly, I struggled with this at first too. With so many Cloudflare storage options, which one should you choose?

Here’s a decision tree:

Scenario Matching Decision Tree

What type is your data?

├─ Need file storage (images, videos, PDFs)?
│   └─ YES → R2
│
├─ Need SQL queries (user tables, orders, multi-table joins)?
│   └─ YES → D1
│
├─ Simple key-value, read-heavy?
│   ├─ Write frequency > 1 RPS/key?
│   │   └─ YES → Not suitable for KV, consider D1 or Durable Objects
│   │
│   └─ NO → KV ✓
│
├─ Need immediate consistency?
│   └─ YES → Durable Objects
│   └─ NO → KV might be OK
│
└─ Don't know?
    └─ Try KV first, if it works don't switch

Detailed Comparison Table

Comparison Dimension	KV	D1	R2
Data Model	Key-Value	SQL (SQLite)	Object Storage
Query Capability	Only get/put/delete	Full SQL queries	No queries, only paths
Write Limit	1 RPS per key	No hard limit	No hard limit
Read Latency	500µs - 10ms (hot)	50-200ms (depends on location)	Fast (download)
Consistency	Eventually consistent	Strongly consistent (single region)	Eventually consistent
Max value	25 MB	SQLite row limit	5 TB per file
Free Tier	100k reads/day	5 GB storage + 25M rows read	10 GB storage
Typical Use	Session, Cache, Config	User data, Orders, Reports	Files, Images, Backups

Specific Scenario Recommendations

User Authentication / Session
→ KV

Reason: Session data is simple key-value, high read frequency (every request needs verification), low write frequency (only during login/logout). Authentication frameworks like OpenAuth use KV by default.

// session:userId → session data
await env.SESSION_KV.put(`session:${sessionId}`, JSON.stringify(session));

User Profiles / Order Management
→ D1

Reason: Needs SQL queries (“find all orders for a user”, “calculate last month’s sales”), KV’s get/put pattern can’t do these queries.

-- D1 can do complex queries
SELECT * FROM orders WHERE user_id = ? AND created_at > ?

Images / File Storage
→ R2

Reason: Files are too large (25 MB is KV’s limit), and the fast read pattern of key-value isn’t needed. R2 is better suited for object storage scenarios.

// R2 store files
await env.MY_BUCKET.put("images/profile.jpg", imageBuffer);

API Rate Limiting
→ KV (but be careful)

Reason: Counters are key-value, but write frequency might exceed 1 RPS. If it’s just simple “check today’s request count,” KV still works; for precise per-second rate limiting, you might need Durable Objects or Upstash Redis.

// Simple rate limiting (daily refresh)
const count = parseInt(await env.KV.get(`rate:${userId}`) || "0");
if (count > 100) {
  return new Response("Rate limit exceeded", { status: 429 });
}
await env.KV.put(`rate:${userId}`, String(count + 1));

Third-party API Caching
→ KV

Reason: API return value caching, high reads, low writes (only updates when API call fails or expires). 5-minute TTL caching doesn’t need immediate consistency at all.

Example of Combined Usage

Often, a project will combine multiple storage types:

interface Env {
  SESSION_KV: KVNamespace;   // User sessions
  CACHE_KV: KVNamespace;     // API cache
  DATABASE_D1: D1Database;   // User data, orders
  FILES_R2: R2Bucket;        // User-uploaded files
}

// A single request might use all of them:
// 1. Read session from SESSION_KV
// 2. Read third-party API cache from CACHE_KV
// 3. Query user orders from DATABASE_D1
// 4. Return user avatar from FILES_R2

This kind of combination is where the true power of the Cloudflare ecosystem shows.

Performance Optimization Practical Tips

KV is great when used correctly, but can become a bottleneck if misused. Here are some optimization tips I’ve personally tested and found effective.

1. cacheTtl Parameter Tuning

The default cacheTtl is 60 seconds. For hot data, this value can be significantly increased.

// ❌ Default behavior: 60 second edge cache
await env.KV.get("config:feature-flags");

// ✅ Optimized: Cache configuration data longer
await env.KV.get("config:feature-flags", {
  cacheTtl: 3600, // 1 hour edge cache
});

What scenarios suit higher cacheTtl?

• Feature flags: Changing config and waiting a few minutes to take effect is completely OK
• Static configuration: API endpoints, third-party service URLs
• Redirect rules: URL mapping tables, low change frequency

What scenarios don’t suit this?

• Session data: User login state needs immediate reflection
• Real-time counters: Rate limiting counters need precision

2. Parallel API Calls Instead of Serial

This is an easy pitfall to fall into. If your Worker needs to read multiple keys, don’t read them one by one.

// ❌ Serial reads: Each request waits for the previous one to complete
const user = await env.KV.get(`user:${userId}`);
const settings = await env.KV.get(`settings:${userId}`);
const permissions = await env.KV.get(`permissions:${userId}`);
// Total latency = 3 × single latency

// ✅ Parallel reads: All three requests go out simultaneously
const [user, settings, permissions] = await Promise.all([
  env.KV.get(`user:${userId}`),
  env.KV.get(`settings:${userId}`),
  env.KV.get(`permissions:${userId}`),
]);
// Total latency ≈ single latency (the slowest one)

KV API calls are asynchronous and don’t block Worker execution. Using Promise.all can “compress” multiple requests’ latency to the longest one.

Real-world test: Reading 3 keys, serial took about 20ms, parallel only 8ms.

3. Hot Keys Design Strategy

KV’s performance largely depends on whether your keys are “hot”—frequently accessed.

Strategies to avoid cold keys:

// ❌ Keys too scattered, each user only accesses their own key
await env.KV.get(`session:${userId}`); // Only this user accesses, cold key

// ✅ Merge into hot key (for shared data)
await env.KV.get("config:global-flags"); // All users share, hot key

But this doesn’t mean you should stuff all data into one key. The correct approach is:

• User private data: Separate keys by user ID (session, profile)
• Globally shared data: Use single hot key (config, flags, redirect rules)

4. Namespace Organization Best Practices

An account can have 1000 namespaces. Using this limit wisely can help you isolate different types of data.

# wrangler.toml
[[kv_namespaces]]
binding = "SESSION_KV"
id = "xxx"  # User sessions

[[kv_namespaces]]
binding = "CACHE_KV"
id = "yyy"  # API cache

[[kv_namespaces]]
binding = "CONFIG_KV"
id = "zzz"  # Configuration data

Benefits:

1. Isolated cleanup: CACHE_KV can be bulk cleared without affecting SESSION_KV
2. Different TTL strategies: SESSION uses short TTL, CONFIG uses long TTL
3. Separated monitoring: Cloudflare Dashboard can show usage for each namespace separately

5. Batch Operation Tips

KV supports list() operation, which can query all keys by prefix:

// List all session keys
const result = await env.SESSION_KV.list({ prefix: "session:" });

// result.keys is an array
for (const key of result.keys) {
  console.log(key.name);
}

// If there are many keys, there will be cursor pagination
if (!result.list_complete) {
  const next = await env.SESSION_KV.list({
    prefix: "session:",
    cursor: result.cursor,
  });
}

Batch cleanup of expired sessions:

// Clean up all sessions (use with caution)
const keys = await env.SESSION_KV.list({ prefix: "session:" });
for (const key of keys.keys) {
  await env.SESSION_KV.delete(key.name);
}

Note: Batch delete operations should be used cautiously—they consume significant write quota.

Pricing and Limits — Cost Control Guide

KV pricing is friendly, but there are a few limits to watch out for. If you hit these limits, requests will error out directly.

Free Plan vs Paid Plan

Metric	Free Plan	Paid Plan ($5/month)
Read Operations	100,000 / day	Unlimited (metered)
Write Operations	1,000 / day	Unlimited (metered)
Delete Operations	1,000 / day	Unlimited (metered)
List Operations	1,000 / day	Unlimited (metered)
Storage	1 GB	Unlimited (metered)
Namespace Count	1000	1000

The Free plan is completely sufficient for personal projects and testing. For production environments, I recommend the Paid plan—$5/month gets you:

• Unlimited reads (pay per use)
• More write quota
• Dashboard monitoring and alerts

Write Rate Limit: The Most Critical Constraint

This is KV’s most important limitation and the easiest pitfall to fall into:

Each unique key can be written at most once per second (1 RPS)

Exceeding this limit, the request will error out directly.

// ❌ High-frequency writes will fail
for (let i = 0; i < 10; i++) {
  await env.KV.put("counter", String(i)); // 2nd+ attempt will fail
}

// ✅ Distributed keys can bypass the limit
await env.KV.put(`counter:${Math.floor(Date.now() / 1000)}`, value);
// One new key per second, won't trigger limit

What’s the essence of this limit? KV’s architecture is “write once, replicate globally.” Frequent writes to the same key would cause replication overhead to explode. So Cloudflare uses this limit to protect their system.

Mitigation Strategies:

1. Time-distributed keys: counter:timestamp creates one new key per second
2. UUID distribution: Use a new UUID as key for each write
3. Switch to D1 or Durable Objects: If high-frequency writes are a requirement

Value Size Limit

KV values can be up to 25 MB (raised from 10 MB in early 2025).

// ❌ Exceeding 25 MB will error
const largeData = generateBigString(30_000_000); // 30 MB
await env.KV.put("large-key", largeData); // Error!

// ✅ Large data uses R2
await env.R2_BUCKET.put("large-key", largeData);

25 MB is more than enough for session, config, cache. But if you need to store large JSON or files, R2 is the better choice.

Namespace Management Strategy

An account has 1000 namespaces total. This number was raised from 200 in early 2025, showing Cloudflare is relaxing limits.

Management Strategy:

// Group by function
SESSION_KV    // User sessions
CACHE_KV      // API cache
CONFIG_KV     // Configuration data
RATE_LIMIT_KV // Rate limiting counters

What if you run out of namespaces? You can use key prefixes to isolate within the same namespace:

// Single namespace isolation
await env.KV.put("session:user1", data);
await env.KV.put("cache:api1", data);
await env.KV.put("config:flags", data);

Cost Estimation Formula

If your project uses the Paid plan:

Monthly Cost = $5 (base fee) + Read costs + Write costs + Storage costs

Read costs = Read operations × $0.01 / 100,000
Write costs = Write operations × $1.00 / 1,000,000
Storage costs = Storage size × $0.50 / GB

Example: A project with 100,000 daily requests:

• Reads: 100,000 × 30 = 3M reads/month = $0.30
• Writes: Assume 1000 × 30 = 30k writes/month ≈ $0.03
• Storage: 10 MB × $0.50/GB ≈ $0.005
• Total Cost: $5 + $0.33 ≈ $5.35/month

Pretty cheap, right? This is Cloudflare’s typical pricing style.

Summary

After all this discussion, the core point is simple: KV is Workers’ “pocket memory,” suitable for session, cache, and config scenarios with read-heavy workloads.

Here’s a quick decision checklist:

Use KV if:

• Data is simple key-value
• Read frequency far exceeds writes
• Don’t need immediate consistency
• Each key gets no more than 1 write per second

Switch to D1 if:

• Need SQL queries
• Have complex table relationships
• Write frequency might exceed 1 RPS

Switch to R2 if:

• Storing files, images, videos
• Value exceeds 25 MB

Switch to Durable Objects if:

• Need immediate consistency
• Collaborative editing, real-time sync

Next steps? Try connecting your Workers project to KV. Start with session storage—the code above runs directly. If you encounter issues, Cloudflare’s official documentation is quite detailed, or search for other articles in this series.

If you’re interested in D1 or R2, check out other articles in the cloudflare-bindui series—I’ll cover the complete storage matrix there.

FAQ

What is the write limit for Cloudflare Workers KV?

Each unique key can be written at most once per second (1 RPS). Exceeding this limit will cause requests to error out directly. Mitigation strategies: use timestamps to distribute keys (like counter:timestamp), or switch to D1/Durable Objects.

Is KV suitable for storing user sessions?

Very suitable. Session data is simple key-value, with high read frequency (every request verification) and low write frequency (only during login/logout). Combined with TTL auto-expiration, no manual cleanup needed.

What's the difference between KV and D1? Which should I choose?

Core differences:

• KV: Key-Value model, hot keys latency 500µs-10ms, write limit 1 RPS/key
• D1: SQL model (SQLite), supports complex queries, no write limit

Selection: Choose D1 for SQL queries, KV for simple key-value with read-heavy workloads.

Why can KV achieve 500µs-10ms latency?

Three-layer cache architecture: Edge Cache (edge nodes) → Regional Cache → Central Store. About 30% of requests hit directly at edge cache without going to origin. After 2025 Cloudflare optimization, speed improved 3x.

What does the cacheTtl parameter do?

Controls the survival time of edge cache. Default is 60 seconds. For hot data (like feature flags, config), can be set to 3600 seconds (1 hour), letting edge nodes cache longer and reduce origin fetches.

What's the maximum value size KV can store?

25 MB (raised from 10 MB in early 2025). Exceeding this limit will error out—large data (images, videos) should use R2 Object Storage.

15 min read · Published on: Apr 22, 2026 · Modified on: Apr 25, 2026