Cloudflare Docs
Workers
Cloudflare Docs
Workers
GitHub icon
Visit Workers on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Workers
  3. Wrangler
  4. Workers KV

Workers KV

Workers KV is a global, low-latency, key-value data store. It stores data in a small number of centralized data centers, then caches that data in Cloudflare’s data centers after access.

To learn more about how KV works, refer to How KV works.

To review the API spec, refer to the KV in Runtime API.

You can interact with KV via Wrangler and the Cloudflare dashboard. This page will guide you through creating your KV namespace, writing a new value to your namespace and interacting with environments.

​​ Create a KV namespace with Wrangler

Wrangler allows you to create, list, and delete KV namespaces. It also allows you to put, list, get, and delete entries within your KV namespace.

KV operations are scoped to your account. To use Workers KV with your Worker, the first thing you must do is create a KV namespace. This is done with the kv:namespace subcommand.

To create a KV namespace with Wrangler:

  1. Run wrangler kv:namespace create <YOUR_NAMESPACE> in your terminal.

The kv:namespace subcommand takes a new binding name as its argument. A Workers KV namespace will be created using a concatenation of your Worker’s name (from your wrangler.toml file) and the binding name you provide:


$ wrangler kv:namespace create <YOUR_NAMESPACE>
🌀  Creating namespace with title <YOUR_WORKER-YOUR_NAMESPACE>
✨  Success!
Add the following to your configuration file:
kv_namespaces = [
  { binding = <YOUR_BINDING>, id = "e29b263ab50e42ce9b637fa8370175e8" }
]
  1. In your wrangler.toml file, add the following with the values generated in your terminal:

kv_namespaces = [
    { binding = "<YOUR_BINDING>", id = "<YOUR_ID>" }

]

Note that binding names do not need to correspond to the namespace you created. It is an entirely new value that you assign.

​​ Interact with your KV namespace

To write a value to your empty KV namespace using Wrangler, run the wrangler kv:key put subcommand and input your key and value respectively:


$ wrangler kv:key put --binding=<YOUR_BINDING> "<KEY>" "<VALUE>"
Writing the value "<VALUE>" to key "<KEY>" on namespace e29b263ab50e42ce9b637fa8370175e8.

You can now access the binding from within a Worker. In your Worker, use the KV .get() command to fetch the data you stored in your KV database:


let value = await <YOUR_BINDING>.get("KEY");

Instead of --binding, you may use --namespace-id to specify which KV namespace should receive the operation:


$ wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "<KEY>" "<VALUE>"
Writing the value "<VALUE>" to key "<KEY>" on namespace e29b263ab50e42ce9b637fa8370175e8.

To summarize, a namespace can be specified in two ways:

  1. With a --binding:


    $ wrangler kv:key get --binding=<YOUR_BINDING> "<KEY>"
    • This can be combined with --preview flag to interact with a preview namespace instead of a production namespace.

  2. With a --namespace-id:


    $ wrangler kv:key get --namespace-id=<YOUR_ID> "<KEY>"

Refer to the kv:bulk documentation to write a file of multiple key-value pairs to a given namespace.

​​ Use environments with KV namespaces

KV namespaces can be used with environments. This is useful for when you have code in your Worker that refers to a KV binding like MY_KV, and you want to be able to have these bindings point to different namespaces (like one for staging and one for production).

A wrangler.toml file with two environments that have two different namespaces with the same binding name:


[env.staging]

kv_namespaces = [
  { binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }

]



[env.production]

kv_namespaces = [
  { binding = "MY_KV", id = "a825455ce00f4f7282403da85269f8ea" }

]

Using the same binding name for two different namespaces keeps your Worker code simple. In the staging environment, MY_KV.get("KEY") will read from the namespace ID e29b263ab50e42ce9b637fa8370175e8. In the production environment, MY_KV.get("KEY") will read from the namespace ID a825455ce00f4f7282403da85269f8ea.

To insert a value into a staging KV namespace, use:


$ wrangler kv:key put --env=staging --binding=<YOUR_BINDING> "<KEY>" "<VALUE>"

Since --namespace-id is always unique (unlike binding names), you do not need to specify an --env argument:


$ wrangler kv:key put --namespace-id=<YOUR_ID> "<KEY>" "<VALUE>"

Most kv subcommands also allow you to specify an environment with the optional --env flag. This allows you to publish Workers running the same code but with different namespaces. For example, you could use separate staging and production namespaces for KV data in your wrangler.toml file:


type = "webpack"

name = "my-worker"

account_id = "<account id here>"

route = "staging.example.com/*"

workers_dev = false



kv_namespaces = [
  { binding = "MY_KV", id = "06779da6940b431db6e566b4846d64db" }

]



[env.production]

route = "example.com/*"

kv_namespaces = [
  { binding = "MY_KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" }

]

With the wrangler.toml file above, you can specify --env production when you want to perform a KV action on the namespace MY_KV under env.production. For example, with the wrangler.toml file above, you can get a value out of a production KV instance with:


$ wrangler kv:key get --binding "MY_KV" --env=production "<KEY>"