This repository has been archived by the owner on Aug 3, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 337
Feat kv commands #405
Merged
Merged
Feat kv commands #405
Changes from 54 commits
Commits
Show all changes
62 commits
Select commit
Hold shift + click to select a range
731f9b6
feat: use cloudflare-rs
ashleymichal 5169f34
feat: #340 first draft of wrangler kv add <namespace>
ashleymichal 59fdb64
Add documentation for kv create
ashleymichal 22e9052
refactor: handle success in endpoint caller
ashleymichal b8bc14b
feat: kv delete <namespace>
ashleymichal 1ff3c02
feat: kv rename
ashleymichal b5fbdd2
Merge pull request #403 from cloudflare/alewis/feat-rename-namespace
ashleymichal 2e4a9ee
feat: kv list (raw output)
ashleymichal 3900fb6
Pretty up list output
ashleymichal 1c05b10
correct rename output example in docs
ashleymichal c0dd867
Merge pull request #404 from cloudflare/alewis/feat-list-namespaces
ashleymichal 22fc8c6
Update cloudflare-rs invocations to match updates
ashleymichal 1022df1
Merge pull request #437 from cloudflare/alewis/update-dependencies
ashleymichal 13ec991
Merge remote-tracking branch 'origin/master' into feat-kv-commands
ashleymichal bcea204
update cloudflare-rs invocations
ashleymichal 3e1b854
Merge remote-tracking branch 'origin/master' into feat-kv-commands
ashleymichal 8f3a14e
Add gets for single keys from Workers KV (#454)
gabbifish a1ff27a
Add individual write subcommand for Workers KV (#458)
gabbifish df8219a
Add bulk upload to Workers KV (#445)
gabbifish 408c34e
Implementation of single and bulk deletion from KV (#452)
gabbifish ed43c93
Merge branch 'master' into feat-kv-commands
ashleymichal 725ea2f
Add key listing functionality for workers kv subcommands (#462)
gabbifish 464667b
make error message about lack of workers kv entitlements more clear
gabbifish eb1bca8
fix #406: remove panics and ensure required args for kv subcommands a…
gabbifish acb6892
clarify Workers KV upgrade error
gabbifish 7c27abb
Gabbi/improve bulk error handling (#466)
gabbifish e87e5eb
Merge branch 'master' into feat-kv-commands
ashleymichal 4752e23
Remove logic for uploading directories from bulk (#485)
ashleymichal d8a04c6
Update kv docs
ashleymichal 4f1c239
Gabbi/update subcommand invocations (#501)
gabbifish a1d72bf
Merge pull request #503 from cloudflare/alewis/kv-docs
ashleymichal 570f5ef
Gabbi/url encode (#507)
gabbifish 70b7ea9
Update usage of cloudflare::Credentials::User -> UserAuthKey
ashleymichal f1469a5
Gabbi/add interactive delete (#511)
gabbifish c5a4995
Merge pull request #520 from cloudflare/alewis/update-dependencies
ashleymichal 5f20b4e
refactor: pass project to kv commands in prep for environments
ashleymichal e3800e2
Merge pull request #526 from cloudflare/alewis/refactor-pass-project
ashleymichal ee872bc
refactor: organize kv by command type
ashleymichal 264de89
Merge pull request #527 from cloudflare/alewis/refactor-directories
ashleymichal 8fb1f56
Use url encoded strings for list keys prefixes
gabbifish ad5b33b
Gabbi/more detailed subcommand docs (#537)
gabbifish bfe8d92
Alewis/refactor key list (#531)
ashleymichal e71a91d
Fix merge conflict in src/main.rs
gabbifish 4237934
s/project/target
gabbifish aac2161
fix with steve's feedback
gabbifish f55263d
use cloudflare-rs package from crates.io (#549)
gabbifish 28de238
Gabbi/add kv env support (#542)
gabbifish bf19955
remove `kv:namespace rename` subcommand (#555)
gabbifish f667c7b
Gabbi/perscriptive namespace titles (#557)
gabbifish 69ac09a
Print out namespaces list as json by default (#541)
gabbifish 267caf9
Gabbi/merge master in (#562)
gabbifish bd9f4f5
warn user to remove binding if deleted + check input for bindings (#560)
gabbifish a8926e7
Re-order kv commands docs to be more user friendly (#558)
EverlastingBugstopper 109b3a5
Update readme to point people to KV commands docs (#568)
gabbifish e71e699
fix links to environmenets
gabbifish 399cf3c
Allow use of same json file to bulk delete as bulk put
ashleymichal ec5ff3f
Merge pull request #577 from cloudflare/alewis/bulk-delete
ashleymichal d33ce50
Merge 09/12 merges to master into feat-kv-commands (#580)
gabbifish 81ac1e6
Fix panic when `kv: ` command does not have subcommand (#579)
gabbifish 6c3d133
Merge branch 'master' into feat-kv-commands
ashleymichal 17e98f4
Resolve merge conflicts in README
ashleymichal 293ff89
Fix links to environments docs
ashleymichal File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,330 @@ | ||
# 🗂️ `kv` | ||
|
||
## Overview | ||
|
||
The `kv` subcommand allows you to store application data in the Cloudflare network to be accessed from Workers, using | ||
[Workers KV](https://www.cloudflare.com/products/workers-kv/). | ||
KV operations are scoped to your account, so in order to use any of these commands, you need to: | ||
|
||
* have a Wrangler project set up with your `account_id` configured in the `wrangler.toml` | ||
ashleymichal marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* call commands from within a Wrangler project directory. | ||
|
||
## Getting Started | ||
|
||
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. | ||
|
||
The `kv:namespace` subcommand takes as a new binding name as an argument. It will create a Worker KV namespace | ||
whose title is a concatenation of your Worker's name (from `wrangler.toml`) and the binding name you provide: | ||
```console | ||
$ wrangler kv:namespace create "MY_KV" | ||
🌀 Creating namespace with title "worker-MY_KV" | ||
✨ Success: WorkersKvNamespace { | ||
id: "e29b263ab50e42ce9b637fa8370175e8", | ||
title: "worker-MY_KV", | ||
} | ||
✨ Add the following to your wrangler.toml: | ||
kv-namespaces = [ | ||
{ binding: "MY_KV", id: "e29b263ab50e42ce9b637fa8370175e8" } | ||
] | ||
``` | ||
Make sure to add the `kv-namespaces` output above to your `wrangler.toml`. You can now | ||
access it from a Worker with code like: | ||
```js | ||
let value = await MY_KV.get("my-key"); | ||
``` | ||
The full KV API for Workers can be found [here](https://developers.cloudflare.com/workers/reference/storage/). | ||
|
||
To put a value to your KV namespace via Wrangler, use the `kv:key put` subcommand. | ||
```console | ||
$ wrangler kv:key put --binding=MY_KV "key" "value" | ||
✨ Success | ||
``` | ||
You can also specify which namespace to put your key-value pair into using `--namespace-id` instead of `--binding`: | ||
```console | ||
$ wrangler kv:key put --namespace-id=e29b263ab50e42ce9b637fa8370175e8 "key" "value" | ||
✨ Success | ||
``` | ||
|
||
Additionally, KV namespaces can be used with [environments](./environments.md)! This is useful for when you have code 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). So, if you have a `wrangler.toml` with two environments: | ||
|
||
```toml | ||
[env.staging] | ||
kv-namespaces = [ | ||
{ binding: "MY_KV", id: "e29b263ab50e42ce9b637fa8370175e8" } | ||
] | ||
|
||
[env.production] | ||
kv-namespaces = [ | ||
{ binding: "MY_KV", id: "a825455ce00f4f7282403da85269f8ea" } | ||
] | ||
``` | ||
|
||
To insert a value into a specific KV namespace, you can use | ||
```console | ||
$ wrangler kv:key put --env=staging --binding=MY_MV "key" "value" | ||
✨ Success | ||
``` | ||
|
||
Since `--namespace-id` is always unique (unlike binding names), you don't need to pass environment variables for them (they will be unused). | ||
|
||
There are way more helpful Wrangler subcommands for interacting with Workers KV, like ones for bulk uploads and deletes--check them out below! | ||
|
||
## Concepts | ||
|
||
Most `kv` commands require you to specify a namespace. A namespace can be specified in two ways: | ||
|
||
1. With a `--binding`: | ||
```sh | ||
wrangler kv:key get --binding=KV "my key" | ||
``` | ||
1. With a `--namespace_id`: | ||
```sh | ||
wrangler kv:key get --namespace-id=06779da6940b431db6e566b4846d64db "my key" | ||
``` | ||
|
||
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`: | ||
|
||
```toml | ||
type = "webpack" | ||
name = "my-worker" | ||
account_id = "<account id here>" | ||
route = "staging.example.com/*" | ||
workers_dot_dev = false | ||
|
||
kv-namespaces = [ | ||
{ binding = "KV", id = "06779da6940b431db6e566b4846d64db" } | ||
] | ||
|
||
[env.production] | ||
route = "example.com/*" | ||
kv-namespaces = [ | ||
{ binding = "KV", id = "07bc1f3d1f2a4fd8a45a7e026e2681c6" } | ||
] | ||
``` | ||
|
||
With the wrangler.toml above, you can specify `--env production` when you want to perform a KV action on | ||
the namespace `KV` under `env.production`. For example, with the wrangler.toml above, you can get a value | ||
out of a production KV instance with: | ||
|
||
```console | ||
wrangler kv:key get --binding "KV" --env=production "my key" | ||
``` | ||
|
||
To learn more about environments, check out the [environments documentation](./environments.md). | ||
|
||
## `kv:namespace` | ||
|
||
### `create` | ||
|
||
Creates a new namespace. | ||
|
||
Takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:namespace create "MY_KV" | ||
🌀 Creating namespace with title "worker-MY_KV" | ||
✨ Success: WorkersKvNamespace { | ||
id: "e29b263ab50e42ce9b637fa8370175e8", | ||
title: "worker-MY_KV", | ||
} | ||
✨ Add the following to your wrangler.toml: | ||
kv-namespaces = [ | ||
{ binding: "MY_KV", id: "e29b263ab50e42ce9b637fa8370175e8" } | ||
] | ||
``` | ||
|
||
### `list` | ||
|
||
Outputs a list of all KV namespaces associated with your account id. | ||
|
||
#### Usage | ||
The example below uses the `jq` command line tool to pretty-print output. | ||
|
||
```console | ||
$ wrangler kv:namespace list | jq '.' | ||
[ | ||
{ | ||
"id": "06779da6940b431db6e566b4846d64db", | ||
"title": "TEST_NAMESPACE" | ||
}, | ||
{ | ||
"id": "32ac1b3c2ed34ed3b397268817dea9ea", | ||
"title": "STATIC_CONTENT" | ||
} | ||
] | ||
``` | ||
|
||
### `delete` | ||
|
||
Deletes a given namespace. | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:namespace delete --binding=KV | ||
Are you sure you want to delete namespace f7b02e7fc70443149ac906dd81ec1791? [y/n] | ||
yes | ||
🌀 Deleting namespace f7b02e7fc70443149ac906dd81ec1791 | ||
✨ Success | ||
``` | ||
|
||
## `kv:key` | ||
|
||
### `put` | ||
|
||
Writes a single key/value pair to the given namespace. | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Optional params include: | ||
|
||
1. `--env`: The [environment](./environments.md) argument. | ||
1. `--ttl`: Number of seconds for which the entries should be visible before they expire. At least 60. Takes precedence over 'expiration' option. | ||
1. `--expiration`: Number of seconds since the UNIX epoch, indicating when the key-value pair should expire. | ||
1. `--path`: Read value from the file at a given path. *This is good for security-sensitive operations, like uploading keys to KV; uploading from a file prevents a key value from being saved in areas like your terminal history.* | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:key put --binding=KV "key" "value" --ttl=10000 | ||
✨ Success | ||
``` | ||
|
||
```console | ||
$ wrangler kv:key put --binding=KV "key" value.txt --path | ||
✨ Success | ||
``` | ||
|
||
### `list` | ||
|
||
Outputs a list of all keys in a given namespace. | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Optional params include: | ||
|
||
1. `--env`: The [environment](./environments.md) argument. | ||
1. `--prefix`: A prefix to filter listed keys. | ||
|
||
#### Usage | ||
|
||
The example below uses the `jq` command line tool to pretty-print output. | ||
|
||
```console | ||
$ wrangler kv:key list --binding=KV --prefix="public" | jq '.' | ||
[ | ||
{ | ||
"name": "public_key" | ||
}, | ||
{ | ||
"name": "public_key_with_expiration", | ||
"expiration": "2019-09-10T23:18:58Z" | ||
} | ||
] | ||
``` | ||
|
||
### `get` | ||
|
||
Reads a single value by key from the given namespace. | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:key get --binding=KV "key" | ||
value | ||
``` | ||
|
||
### `delete` | ||
|
||
Removes a single key value pair from the given namespace. | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:key delete --binding=KV "key" | ||
Are you sure you want to delete key "key"? [y/n] | ||
yes | ||
🌀 Deleting key "key" | ||
✨ Success | ||
``` | ||
|
||
## `kv:bulk` | ||
|
||
### `put` | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Writes a file full of key/value pairs to the given namespace. Takes as an argument a JSON file with a list of key-value pairs to upload (see JSON spec above). An example of JSON input: | ||
|
||
```json | ||
[ | ||
{ | ||
"key": "test_key", | ||
"value": "test_value", | ||
"expiration_ttl": 3600 | ||
} | ||
] | ||
``` | ||
|
||
The schema below is the full schema for key-value entries uploaded via the bulk API: | ||
|
||
| **Name** | **Description** | Optional | | ||
| ------------------------------ | ------------------------------------------------------------ | -------- | | ||
| `key`<br />(String) | A key's name. The name may be at most 512 bytes. All printable, non-whitespace characters are valid. | no | | ||
| `value`<br />(String) | A UTF-8 encoded string to be stored, up to 2 MB in length. | no | | ||
| `expiration`<br />(Number) | The time, measured in number of seconds since the UNIX epoch, at which the key should expire. | yes | | ||
| `expiration_ttl`<br />(Number) | The number of seconds for which the key should be visible before it expires. At least 60. | yes | | ||
| `base64`<br />(Boolean) | Whether or not the server should base64 decode the value before storing it. Useful for writing values that wouldn't otherwise be valid JSON strings, such as images. Defaults to `false` | yes | | ||
|
||
If both `expiration` and `expiration_ttl` are specified for a given key, the API will prefer `expiration_ttl`. | ||
|
||
The `put` command also takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:bulk put --binding=KV allthethingsupload.json | ||
✨ Success | ||
``` | ||
|
||
### `delete` | ||
|
||
Requires `--binding` or `--namespace-id` argument. | ||
|
||
Deletes all specified keys within a given namespace. | ||
Takes as an argument a JSON file with a list of keys to delete; for example: | ||
|
||
```json | ||
[ | ||
"key1", | ||
"key2" | ||
] | ||
``` | ||
|
||
The `delete` command also takes an optional `--env` [environment](./environments.md) argument. | ||
|
||
#### Usage | ||
|
||
```console | ||
$ wrangler kv:bulk delete --binding=KV allthethingsdelete.json | ||
Are you sure you want to delete all keys in allthethingsdelete.json? [y/n] | ||
yes | ||
✨ Success | ||
``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This file was renamed. I might be wrong but I believe I saw a link to this doc printed out in my terminal.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is correct
@gabbifish do you mind updating the instances of /docs/environments.md to /docs/content/environments.md?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do!