THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Page History
| ID | IEP-88 | ||||||
| Author | |||||||
| Sponsor | |||||||
| Created |
| ||||||
| Status |
|
| Table of Contents |
|---|
Motivation
Ignite 3 CLI tool is a command-line utility that acts as an entry point for all monitoring and management operations with Apache Ignite clusters. A user should download the tool from the website and then use it to:
- Connect to a cluster to monitor its state and perform management operations (configuration changes, cluster init).
- Connect to a cluster to run SQL queries.
- Connect to a cluster to get the cluster status (topology, version).
Description
The tool should be designed and developed with an explicit focus on usability and respect for https://clig.dev/#guidelines. In addition to regular commands, it should feature a fully-fledged REPL for different functions. REPL mode must provide the following capabilities:
- Advanced command autocompletion: not only static commands but dynamic completion for parameters and values; in sql mode keywords and dynamic table schema are supported.
- Command history.
- Current status.
REPL mode is used by default and is activated if the igniteignite3 command is executed without parameters.
Communication with the cluster
The tool should connect to a remote cluster via REST endpoints provided by the cluster. For SQL REPL mode the JDBC is used.
Benefits of using REST as a communication realization between CLI and Ignite 3 cluster:
- This approach seems to be the de-facto standard for the client-server communication model.
- CLI can connect to any cluster it has a network connection to.
- REST component already implemented in Ignite 3.
- REST client can be generated from Open API specification (see IEP-87).
Error handling
If a user makes a mistake in syntax, an appropriate error message should be shown. It must describe what exactly is wrong. Possible options: unknown command, unknown parameter, missing mandatory parameter, etc.
In non-REPL mode, if a user attempts to execute a command that is only available in REPL, the tool should suggest using the REPL mode.
Errors and messing should be sent into stderr. The output of commands should be sent to stdout.
Parameters
Generally (exclusions are defined on a case-by-case basis), every parameter for every command should have two name aliases: a long version starting with two dashes (e.g., --cluster-endpoint-url), and an optional short single-character version starting with a single dash (e.g., -cu).
The long version name can be separated from the value by either a space or by ‘=’:
--cluster-endpoint-url localhost:8080--cluster-endpoint-url=localhost:8080
The short version name can be separated from the value only by a space:
-c u localhost:8080
Options without a value (i.e. on-off switches) are allowed. If several such options in a single command are provided using their short names, they can be collapsed. For example, ignite ignite3 -a -b -c is equivalent to ignite -abc.
There's a -v | --verbose parameter which turns on additional logging which can help with debugging errors.
Configuration
CLI tool should have configurable defaults. They could be placed in the config file and modified by the user. Also, a special command can be used to set the default value. For example:
ignite ignite3 cli config set ignite.cluster-endpoint-url=http://localhost:3344
There should an option to use a custom configuration file that is put on CLI run:
The configuration file location should be configurable through environment variable:
export IGNITE_CLI_CONFIG_FILEignite topology --cli-config=./.config/path
ignite3 topology
Exit codes
Exit codes have to be mapped with Ignite 3 error codes.
Quick overview of existing CLIs
Ksql CLI
KsqlDB can be queried from Ksql CLI https://docs.ksqldb.io/en/latest/operate-and-deploy/installation/cli-config/.
- written in Java
- uses REST as a communication protocol
- has interactive and non-interactive modes
- does not support autocompletion
Hazelcast CLI (beta)
https://github.com/hazelcast/hazelcast-commandline-client
- written in go
- uses REST as a communication protocol (hazelcast ships go client)
- supports interactive and non-interactive modes
- has advanced autocompletion in interactive mode
- has custom keyboard shortcuts to navigate in interactive mode
- supports bash autocomplete for non-interactive mode
Snowsql
https://docs.snowflake.com/en/user-guide/snowsql-use.html
- supports scripts execution
- does not support featured non-interactive mode
- has a reach interactive interface
- supports custom commands in interactive mode like "!print", "!define".
- has advanced SQL autocompletion
Command list
help
Help must be available for every command and should include at least the following:
- Description of the command (what it does and when it should be used).
- The general syntax of the command.
- List of available parameters with their names and descriptions.
- Typical usage examples for the command in general, and for specific parameters where appropriate.
REPL mode
| command spec | alias | description |
|---|---|---|
help | Full list of commands with their descriptions | |
help <command> | <command> --help[-h] | Detailed help for a specific command |
non-REPL mode
| command spec | alias | description |
|---|---|---|
ignite ignite3 help | Full list of commands with their descriptions | |
ignite ignite3 help <command> | ignite ignite3 <command> --help[-h] | Detailed help for a specific command |
clear
This is a REPL-only command.
| command spec | description |
|---|---|
clear | Clear the terminal |
exit
Stop current interactive session. This is a REPL-only command.
| command spec | description |
|---|---|
exit | Exit from interactive mode |
Bootstraps the ignite workspace in the local machine. This is the equivalent to the ignite init command from the previous cli version.
REPL mode
bootstrapInstall artifacts and create working directories on the local machine
non-REPL mode
ignite bootsrapInstall artifacts and create working directories on the local machine
connect
Connects to a cluster. This is a REPL-only command.
| command spec | description |
|---|---|
connect [cluster--clusterendpoint-url] | Create a session for the cluster, i.e. subsequent commands do not require the cluster URL anymore |
disconnect
Disconnects the current session. This is a REPL-only command.
| command spec | description |
|---|---|
disconnect | Disconnect the current session |
sql
REPL mode
| command spec | description |
|---|
sql [-- |
jdbc-url |
] [--script-file | query] | If executed without |
non-REPL mode
| command spec | description |
|---|
ignite3 sql [-- |
jdbc-url] |
<--script-file | query> | Execute sql query and print the result |
version
REPL mode
| command spec | alias | description |
|---|---|---|
version | Show the version of the CLI Tool |
non-REPL mode
| command spec | alias | description |
|---|---|---|
ignite3 version | ignite3 --version | Show the version of the CLI Tool |
cluster
cluster init
Initializes cluster in a way described in IEP-77.
REPL mode
| command spec | description |
|---|---|
cluster init [--cluster-endpoint-url] <--meta-storage-node> [--cmg-node] <--cluster-name> | Initialize the connected cluster |
non-REPL mode
| command spec | description |
|---|---|
ignite ignite3 cluster init [--cluster-endpoint-url] <--meta-storage-node> [--cmg-node] <--cluster-name> | Initialize the cluster |
meta-storage-node is a list with a minimum 1 argument, cmg-node is a list but could be empty.
cluster
...
status
Show the detailed status of the cluster including its name, topology, etcstatus, and the number of nodes in physical topology.
REPL mode
| command spec | description |
|---|---|
cluster |
status [--cluster-endpoint-url] | Show the status of the cluster |
non-REPL mode
| command spec | description |
|---|
ignite cluster showignite3 cluster status [--cluster-endpoint-url] | Show the status of the cluster |
cluster config show
Has to be rendered in HOCON format.
REPL mode
| command spec | description |
|---|---|
cluster config show [--cluster-endpoint-url] [--selector] | Read the connected Show cluster configuration configuration |
non-REPL mode
| command spec | description |
|---|---|
ignite ignite3 cluster config show [--cluster-endpoint-url] [--selector] | Read the Show cluster configuration |
cluster config update
REPL mode
| command spec | description |
|---|---|
cluster config update [--cluster-endpoint-url] <config in HOCON format or path to file> | Update the connected cluster configuration with provided HOCON configuration |
non-REPL mode
| command spec | description |
|---|---|
ignite ignite3 cluster config update [--cluster-endpoint-url] <config in HOCON format or path to file> | Update the cluster configuration with provided HOCON configuration |
node start
Start the Ignite 3 node.
cluster topology physical
According to the join protocol, we are going to have two types of node topologies: "physical" (a.k.a. network) topology and "logical" topology. It may be convenient for the user to know which nodes have passed validation and have joined the logical topology, therefore it is suggested to implement a CLI command for this purpose.
Response example:
consistent ID, ID, address, status
node 1, e2d4988a-b836-4e7e-a888-2639e6f79ef0, 127.0.0.1
node 2, 5cb561fc-1963-4f95-98f8-deb407669a86, 127.0.0.2
REPL mode
| command spec | description |
|---|---|
cluster topology physical [--cluster-endpoint-url] | Show the physical topology of the cluster |
non-REPL mode
| command spec | description |
|---|
ignite3 cluster topology physical [-- |
cluster-endpoint-url] |
| Show the physical topology of the cluster |
cluster topology logical
REPL mode
| command spec | description |
|---|---|
cluster topology logical [--cluster-endpoint-url] | Show the logical topology of the cluster |
non-REPL mode
| command spec | description |
|---|
ignite3 cluster topology logical [-- |
cluster-endpoint-url] |
Start node with the default configuration or reads the config from --config option
node stop
| Show the logical topology of the cluster |
node
node status
Shows the status of the node. Could be starting, started, stopping, and recovering.Stop the Ignite 3 node.
REPL mode
| command spec | description |
|---|
node stop <nodeName>node status [--node-url] | Shows the node status |
non-REPL mode
| command spec | description |
|---|
ignite node stop <nodeName>ignite3 node status [--node-url] | Shows the node status |
node config show
Has to be rendered in HOCON format.
REPL mode
| command spec | description |
|---|---|
node config show [--node-url] [ |
selector] | Read the local node configuration |
non-REPL mode
| command spec | description |
|---|
ignite3 node config show [--node-url] [ |
selector] | Read the local node configuration |
node config update
REPL mode
| command spec | description |
|---|---|
node config update [--node-url] <config in HOCON format or path to file> | Update the connected local node configuration with provided HOCON configuration |
non-REPL mode
| command spec | description |
|---|
ignite3 node config update [--node-url] <config in HOCON format or path to file> | Update the local node configuration with provided HOCON configuration |
sql
node version
REPL mode
| command spec | description |
|---|---|
node version | Show the ignite node build version |
non-REPL mode
| command spec | description |
|---|---|
ignite3 node version | Show the ignite node build version |
node metric enable
REPL mode
| command spec | description | ||
|---|---|---|---|
node metric enable [--node-url] <srcName> | Enable node metric source | sql <query> | If executed without parameters, create a SQL connection session within the REPL. From this point, it provides functionality similar to a command-line JDBC tool (e.g., sqlline) |
non-REPL mode
| command spec | description |
|---|---|
ignite sql ignite3 node metric enable [--clusternode-url] <srcName> | Enable node metric source |
node metric disable
REPL mode
| command spec | description |
|---|---|
node metric disable [--script-file] <query> | Execute sql query and print the result |
-node-url] <srcName> | Disable node metric source |
non-REPL mode
| command spec | description |
|---|---|
ignite3 node metric disable [--node-url] <srcName> | Disable node metric source |
node metric list
REPL mode
| command spec | aliasdescription | ||
|---|---|---|---|
node metric list [--node-url] | List node metric sources | version | Show the version of the CLI Tool |
non-REPL mode
| command spec | alias | description | ignite version | ignite --version | Show the version of the CLI Tool
|---|---|---|---|---|
ignite3 node metric list [--node-url] | List node metric sources |
cli config
cli config get
REPL mode
| command spec | alias | description |
|---|---|---|
cli config get <config key> | key> | Show the default config value for the CLI Tool. Displays all default configs if called without parametercurrent profile. |
non-REPL mode
| command spec | aliasdescription | |
|---|---|---|
ignite ignite3 cli config get [--profile] <config key> | Show the default config value for the CLI Tool. Displays all default configs if called without parameterspecified or default profile. |
cli config set
REPL mode
| command spec | description |
|---|---|
cli config set <config key-value> value> | Set the default config value for the CLI Toolcurrent profile. |
non-REPL mode
| command spec | description |
|---|---|
ignite ignite3 cli config set [--profile] <config key-value> | Set the default config value for the CLI Tool |
topology
According to the join protocol, we are going to have two types of node topologies: "physical" (a.k.a. network) topology and "logical" topology. It may be convenient for the user to know which nodes have passed validation and have joined the logical topology, therefore it is suggested to implement a CLI command for this purpose.
Response example:
consistent ID, ID, address, status
node 1, e2d4988a-b836-4e7e-a888-2639e6f79ef0, 127.0.0.1, RUNNING
node 2, 5cb561fc-1963-4f95-98f8-deb407669a86, 127.0.0.2, RECOVERY| specified or default profile. |
cli config show
REPL mode
| command spec | description |
|---|---|
cli config show | Show the config contents for the current profile. |
non-REPL mode
| command spec | description |
|---|---|
ignite3 cli config show [--profile] | Show the config contents for the specified or default profile. |
cli config profile
cli config profile show
REPL mode
| command spec | description |
|---|---|
cli config profile show | Show current default profile of CLI Tool |
non-REPL mode
| command spec | description |
|---|---|
ignite3 cli config show | Show current default profile |
cli config profile show
REPL mode
| command spec | description |
|---|---|
cli config profile list | List profiles of CLI Tool |
non-REPL mode
| command spec | description |
|---|---|
ignite3 cli config list | List profiles |
cli config profile activate
REPL mode
| command spec | description |
|---|---|
cli config profile activate <profileName> | Activate profile as default for CLI Tool |
non-REPL mode
| command spec | description |
|---|---|
ignite3 cli config profile activate <profileName> | Activate profile as default for CLI Tool |
cli config profile create
REPL mode
| command spec | description |
|---|
topologycli config profile create [--name -n] [--copy-from -c] [--activate -a] | Create new profile and optionally copy content from another profile and optionally activate new profile as default for CLI Tool |
non-REPL mode
| command spec | description |
|---|
ignite topology ignite3 cli config profile create [--name -n] [--copy-from -c] [-- |
activate - |
a] | Create new profile and optionally copy content from another profile and optionally activate new profile as default for CLI Tool |
Opened tickets
| Jira | ||||||
|---|---|---|---|---|---|---|
|
Closed tickets
| Jira | ||||||
|---|---|---|---|---|---|---|
|
Overview
Content Tools
Apps