pcx_content_type | title | weight |
---|---|---|
reference |
KV commands |
2 |
Manage KV namespaces.
The kv:...
commands allow you to manage application data in the Cloudflare network to be accessed from Workers using KV.
Creates a new KV namespace.
$ wrangler kv:namespace create <NAMESPACE> [OPTIONS]
{{}}
NAMESPACE
{{}}string{{}} {{}}required{{}}- The name of the new namespace.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace (the
preview_id
value).
- Interact with a preview namespace (the
{{}}
$ wrangler kv:namespace create "MY_KV"
🌀 Creating namespace with title "worker-MY_KV"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
kv_namespaces = [
{ binding = "MY_KV", id = "e29b263ab50e42ce9b637fa8370175e8" }
]
$ wrangler kv:namespace create "MY_KV" --preview
🌀 Creating namespace with title "my-site-MY_KV_preview"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
kv_namespaces = [
{ binding = "MY_KV", preview_id = "15137f8edf6c09742227e99b08aaf273" }
]
Lists all KV namespaces associated with the current account ID.
$ wrangler kv:namespace list
$ wrangler kv:namespace list | jq "."
[
{
"id": "06779da6940b431db6e566b4846d64db",
"title": "TEST_NAMESPACE"
},
{
"id": "32ac1b3c2ed34ed3b397268817dea9ea",
"title": "STATIC_CONTENT"
}
]
Deletes a given KV namespace.
$ wrangler kv:namespace delete [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, to delete.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace to delete.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
{{}}
$ wrangler kv:namespace delete --binding=MY_KV
Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n]
yes
Deleting namespace f7b02e7fc70443149ac906dd81ec1791
Deleted namespace f7b02e7fc70443149ac906dd81ec1791
$ wrangler kv:namespace delete --binding=MY_KV --preview
Are you sure you want to delete namespace 15137f8edf6c09742227e99b08aaf273? [y/n]
yes
Deleting namespace 15137f8edf6c09742227e99b08aaf273
Deleted namespace 15137f8edf6c09742227e99b08aaf273
Manage key-value pairs within a KV namespace.
Writes a single key-value pair to a particular KV namespace.
$ wrangler kv:key put <KEY> [VALUE] [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
Exactly one of VALUE
or --path
is required.
{{
{{}}
KEY
{{}}string{{}} {{}}required{{}}- The key to write to.
VALUE
{{}}string{{}} {{}}optional{{}}- The value to write.
--path
{{}}optional{{}}- When defined, the value is loaded from the file at
--path
rather than reading it from theVALUE
argument. This is ideal for security-sensitive operations because it avoids saving keys and values into your terminal history.
- When defined, the value is loaded from the file at
--binding
{{}}string{{}}- The binding name of the KV namespace, as stored in the
wrangler.toml
file, where the key-pair will be stored.
- The binding name of the KV namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the KV namespace where the key-pair will be stored.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
--ttl
{{}}number{{}} {{}}optional{{}}- The lifetime (in number of seconds) that the key-value pair should exist before expiring. Must be at least
60
seconds. This option takes precedence over theexpiration
option.
- The lifetime (in number of seconds) that the key-value pair should exist before expiring. Must be at least
--expiration
{{}}number{{}} {{}}optional{{}}- The timestamp, in UNIX seconds, indicating when the key-value pair should expire.
--metadata
{{}}string{{}} {{}}optional{{}}- Any (escaped) JSON serialized arbitrary object to a maximum of 1024 bytes.
{{}}
$ wrangler kv:key put --binding=MY_KV "my-key" "some-value"
Writing the value "some-value" to key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
$ wrangler kv:key put --binding=MY_KV --preview "my-key" "some-value"
Writing the value "some-value" to key "my-key" on namespace 15137f8edf6c09742227e99b08aaf273.
$ wrangler kv:key put --binding=MY_KV "my-key" "some-value" --ttl=10000
Writing the value "some-value" to key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
$ wrangler kv:key put --binding=MY_KV "my-key" --path=value.txt
Writing the contents of value.txt to the key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
Reads a single value by key from the given KV namespace.
$ wrangler kv:key get <KEY> [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
KEY
{{}}string{{}} {{}}required{{}}- The key value to get.
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, where the key-pair is stored.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace where the key-pair is stored.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
{{}}
$ wrangler kv:key get --binding=MY_KV "my-key"
value
Outputs a list of all keys in a given KV namespace.
$ wrangler kv:key list [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, from which keys are listed.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace from which keys are listed.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
--prefix
{{}}string{{}} {{}}optional{{}}- Only list keys that begin with the given prefix.
{{}}
$ wrangler kv:key list --binding=MY_KV --prefix="public" | jq "."
[
{
"name": "public_key"
},
{
"name": "public_key_with_expiration",
"expiration": "2019-09-10T23:18:58Z"
}
]
Removes a single key value pair from the given namespace.
$ wrangler kv:key delete <KEY> [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
KEY
{{}}string{{}} {{}}required{{}}- The key value to get.
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, from where the key is removed.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace from which the key is removed.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
{{}}
$ wrangler kv:key delete --binding=MY_KV "my-key"
Deleting the key "my-key" on namespace f7b02e7fc70443149ac906dd81ec1791.
Manage multiple key-value pairs within a KV namespace in batches.
Writes a JSON file containing an array of key-value pairs to the given namespace.
$ wrangler kv:bulk put <FILENAME> [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
FILENAME
{{}}string{{}} {{}}required{{}}- The JSON file containing an array of key-value pairs to write to the namespace.
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, from which key-pairs are bulked.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace from which key-pairs are bulked.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
{{}}
This command takes a JSON file as an argument with a list of key-value pairs to upload. An example of JSON input:
[
{
"key": "test_key",
"value": "test_value",
"expiration_ttl": 3600
}
]
KV namespace values can only store strings. In order to save complex a value, stringify it to JSON:
[
{
"key": "test_key",
"value": "{\"name\": \"test_value\"}",
"expiration_ttl": 3600
}
]
Here is the full schema for key-value entries uploaded via the bulk API:
{{}}
key
{{}}string{{}} {{}}required{{}}- The key’s name. The name may be 512 bytes maximum. All printable, non-whitespace characters are valid.
value
{{}}string{{}} {{}}required{{}}- The UTF-8 encoded string to be stored, up to 25 MB in length.
metadata
{{}}object{{}} {{}}optional{{}}- Any arbitrary object (must serialize to JSON) to a maximum of 1024 bytes.
expiration
{{}}number{{}} {{}}optional{{}}- The time, measured in number of seconds since the UNIX epoch, at which the key should expire.
expiration_ttl
{{}}number{{}} {{}}optional{{}}- The number of seconds the document should exist before expiring. Must be at least
60
seconds.
- The number of seconds the document should exist before expiring. Must be at least
base64
{{}}boolean{{}} {{}}optional{{}}- When true, the server will decode the value as base64 before storing it. This is useful for writing values that would otherwise be invalid JSON strings, such as images. Defaults to
false
.
- When true, the server will decode the value as base64 before storing it. This is useful for writing values that would otherwise be invalid JSON strings, such as images. Defaults to
{{}}
{{
}} If bothexpiration
and expiration_ttl
are specified for a given key, the API will prefer expiration_ttl
.
{{}}
$ wrangler kv:bulk put --binding=MY_KV allthethingsupload.json
Success!
Deletes all keys read from a JSON file within a given namespace.
$ wrangler kv:bulk delete <FILENAME> [OPTIONS]
{{
}} Exactly one of--binding
or --namespace-id
is required.
{{}}
{{}}
FILENAME
{{}}string{{}} {{}}required{{}}- The JSON file containing an array of keys to delete from the namespace.
--binding
{{}}string{{}}- The binding name of the namespace, as stored in the
wrangler.toml
file, from which keys are removed.
- The binding name of the namespace, as stored in the
--namespace-id
{{}}string{{}}- The ID of the namespace from which keys are removed.
--env
{{}}string{{}} {{}}optional{{}}- Perform on a specific environment.
--preview
{{}}boolean{{}} {{}}optional{{}}- Interact with a preview namespace instead of production.
{{}}
This command takes a JSON file as an argument containing an array of keys to delete. Here is an example of the JSON input:
["test_key_1", "test_key_2"]
$ wrangler kv:bulk delete --binding=MY_KV allthethingsdelete.json
? Are you sure you want to delete all keys in allthethingsdelete.json from kv-namespace with id "f7b02e7fc70443149ac906dd81ec1791"? › (Y/n)
Success!