Key-value
A key-value store for every project, organized into namespaces, that a Worker reads through its KV binding and any program reads through the API.
Every project has a key-value store for small values that are read often: sessions, feature flags, cached responses, rate counters you keep yourself. It is organized into namespaces, and each namespace holds keys of up to 512 bytes with values of up to 1 MiB.
You can reach the same keys three ways:
| From | How |
|---|---|
| A Worker | Declare a namespace in wrangler.jsonc and use env.<binding>, the same API as Cloudflare KV. |
| Any program | The Key-value API, with an account token. |
| The console | Storage → Key-value: browse namespaces, search keys, and read, edit, add or delete them. |
From a Worker
// wrangler.jsonc
{
"kv_namespaces": [{ "binding": "CACHE", "id": "cache" }]
}await env.CACHE.put("user:42", JSON.stringify(user), { expirationTtl: 3600, metadata: { plan: "pro" } });
const cached = await env.CACHE.get("user:42", "json");
const { value, metadata } = await env.CACHE.getWithMetadata("user:42");
const { keys, list_complete, cursor } = await env.CACHE.list({ prefix: "user:" });
await env.CACHE.delete("user:42");The namespace is named by the binding's id, so two bindings with the same id share it. Without an id, the binding's name in lower case is used. get takes the text, json, arrayBuffer and stream types, or an array of up to 100 keys, which returns a Map.
How it behaves
- Writes are visible at once. There is no propagation delay: the next read, from anywhere, sees the new value.
- Expiry is exact. A key stops being returned the second it expires.
expirationTtlandexpirationmust be at least 60 seconds away, as on Cloudflare. - A namespace belongs to its project. Deleting the project deletes its keys.
- Larger values belong in Storage. A value over 1 MiB is refused with a message that says so. Store large objects as files, which a Worker reaches through an R2 bucket binding.
In the console
Open Storage → Key-value, choose a namespace, then select a key. The value inspector shows its saved value, size, metadata and expiry. Text values and JSON metadata can be edited; Save applies both together and Revert discards the local edits. Changing keys or namespaces, switching to Files, or following a link away from the editor asks before discarding unsaved edits.
Add key accepts a namespace, key, text value, optional expiry in seconds and optional JSON metadata. Names and values are checked by their UTF-8 byte length. The add form refuses to replace an existing key; select that key to edit its value. Connect to your app provides a copyable namespace binding for wrangler.jsonc. The binding's namespace link opens the matching namespace in Storage.
Editing keeps the key's existing expiry. During its final 60 seconds, saving is refused rather than removing the expiry or keeping the key permanently. Wait for it to expire or create a separate key if needed. Binary values can be inspected and copied in their API encoding; the console does not edit their bytes.
Prefix search has a clear action, and failed key/value loads offer a retry. Deleting a key or clearing a namespace requires confirmation and has no undo.
Keep recovery separate
KV lives outside the project's PostgreSQL database. Point-in-time restore leaves its keys unchanged. Deleting the project deletes the keys; deleting a key or clearing a namespace has no recovery control. Decide which values can be regenerated and keep separate copies when your application requires them.