Get started
Workers KV provides low-latency, high-throughput global storage to your Cloudflare Workers applications. Workers KV is ideal for storing user configuration data, routing data, A/B testing configurations and authentication tokens, and is well suited for read-heavy workloads.
This guide will instruct you through:
- Creating a KV namespace.
- Writing key-value pairs to your KV namespace from a Cloudflare Worker.
- Reading key-value pairs from a KV namespace.
To continue:
- Sign up for a Cloudflare account if you have not already.
- Install
npm
. - Install
Node.js
. Use a Node version manager like Volta or nvm to avoid permission issues and change Node.js versions. Wrangler requires a Node version of16.13.0
or later. - Update your Wrangler installation to the most updated version.
Create a new Worker to read and write to your KV namespace.
Create a new project named kv-tutorial
by running:
For setup, select the following options:
- For What would you like to start with?, choose
Hello World example
. - For Which template would you like to use?, choose
Hello World Worker`
. - For Which language do you want to use?, choose
TypeScript`
. - For Do you want to use git for version control?, choose
Yes
. - For Do you want to deploy your application?, choose
No
(we will be making some changes before deploying).
This will create a new kv-tutorial
directory. Your new kv-tutorial
directory will include:
- A
"Hello World"
Worker atsrc/index.ts
. - A
wrangler.toml
configuration file.wrangler.toml
is how yourkv-tutorial
Worker will access your kv database.
Change into the directory you just created for your Worker project:
A KV namespace is a key-value database replicated to Cloudflare’s global network.
You can create a KV namespace via Wrangler or the dashboard.
Wrangler allows you to put, list, get, and delete entries within your KV namespace.
To create a KV namespace via Wrangler:
- Open your terminal and run the following command:
The npx wrangler kv namespace create <YOUR_NAMESPACE>
subcommand takes a new binding name as its argument. A KV namespace will be created using a concatenation of your Worker’s name (from your wrangler.toml
file) and the binding name you provide. The id
will be randomly generated for you.
- In your
wrangler.toml
file, add the following with the values generated in your terminal:
Binding names do not need to correspond to the namespace you created. Binding names are only a reference. Specifically:
- The value (string) you set for
<BINDING_NAME>
will be used to reference this database in your Worker. In this tutorial, name your bindingDB
. - The binding must be a valid JavaScript variable name. For example,
binding = "MY_KV"
orbinding = "routingConfig"
would both be valid names for the binding. - Your binding is available in your Worker at
env.<BINDING_NAME>
from within your Worker.
- Log in to the Cloudflare dashboard.
- Select Workers & Pages > KV.
- Select Create a namespace.
- Enter a name for your namespace.
- Select Add.
You can interact with your KV namespace via Wrangler or directly from your Workers application.
To write a value to your empty KV namespace using Wrangler, run the wrangler kv key put
subcommand in your terminal, and input your key and value respectively. <KEY>
and <VALUE>
are values of your choice.
Instead of using --binding
, you may use --namespace-id
to specify which KV namespace should receive the operation:
To create a key and a value in local mode, use the --local
flag:
To access the value using Wrangler, run the wrangler kv key get
subcommand in your terminal, and input your key value:
A KV namespace can be specified in two ways:
- With a
--binding
:
This can be combined with --preview
flag to interact with a preview namespace instead of a production namespace.
- With a
--namespace-id
:
Refer to the kv bulk
documentation to write a file of multiple key-value pairs to a given KV namespace.
You can access the binding from within your Worker.
In your Worker script, add your KV namespace in the Env
interface:
Use the put()
method on YOUR_KV_NAMESPACE
to create a new key-value pair, or to update the value for a particular key:
Use the KV get()
method to fetch the data you stored in your KV database:
Your Worker code should look like this:
The code above:
- Writes a key to
YOUR_KV_NAMESPACE
using KV’sput()
method. - Reads the same key using KV’s
get()
method, and returns an error if the key is null (or in case the key is not set, or does not exist). - Uses JavaScript’s
try...catch
exception handling to catch potential errors. When writing or reading from any service, such as Workers KV or external APIs usingfetch()
, you should expect to handle exceptions explicitly.
To run your project locally, enter the following command within your project directory:
When you run wrangler dev
, Wrangler will give you a URL (usually a localhost:8787
) to review your Worker. After you visit the URL Wrangler provides, you will see your value printed on the browser.
Run the following command to deploy KV to Cloudflare’s global network:
You can now visit the URL for your newly created Workers KV application.
For example, if the URL of your new Worker is kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev
, accessing https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/
will send a request to your Worker that writes (and reads) from Workers KV.
By finishing this tutorial, you have created a KV namespace, a Worker that writes and reads from that namespace, and deployed your project globally.
If you have any feature requests or notice any bugs, share your feedback directly with the Cloudflare team by joining the Cloudflare Developers community on Discord.
- Learn more about the KV API.
- Understand how to use Environments with Workers KV.
- Read the wrangler
kv
command documentation.