KV store

KV (key-value) is a fast store where a string value sits under a string key. It is built into functions and reachable by name, with no connection strings.

KV is for simple “put — read” data: caches, sessions, settings, view counters. It is not meant for tables or relations between records — use the D1 database.

Declaration

A KV namespace is declared in wrangler.jsonc under kv_namespaces:

{
  "kv_namespaces": [
    { "binding": "CACHE", "id": "cache" }
  ]
}

• binding — the variable name under which the store is visible in code: env.CACHE.
• id — the name you pass to the CLI commands.

You can have several namespaces — for example, one for the cache and one for settings.

Reading and writing from code

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    // Write (third argument — options, e.g. a lifetime in seconds)
    if (url.pathname === "/set") {
      const key = url.searchParams.get("key");
      const value = url.searchParams.get("value") ?? "1";
      await env.CACHE.put(key, value, { expirationTtl: 60 });
      return Response.json({ ok: true });
    }

    // Read
    if (url.pathname === "/get") {
      const key = url.searchParams.get("key");
      const value = await env.CACHE.get(key);
      return Response.json({ key, value });
    }

    // Delete
    if (url.pathname === "/delete") {
      const key = url.searchParams.get("key");
      await env.CACHE.delete(key);
      return Response.json({ ok: true });
    }

    // List keys
    const { keys } = await env.CACHE.list();
    return Response.json(keys);
  },
};

Main methods:

• get(key) — the value under the key, or null if it is absent.
• put(key, value, options?) — write. In options you can set expirationTtl (a lifetime in seconds) or expiration (a Unix expiration time in seconds). Without options the key lives forever.
• delete(key) — remove the key.
• list() — the list of keys ({ keys, list_complete, cursor }).

The value is a string. To store an object, serialize it yourself, e.g. JSON.stringify(...), and parse it back with JSON.parse.

Bulk import

A set of keys is loaded with one command from a JSON file in the Wrangler format. Each entry is an object with a key and a value:

[
  { "key": "greeting", "value": "hello" },
  { "key": "plan", "value": "pro" },
  { "key": "logo", "value": "<base64>", "base64": true },
  { "key": "offer", "value": "discount", "expiration": 1730000000 }
]

• key — the key, value — the value (a string).
• base64: true — the value is base64-encoded; this is how you load binary data.
• expiration — a Unix time in seconds when the key expires. Without it the key is permanent.

The file must be inside the project directory and get into the archive (not be excluded by .gitignore). Run from the project directory:

webshield apps kv import --app api CACHE seed/keys.json

Here CACHE is the id of the namespace from the config. The import adds or updates keys: existing ones are overwritten with the new values.

Bulk delete

Delete a list of keys — the same format, only the key field:

[
  { "key": "greeting" },
  { "key": "plan" }
]

webshield apps kv delete-keys --app api CACHE old-keys.json

Details

• The function must already be deployed — the commands run on its nodes, next to the store.
• Imports and deletes repeat on their own if the connection to the function breaks: writing and deleting by key is safe to run twice.
• History and output of operations is on the Data tab.
• Return to a point in time also restores KV: Data tab → Return data to a moment. More in Functions.