RFC - KV Commands / Queries

[ashleymichal]

Overview

Providing a fully CLI-driven experience for KV requires that users interact with the KV API in order to perform operations on and query namespaces and key value pairs for their account outside the context of a Worker project. Using Wrangler it should be possible for a developer to fully automate deploying and maintaining a Workers/KV project, complete with provisioning namespaces, writing key/value pairs, and pushing code (if necessary). This means providing basic commands for interacting with all of the documented KV endpoints:

• Create namespace Add KV Command: Create Namespace #340 ✅
• Remove namespace Add KV Command: Remove Namespace #341 ✅
• List all namespaces associated with your account Add KV Command: List Namespaces #342 ✅
• Rename namespace Add KV Command: Rename Namespace #348 ✅
• Write value for key in a namespace (with or without expiration) Add KV Command: Write Key/Value Pair on Namespace #343
• Delete key value pair in a namespace Add KV Command: Remove Key/Value Pair from Namespace #344
• List all keys for a namespace Add KV Command: List Key/Value Pairs for Namespace #345
• Read the value for a key within a namespace Add KV Command: Get Value for Key in Namespace #349
• bulk write/delete for key/value pairs. Add KV Command: Bulk Set Key/Value Pair on Namespace #346 Add KV Command: Bulk Remove Key/Value Pair from Namespace #347 (needs design)

Interactions

$ wrangler kv:namespace create <title> [--env]
$ wrangler kv:namespace delete <binding> [--env]
$ wrangler kv:namespace rename <binding> <new-title> [--env]
$ wrangler kv:namespace list [--env]
$ wrangler kv:key write <binding> <key>=<value> [--env | --ttl | --exp]
$ wrangler kv:key delete <binding> <key> [--env]
$ wrangler kv:key list <binding> [--env]
$ wrangler kv:bulk write <binding> ./path/to/data.json [--env]
$ wrangler kv:bulk delete <binding> ./path/to/data.json [--env]

Stretch goal: bulk upload/delete these are required.

Pre-work - not necessary before, will be post-work.

#63 would be a nice-to-have prior to this, but most of the work is in the http module right now so a big refactor is not necessary. Perhaps wrapping that and providing a kv_client with methods for each action would be appropriate. If that pattern is appreciated we can extend it to the existing workers calls with a workers_client and a preview_client.

Security

One security consideration: we should empower users to protect sensitive data. Leaving values as plain text arguments in the command will leak data into shell history wherever the data is written; we need to take this into consideration either in documentation, or in the design of the command.

[ashleymichal]

One existing constraint: All KV commands require an account_id to make requests. We can either:

1. Require that users run KV commands in the context of an existing Wrangler project.
2. Partially implement WIP RFC: Automatically configure account_id and zone_id #331 by asking for account id in wrangler config, which would allow kv subcommands to be run anywhere.

Given that most of our users will likely be using these subcommands in the context of a project, we can probably get away with the former for now and wait for user requests to make these commands global.

[exvuma]

Renaming a namespace adds a lot of complexity and confusion with low value imo.

Unrelated idea: feedback from customers is the name of the bindings and the name namespace itself is confusing. It'd be cool if our CLI could simplify this by just having one name for a namespace/binding

[ashleymichal]

none of these commands have anything to do with adding namespace bindings to a wrangler project, fwiw. Renaming (re-titling if you will) is an operation already supported by the kv api.

re: bindings names and namespace titles, i intend to also include information clearing that up, and i think the uses outweigh the initial confusion: just like with a conventional application, one could easily have, say, a "staging" namespace and a "production" namespace which use the same bindings but attach to different namespaces by id depending on the environment. this ties in nicely with #385 .