# 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.

Source: https://docs.fortly.com/kv

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](https://docs.fortly.com/api/kv), with an [account token](https://docs.fortly.com/account/tokens). |
| The console | **Storage → Key-value**: browse namespaces, search keys, and read, edit, add or delete them. |

## From a Worker

```jsonc
// wrangler.jsonc
{
  "kv_namespaces": [{ "binding": "CACHE", "id": "cache" }]
}
```

```js
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. `expirationTtl` and `expiration` must 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](https://docs.fortly.com/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](https://docs.fortly.com/data/backups) 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.

- [Key-value API](https://docs.fortly.com/api/kv): List, read, write and delete keys with a server-held account token.
- [Worker bindings](https://docs.fortly.com/deploy/bindings): Inspect the namespace your live Worker receives.
- [Files and buckets](https://docs.fortly.com/files#buckets-for-a-worker): Use object storage for values larger than 1 MiB.