From 4bdc8227f1104876783ae640c17e4913afdbde3b Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Tue, 26 Feb 2019 13:52:15 -0800 Subject: [PATCH 1/8] TiKV Command Line RFC Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 208 ++++++++++++++++++++ 1 file changed, 208 insertions(+) create mode 100644 text/2019-02-26-tikv-client-command-line.md diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md new file mode 100644 index 00000000..95e76cdf --- /dev/null +++ b/text/2019-02-26-tikv-client-command-line.md @@ -0,0 +1,208 @@ +# TiKV Rust Client Command Line Tool + +## Summary + +Use the TiKV Rust Client to build a simple command line tool for inspection and anaylsis. + +This tool will stand as an analogue to `mycli` or `mysql-client` for users. + +## Motivation + +Currently `tikv-ctl` offers some ways to interact with a TiKV cluster, it +focuses mostly on the *management* of a TiKV cluster instead of a *client* for +the cluster. + +With the `tikv-client` crate users will find a way to interact with their TiKV +cluster from their application. Some users will find it desirable to be able to +inspect their cluster from a command line tool, or otherwise outside of their +application. + +Building a simple command line tool to execute commands such as `get`, `set`, +`delete`, and `scan` would mean users do not need to worry about creating such +tools for themselves. + +It also provides us with a useful tool during the development cycle, as it will +be very easy to issue one-off commands to TiKV. + +Further, we mentioned in the Rust Client RFC +(https://github.com/tikv/rfcs/pull/7) we mentioned we wanted to accomplish this. + +## Detailed design + +The client will be created using the `tikv-client` crate and its already existing +functionality. It will utilize `clap` to provide a simple wrapper around the +crate API. + +### Install + +We will build this tool in the `tikv-cli` repository. It will be published. +Users will be able to install it with `cargo install tikv-cli`. (See +*Alternatives* for another option.) + +### Configuration + +The tool will retrieve its configuration from one of the following places, in +order of precedence (greatest to least): + +* The command line options, such as `--pd 127.0.0.1:2379`. +* A local configuration file `./.tikv-cli.toml` +* The global configuration file `${XDG_CONFIG_HOME}/tikv-cli.toml`. +* The default options (connect to localhost, no TLS). + +The options are: + +```toml +[connection] +# A list of `pd` endpoints. +pd_endpoints = [ + "127.0.0.1:2379", + "127.0.0.2:2379", +] + +[tls] +# The path of the CA file for TLS. +ca_path = "./rsa.ca" +# The path of the certificate file for TLS. +cert_path = "./rsa.cert" +# The path of the key file for TLS. +key_path = "./rsa.key" + +[output] +# If the ouput JSON should be minified. +minify = false +# Level of logging to use. Available: error. warn, info, debug, trace +logging = "info" +``` + +### Input/Output + +By default input is by positional arguments in `bash`/`sh` string format. + +By default the tool will output in prettyprinted JSON. For single entry results, +it will return a string (including `"`), for key-value pairs it will use a JSON +object `{ key: "", value: "" }`, for multiple results it will return a JSON +array. Errors will use an `{ error: "" }` object. Opting out of prettyprint will +be via the `--minify` flag. + +JSON was chosen because it is an efficient, pervasive, human-readable, modern +standard that has many tools (eg `jq`) to use for post processing if needed. + +All standard (non-logging) output will be on `stdout`. + +It will feature configurable logging levels with `slog` which will output to `stderr`. + +The tool will exit zero on successful requests, and non-zero on unsuccessful +requests. In the case of REPL mode, it shall always exit zero. + +### Interacting with it + +Users will interact with the tool through the command line. It will support both +a one-off mode or a REPL (Read-eval-print-loop) style mode (See alternatives). + +Example of the one-off raw mode: + +```bash +$ tikv-cli raw set "cncf" "linux foundation" +Finished in 0.001s. +$ tikv-cli raw set "tikv" "rust" +Finished in 0.001s. +$ tikv-cli raw get "cncf" +"linux foundation" +Finished in 0.002s. +$ tikv-cli raw scan "b".. +[ + { key: "cncf", value: "linux foundation" }, + { key: "tikv", value: "rust" }, +] +Finished in 0.003s. +``` + +Example of REPL raw mode: + +```bash +$ tikv-cli raw +> set "cncf" "linux foundation" +Finished in 0.001s. +> set "tikv" "rust" +Finished in 0.001s. +> get "cncf" +"linux foundation" +Finished in 0.001s. +> scan "b".. +[ + { key: "cncf", value: "linux foundation" }, + { key: "tikv", value: "rust" }, +] +Finished in 0.003s. +``` + +REPL transactional mode, notice how the `>>` communicates that the user is in a +transaction. Also notice how the transaction timestamp is outputted in the +request complete messages. + +```bash +$ tikv-cli txn +> begin +Finished in 0.000s. (txn ts: 1551216224838) +>>set "cncf" "linux foundation" +Finished in 0.001s. (txn ts: 1551216224838) +>> set "tikv" "rust" +Finished in 0.001s. (txn ts: 1551216224838) +>> get "cncf" +"linux foundation" +Finished in 0.001s. (txn ts: 1551216224838) +>> scan "b".. +[ + { key: "cncf", value: "linux foundation" }, + { key: "tikv", value: "rust" }, +] +Finished in 0.003s. (txn ts: 1551216224838) +> commit +Finished in 0.001s. (txn ts: 1551216224838) +``` + +One-off transactional mode is a bit different, as we need some way to maintain +timestamp across commands. The user may choose how to do this, the reccomended +way is via ENV variables, but they must do this. (See alternatives) + +```bash +$ TS=$(tikv-cli txn begin) +$ tikv-cli txn ${TS} set "cncf" "linux foundation" +Finished in 0.001s. (txn ts: 1551216224838) +$ tikv-cli txn ${TS} set "tikv" "rust" +Finished in 0.001s. (txn ts: 1551216224838) +$ tikv-cli txn ${TS} get "cncf" +"linux foundation" +Finished in 0.002s. (txn ts: 1551216224838) +$ tikv-cli txn ${TS} scan "b".. +[ + { key: "cncf", value: "linux foundation" }, + { key: "tikv", value: "rust" }, +] +Finished in 0.003s. (txn ts: 1551216224838) +$ tikv-cli txn ${TS} commit +Finished in 0.004s. (txn ts: 1551216224838) +``` + +## Drawbacks + +We may not wish to need to maintain this tool, or we may wish for the community +to maintain it. + +## Alternatives + +* *(Installation/Repo)* We could use the `tikv-client` repository and provide + either an opt-out or an opt-in binary from `src/bin/tikv-cli.rs`. If we chose + an opt-in functionality here users mgiht end up with an awkard installation + call. +* (*Use `tikv-cli`*), we could use `tikv-cli` for this, but it creates as fuzzy + distinction between management tools and clients. +* (*No REPL, or only REPL*). We may chose to not have a REPL mode, or we may chose + to *only* have a REPL mode. +* (*A different timestamp handling for one-off mode*). We may find the way we + handle timestamps in transactional one-off mode to be unwieldly. Perhaps there + is a better way. + +## Unresolved questions + +We must decide if there are other alternatives we want to favor. From 8f8621c1d8d24f75a866c71b15392bc10806be1d Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Mon, 4 Mar 2019 13:32:03 -0800 Subject: [PATCH 2/8] Fixup log levels and add API note. Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index 95e76cdf..2e95e3e0 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -70,7 +70,7 @@ key_path = "./rsa.key" [output] # If the ouput JSON should be minified. minify = false -# Level of logging to use. Available: error. warn, info, debug, trace +# Level of logging to use. Available: critical, error, warning, info, debug, trace logging = "info" ``` @@ -99,6 +99,9 @@ requests. In the case of REPL mode, it shall always exit zero. Users will interact with the tool through the command line. It will support both a one-off mode or a REPL (Read-eval-print-loop) style mode (See alternatives). +Due to the nature of TiKV having two APIs, *raw* and *transactional* we need to +support both APIs. Learn about the differences [here](https://tikv.org/docs/architecture/#apis). + Example of the one-off raw mode: ```bash @@ -162,7 +165,7 @@ Finished in 0.001s. (txn ts: 1551216224838) ``` One-off transactional mode is a bit different, as we need some way to maintain -timestamp across commands. The user may choose how to do this, the reccomended +timestamp across commands. The user may choose how to do this, the recommended way is via ENV variables, but they must do this. (See alternatives) ```bash @@ -186,8 +189,8 @@ Finished in 0.004s. (txn ts: 1551216224838) ## Drawbacks -We may not wish to need to maintain this tool, or we may wish for the community -to maintain it. +This will increase our maintenance burden, so it may be better to leave this up +to independent community efforts. ## Alternatives From 67801d26bfec31b7319f57c2b91bd312faa573f1 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Mon, 4 Mar 2019 16:22:08 -0800 Subject: [PATCH 3/8] Refinements to API Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 94 +++++++++++++-------- 1 file changed, 57 insertions(+), 37 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index 2e95e3e0..e2bedbfd 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -12,7 +12,7 @@ Currently `tikv-ctl` offers some ways to interact with a TiKV cluster, it focuses mostly on the *management* of a TiKV cluster instead of a *client* for the cluster. -With the `tikv-client` crate users will find a way to interact with their TiKV +With the `tikv-client` Rust crate users will find a way to interact with their TiKV cluster from their application. Some users will find it desirable to be able to inspect their cluster from a command line tool, or otherwise outside of their application. @@ -54,6 +54,7 @@ The options are: ```toml [connection] # A list of `pd` endpoints. +# Default: None pd_endpoints = [ "127.0.0.1:2379", "127.0.0.2:2379", @@ -61,19 +62,36 @@ pd_endpoints = [ [tls] # The path of the CA file for TLS. +# Default: None ca_path = "./rsa.ca" # The path of the certificate file for TLS. +# Default: None cert_path = "./rsa.cert" # The path of the key file for TLS. +# Default: None key_path = "./rsa.key" -[output] +[client] +# Level of logging to use. +# Available: critical, error, warning, info, debug, trace +# Default: info +logging = "info" # If the ouput JSON should be minified. +# Default: false minify = false -# Level of logging to use. Available: critical, error, warning, info, debug, trace -logging = "info" +# The mode the client should be in. +# All clients connected to a keyspace should use the same mode. +# Available: raw, transaction +# Default: transaction +mode = "transaction" +# If the tool should output on stderr the duration of commands. +# Default: true +output-durations = true ``` +On the command line, these options have the same name, but with `_` replaced +with `-` for idiomatic reasons. + ### Input/Output By default input is by positional arguments in `bash`/`sh` string format. @@ -92,27 +110,27 @@ All standard (non-logging) output will be on `stdout`. It will feature configurable logging levels with `slog` which will output to `stderr`. The tool will exit zero on successful requests, and non-zero on unsuccessful -requests. In the case of REPL mode, it shall always exit zero. +requests. In the case of REPL mode, it shall exit zero unless the connection is +found to be lost. ### Interacting with it Users will interact with the tool through the command line. It will support both a one-off mode or a REPL (Read-eval-print-loop) style mode (See alternatives). -Due to the nature of TiKV having two APIs, *raw* and *transactional* we need to -support both APIs. Learn about the differences [here](https://tikv.org/docs/architecture/#apis). +TiKV has two APIs, *raw* and *transactional*, both are supported. Learn about the differences [here](https://tikv.org/docs/architecture/#apis). Example of the one-off raw mode: ```bash -$ tikv-cli raw set "cncf" "linux foundation" +$ tikv-cli --mode raw set "cncf" "linux foundation" Finished in 0.001s. -$ tikv-cli raw set "tikv" "rust" +$ tikv-cli --mode raw set "tikv" "rust" Finished in 0.001s. -$ tikv-cli raw get "cncf" +$ tikv-cli --mode raw get "cncf" "linux foundation" Finished in 0.002s. -$ tikv-cli raw scan "b".. +$ tikv-cli --mode raw scan "b".. [ { key: "cncf", value: "linux foundation" }, { key: "tikv", value: "rust" }, @@ -123,7 +141,7 @@ Finished in 0.003s. Example of REPL raw mode: ```bash -$ tikv-cli raw +$ tikv-cli --mode raw > set "cncf" "linux foundation" Finished in 0.001s. > set "tikv" "rust" @@ -139,12 +157,12 @@ Finished in 0.001s. Finished in 0.003s. ``` -REPL transactional mode, notice how the `>>` communicates that the user is in a -transaction. Also notice how the transaction timestamp is outputted in the -request complete messages. +In the REPL of the *(default)* transactional mode below, the `>>` communicates +that the user is in a transaction. Also notice how the transaction timestamp is +outputted in the request complete messages. ```bash -$ tikv-cli txn +$ tikv-cli > begin Finished in 0.000s. (txn ts: 1551216224838) >>set "cncf" "linux foundation" @@ -160,31 +178,36 @@ Finished in 0.001s. (txn ts: 1551216224838) { key: "tikv", value: "rust" }, ] Finished in 0.003s. (txn ts: 1551216224838) -> commit +>> commit Finished in 0.001s. (txn ts: 1551216224838) ``` -One-off transactional mode is a bit different, as we need some way to maintain -timestamp across commands. The user may choose how to do this, the recommended -way is via ENV variables, but they must do this. (See alternatives) +One-off transactional mode is a bit different, a series of commands can be +provided as a list. Begin and commit are inserted implictly at the start and end +of the command. This creates a 'command level atomicity'. + +In most scripting uses, we expect users will newline separate commands. + +The output is a JSON array, with each index having the result of the respective +command. In the case of command such as `set` which have no output, a `null` is +used. ```bash -$ TS=$(tikv-cli txn begin) -$ tikv-cli txn ${TS} set "cncf" "linux foundation" -Finished in 0.001s. (txn ts: 1551216224838) -$ tikv-cli txn ${TS} set "tikv" "rust" -Finished in 0.001s. (txn ts: 1551216224838) -$ tikv-cli txn ${TS} get "cncf" -"linux foundation" -Finished in 0.002s. (txn ts: 1551216224838) -$ tikv-cli txn ${TS} scan "b".. +$ tikv-cli \ + set "cncf" "linux foundation" \ + set "tikv" "rust" \ + get "cncf" \ + scan "b".. [ - { key: "cncf", value: "linux foundation" }, - { key: "tikv", value: "rust" }, + null, + null, + "linux foundation", + [ + { key: "cncf", value: "linux foundation" }, + { key: "tikv", value: "rust" }, + ], ] -Finished in 0.003s. (txn ts: 1551216224838) -$ tikv-cli txn ${TS} commit -Finished in 0.004s. (txn ts: 1551216224838) +Finished in 0.003s. ``` ## Drawbacks @@ -202,9 +225,6 @@ to independent community efforts. distinction between management tools and clients. * (*No REPL, or only REPL*). We may chose to not have a REPL mode, or we may chose to *only* have a REPL mode. -* (*A different timestamp handling for one-off mode*). We may find the way we - handle timestamps in transactional one-off mode to be unwieldly. Perhaps there - is a better way. ## Unresolved questions From 68ee7e054f69cd7dea732decd4fb4cee0d7dd6c8 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Mon, 4 Mar 2019 16:28:34 -0800 Subject: [PATCH 4/8] Fix line length Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index e2bedbfd..9b6ce174 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -118,7 +118,8 @@ found to be lost. Users will interact with the tool through the command line. It will support both a one-off mode or a REPL (Read-eval-print-loop) style mode (See alternatives). -TiKV has two APIs, *raw* and *transactional*, both are supported. Learn about the differences [here](https://tikv.org/docs/architecture/#apis). +TiKV has two APIs, *raw* and *transactional*, both are supported. Learn about the +differences [here](https://tikv.org/docs/architecture/#apis). Example of the one-off raw mode: From 004c6e8c129544f8911faf340f3295722db8d276 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Wed, 6 Mar 2019 09:39:23 -0800 Subject: [PATCH 5/8] Various clarifications Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 38 ++++++++++----------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index 9b6ce174..55d19e46 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -2,40 +2,40 @@ ## Summary -Use the TiKV Rust Client to build a simple command line tool for inspection and anaylsis. +Use the TiKV Rust Client to build a simple command line tool for inspection and analysis. This tool will stand as an analogue to `mycli` or `mysql-client` for users. ## Motivation -Currently `tikv-ctl` offers some ways to interact with a TiKV cluster, it +While `tikv-ctl` offers some ways to interact with a TiKV cluster, it focuses mostly on the *management* of a TiKV cluster instead of a *client* for the cluster. -With the `tikv-client` Rust crate users will find a way to interact with their TiKV +With the `tikv-client` Rust crate, users will find a way to interact with their TiKV cluster from their application. Some users will find it desirable to be able to inspect their cluster from a command line tool, or otherwise outside of their application. Building a simple command line tool to execute commands such as `get`, `set`, -`delete`, and `scan` would mean users do not need to worry about creating such +`delete`, or `scan` means users do not need to worry about creating such tools for themselves. It also provides us with a useful tool during the development cycle, as it will be very easy to issue one-off commands to TiKV. -Further, we mentioned in the Rust Client RFC -(https://github.com/tikv/rfcs/pull/7) we mentioned we wanted to accomplish this. +Plus, this tool is one of the goals we mentioned in the Rust Client RFC +(https://github.com/tikv/rfcs/pull/7). ## Detailed design -The client will be created using the `tikv-client` crate and its already existing -functionality. It will utilize `clap` to provide a simple wrapper around the -crate API. +The client will be created using the `tikv-client` crate and existing +functionality. `clap` and `serde` will be used to provide a simple wrapper +around the crate API. ### Install -We will build this tool in the `tikv-cli` repository. It will be published. +This tool will be built in the `tikv-cli` repository. It will be published. Users will be able to install it with `cargo install tikv-cli`. (See *Alternatives* for another option.) @@ -44,10 +44,10 @@ Users will be able to install it with `cargo install tikv-cli`. (See The tool will retrieve its configuration from one of the following places, in order of precedence (greatest to least): -* The command line options, such as `--pd 127.0.0.1:2379`. +* Command line flags, such as `--pd 127.0.0.1:2379`. * A local configuration file `./.tikv-cli.toml` -* The global configuration file `${XDG_CONFIG_HOME}/tikv-cli.toml`. -* The default options (connect to localhost, no TLS). +* A global configuration file `${XDG_CONFIG_HOME}/tikv-cli.toml`. +* Default options (connect to localhost, no TLS). The options are: @@ -102,24 +102,24 @@ object `{ key: "", value: "" }`, for multiple results it will return a JSON array. Errors will use an `{ error: "" }` object. Opting out of prettyprint will be via the `--minify` flag. -JSON was chosen because it is an efficient, pervasive, human-readable, modern +JSON is chosen because it is an efficient, pervasive, human-readable, modern standard that has many tools (eg `jq`) to use for post processing if needed. All standard (non-logging) output will be on `stdout`. It will feature configurable logging levels with `slog` which will output to `stderr`. -The tool will exit zero on successful requests, and non-zero on unsuccessful +The tool will exit with exit code zero on successful requests, and non-zero on unsuccessful requests. In the case of REPL mode, it shall exit zero unless the connection is found to be lost. ### Interacting with it -Users will interact with the tool through the command line. It will support both -a one-off mode or a REPL (Read-eval-print-loop) style mode (See alternatives). +Users will interact with the tool through a command line interface. It will +support both one-off mode or REPL (Read-eval-print-loop) style mode (See [alternatives](#Alternatives)). -TiKV has two APIs, *raw* and *transactional*, both are supported. Learn about the -differences [here](https://tikv.org/docs/architecture/#apis). +TiKV has two APIs, *raw* and *transactional*, both are supported by this tool. +Learn about the differences [here](https://tikv.org/docs/architecture/#apis). Example of the one-off raw mode: From 8799896aeffa35840a968b48553a6f86a1862ba8 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Thu, 21 Mar 2019 14:30:06 -0700 Subject: [PATCH 6/8] Structure one-off-txn mode better Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index 55d19e46..dbb86d39 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -180,12 +180,14 @@ Finished in 0.001s. (txn ts: 1551216224838) ] Finished in 0.003s. (txn ts: 1551216224838) >> commit -Finished in 0.001s. (txn ts: 1551216224838) +Finished in 0.001s. (txn ts: 1551216224838, commit ts: 1551216224838) ``` One-off transactional mode is a bit different, a series of commands can be -provided as a list. Begin and commit are inserted implictly at the start and end -of the command. This creates a 'command level atomicity'. +provided as a list. This is similar to an 'Auto-commit mode' where `begin` and +`commit` are inserted implictly at the start and end of the command. If any +commands fail, the entire transaction is rolled back and the program exits with +a non-zero exit code. In most scripting uses, we expect users will newline separate commands. From 43e4fe9f6b71a1ea828083e750948aac78f85002 Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Wed, 8 May 2019 10:57:34 -0700 Subject: [PATCH 7/8] Reflect new plans Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 58 ++++++++++++++------- 1 file changed, 40 insertions(+), 18 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index dbb86d39..23ff2ad1 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -35,9 +35,9 @@ around the crate API. ### Install -This tool will be built in the `tikv-cli` repository. It will be published. -Users will be able to install it with `cargo install tikv-cli`. (See -*Alternatives* for another option.) +This tool will be built in the `client-rust` repository. It will be published. +Users will be able to install it with +`cargo install tikv-client --features cli`. (See *Alternatives* for another option.) ### Configuration @@ -45,8 +45,9 @@ The tool will retrieve its configuration from one of the following places, in order of precedence (greatest to least): * Command line flags, such as `--pd 127.0.0.1:2379`. -* A local configuration file `./.tikv-cli.toml` -* A global configuration file `${XDG_CONFIG_HOME}/tikv-cli.toml`. +* A local configuration file `./.tikv-client.toml` +* A global configuration file `${XDG_CONFIG_HOME}/tikv-client.toml` (or + comparable cross platform options) * Default options (connect to localhost, no TLS). The options are: @@ -86,7 +87,13 @@ minify = false mode = "transaction" # If the tool should output on stderr the duration of commands. # Default: true -output-durations = true +output_durations = true +# Control the encoding. +# TiKV has a Unified Key Format which is used in cases where a more human readable format is +# required for non-UTF-8 data. +# Avaiable: utf-8, ukf, profobuffer, hex +key-encoding = "utf-8" +value-encoding = "utf-8" ``` On the command line, these options have the same name, but with `_` replaced @@ -113,10 +120,23 @@ The tool will exit with exit code zero on successful requests, and non-zero on u requests. In the case of REPL mode, it shall exit zero unless the connection is found to be lost. +TiKV is often used in cases where a key or value is not a UTF-8 compatible +string, or may print undesirable control characters to the console. We provide the +`key-encoding` and `value-encoding` configuration options to control this. + +For most users, their natural first attempt with the client will be to use UTF-8 +strings for both keys and values. In order to prevent confusion, we default to +UTF-8 for both and make the options for `*-encoding` discoverable. + +The `key-encoding` and `value-encoding` options support `utf-8`, `ukf` (TiKV's +Unified Key format), `protobuffer`, or `hex`. (There is a potential use of +values to store keys.) + ### Interacting with it Users will interact with the tool through a command line interface. It will -support both one-off mode or REPL (Read-eval-print-loop) style mode (See [alternatives](#Alternatives)). +support both one-off mode or REPL (Read-eval-print-loop) style mode +(See [alternatives](#Alternatives)). TiKV has two APIs, *raw* and *transactional*, both are supported by this tool. Learn about the differences [here](https://tikv.org/docs/architecture/#apis). @@ -124,14 +144,14 @@ Learn about the differences [here](https://tikv.org/docs/architecture/#apis). Example of the one-off raw mode: ```bash -$ tikv-cli --mode raw set "cncf" "linux foundation" +$ tikv-client --mode raw set "cncf" "linux foundation" Finished in 0.001s. -$ tikv-cli --mode raw set "tikv" "rust" +$ tikv-client --mode raw set "tikv" "rust" Finished in 0.001s. -$ tikv-cli --mode raw get "cncf" +$ tikv-client --mode raw get "cncf" "linux foundation" Finished in 0.002s. -$ tikv-cli --mode raw scan "b".. +$ tikv-client --mode raw scan "b" .. [ { key: "cncf", value: "linux foundation" }, { key: "tikv", value: "rust" }, @@ -142,7 +162,7 @@ Finished in 0.003s. Example of REPL raw mode: ```bash -$ tikv-cli --mode raw +$ tikv-client --mode raw > set "cncf" "linux foundation" Finished in 0.001s. > set "tikv" "rust" @@ -163,7 +183,7 @@ that the user is in a transaction. Also notice how the transaction timestamp is outputted in the request complete messages. ```bash -$ tikv-cli +$ tikv-client > begin Finished in 0.000s. (txn ts: 1551216224838) >>set "cncf" "linux foundation" @@ -196,7 +216,7 @@ command. In the case of command such as `set` which have no output, a `null` is used. ```bash -$ tikv-cli \ +$ tikv-client \ set "cncf" "linux foundation" \ set "tikv" "rust" \ get "cncf" \ @@ -213,6 +233,12 @@ $ tikv-cli \ Finished in 0.003s. ``` +## Future Work + +We plan to eventually spin off this command line interface into an independent +project as it matures. For the time being it will provide a very convenient way +to use and test the Rust client. + ## Drawbacks This will increase our maintenance burden, so it may be better to leave this up @@ -220,10 +246,6 @@ to independent community efforts. ## Alternatives -* *(Installation/Repo)* We could use the `tikv-client` repository and provide - either an opt-out or an opt-in binary from `src/bin/tikv-cli.rs`. If we chose - an opt-in functionality here users mgiht end up with an awkard installation - call. * (*Use `tikv-cli`*), we could use `tikv-cli` for this, but it creates as fuzzy distinction between management tools and clients. * (*No REPL, or only REPL*). We may chose to not have a REPL mode, or we may chose From 8fc3b1d86c38de592369c078c814977d07462b0b Mon Sep 17 00:00:00 2001 From: Ana Hobden Date: Mon, 29 Jul 2019 11:11:28 -0700 Subject: [PATCH 8/8] Reflect sciamp-dev feedback Signed-off-by: Ana Hobden --- text/2019-02-26-tikv-client-command-line.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/text/2019-02-26-tikv-client-command-line.md b/text/2019-02-26-tikv-client-command-line.md index 23ff2ad1..d3031de5 100644 --- a/text/2019-02-26-tikv-client-command-line.md +++ b/text/2019-02-26-tikv-client-command-line.md @@ -55,7 +55,7 @@ The options are: ```toml [connection] # A list of `pd` endpoints. -# Default: None +# Default: "127.0.0.1:2379" pd_endpoints = [ "127.0.0.1:2379", "127.0.0.2:2379", @@ -91,9 +91,9 @@ output_durations = true # Control the encoding. # TiKV has a Unified Key Format which is used in cases where a more human readable format is # required for non-UTF-8 data. -# Avaiable: utf-8, ukf, profobuffer, hex -key-encoding = "utf-8" -value-encoding = "utf-8" +# Avaiable: utf-8, ukf, protobuffer, hex +key_encoding = "utf-8" +value_encoding = "utf-8" ``` On the command line, these options have the same name, but with `_` replaced @@ -122,13 +122,13 @@ found to be lost. TiKV is often used in cases where a key or value is not a UTF-8 compatible string, or may print undesirable control characters to the console. We provide the -`key-encoding` and `value-encoding` configuration options to control this. +`key_encoding` and `value_encoding` configuration options to control this. For most users, their natural first attempt with the client will be to use UTF-8 strings for both keys and values. In order to prevent confusion, we default to UTF-8 for both and make the options for `*-encoding` discoverable. -The `key-encoding` and `value-encoding` options support `utf-8`, `ukf` (TiKV's +The `key_encoding` and `value_encoding` options support `utf-8`, `ukf` (TiKV's Unified Key format), `protobuffer`, or `hex`. (There is a potential use of values to store keys.)