sellStorage & Databases

key

Workers KV

Save a value under a name and read it back fast from anywhere on Earth.

100KFree reads / day

1KFree writes / day

25 MiBMax value size

~60sGlobal propagation

lightbulb

What is Workers KV?

Workers KV is a key-value store (key-value = you save data as a name → value pair, and look it up by the name). It is built for reads: once data is cached near a user, getting it back is extremely fast.

There are no tables or SQL. You just put('user:42', '...') to save and get('user:42') to read. Values are copied across Cloudflare's global network so reads stay close to your users.

local_library

Think of it like…

A worldwide network of coat-check counters. You hand in a coat and get a ticket (the key). Show that ticket at any branch and they fetch your coat instantly — because every branch keeps a copy.

help

Why use KV?

When you read the same small piece of data over and over — a config flag, a cached API response, a session — a full SQL database is overkill. KV makes those reads nearly instant and globally available.

bolt

Fast reads everywhere

Cached values are served from the location nearest each user.

trending_up

Handles huge read volume

Designed for read-heavy workloads where the same keys are fetched often.

extension

Dead-simple API

Just put, get, list, and delete — nothing else to learn.

savings

Cheap to run

A big free tier and low per-operation cost make caching nearly free.

target

When should you use it?

cached

Caching API responses

Store a slow upstream response and serve it fast for the next minute.

tune

Feature flags & config

Toggle features or store settings read on almost every request.

badge

Sessions & tokens

Keep login sessions or auth tokens that are read far more than written.

routing

Redirects & lookups

Short-link maps or country routing tables looked up by key.

rocket_launch

How do you start?

Create a namespace (a namespace = one isolated bucket of key-value pairs), bind it to a Worker, then write and read values.

Create a namespace
Wrangler prints an id — copy it for the binding.
bash
```
npx wrangler kv namespace create MY_KV
```
Bind it to your Worker
Add this to wrangler.jsonc so the store is available as env.MY_KV.
json
```
{
  "kv_namespaces": [
    {
      "binding": "MY_KV",
      "id": "<paste-your-id-here>"
    }
  ]
}
```

Write & read in code

put saves a value; get reads it back. The expirationTtl option auto-deletes the key after the given seconds.

export default {
  async fetch(request, env) {
    await env.MY_KV.put("greeting", "Hello!", {
      expirationTtl: 3600,
    });

    const value = await env.MY_KV.get("greeting");
    return new Response(value ?? "not found");
  },
};

Seed a value from the CLI
You can also write keys straight from the terminal.
bash
```
npx wrangler kv key put --binding MY_KV "greeting" "Hello!" --remote
```
Deploy
Publish the Worker to go live globally.
bash
```
npx wrangler deploy
```

school

Key concepts

key

Key & value

The key is the name (up to 512 bytes); the value is the data (up to 25 MiB).

schedule

Eventual consistency

After a write, other regions may take up to ~60 seconds to show the new value. They get there eventually — hence 'eventual'.

timer

Expiration (TTL)

Set expirationTtl so a key auto-deletes itself after N seconds — perfect for caches.

compare_arrows

Read-heavy, not write-heavy

KV shines when you read far more than you write; the same key takes ~1 write/second max.

tips_and_updates

Tips & limits

warning

Not for instant-fresh data

Because writes take up to ~60 seconds to spread worldwide, avoid KV for things that must be perfectly up-to-date everywhere instantly, like bank balances. Use D1 or Durable Objects for that.

Free tier: 100,000 reads, 1,000 writes, 1,000 deletes, and 1,000 list operations per day, plus 1 GB storage.
A key can be up to 512 bytes; a value up to 25 MiB; up to 1,000 namespaces per account.
Use clear key prefixes like session: or cache: to keep keys organized.
Reads are cheaper than writes — lean on caching and let TTLs expire stale data.