ID | IEP-88 |
Author | |
Sponsor | |
Created |
|
Status | ACTIVE |
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:
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:
REPL mode is used by default and is activated if the ignite
command is executed without parameters.
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:
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.
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-url
), and an optional short single-character version starting with a single dash (e.g., -c
).
The long version name can be separated from the value by either a space or by ‘=’:
--cluster-url localhost:8080
--cluster-url=localhost:8080
The short version name can be separated from the value only by a space:
-c 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 -a -b -c
is equivalent to ignite -abc
.
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 cli config set cluster-url=http://localhost:3344
There should an option to use a custom configuration file that is put on CLI run:
ignite topology --cli-config=./.config/path
Exit codes have to be mapped with Ignite 3 error codes.
KsqlDB can be queried from Ksql CLI https://docs.ksqldb.io/en/latest/operate-and-deploy/installation/cli-config/.
https://github.com/hazelcast/hazelcast-commandline-client
https://docs.snowflake.com/en/user-guide/snowsql-use.html
Help must be available for every command and should include at least the following:
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 help | Full list of commands with their descriptions | |
ignite help <command> | ignite <command> --help[-h] | Detailed help for a specific command |
This is a REPL-only command.
command spec | description |
---|---|
clear | Clear the terminal |
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
command spec | description |
---|---|
bootstrap | Install artifacts and create working directories on the local machine |
non-REPL mode
command spec | description |
---|---|
ignite bootsrap | Install artifacts and create working directories on the local machine |
Connects to a cluster. This is a REPL-only command.
command spec | description |
---|---|
connect [--cluster-url] | Create a session for the cluster, i.e. subsequent commands do not require the cluster URL anymore |
Disconnects the current session. This is a REPL-only command.
command spec | description |
---|---|
disconnect | Disconnect the current session |
Initializes cluster in a way described in IEP-77.
REPL mode
command spec | description |
---|---|
cluster init [--cluster-url]<--meta-storage-node>[--cmg-node]<--cluster-name> | Initialize the connected cluster |
non-REPL mode
command spec | description |
---|---|
ignite cluster init [--cluster-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.
Show the detailed status of the cluster including name, topology, etc.
REPL mode
command spec | description |
---|---|
cluster status [--cluster-url] | Show the status of the cluster |
non-REPL mode
command spec | description |
---|---|
ignite cluster status | 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-url][--selector] | Show connected cluster configuration |
non-REPL mode
command spec | description |
---|---|
ignite cluster config show [--cluster-url][--selector] | Show connected cluster configuration |
REPL mode
command spec | description |
---|---|
cluster config update [--cluster-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 cluster config update [--cluster-url] <config in HOCON format or path to file> | Update the cluster configuration with provided HOCON configuration |
Start the Ignite 3 node.
REPL mode
command spec | description |
---|---|
node start [--config] <nodeName> | Start node with the default configuration or reads the config from --config option |
non-REPL mode
command spec | description |
---|---|
ignite node start [--config] <nodeName> | Start node with the default configuration or reads the config from --config option |
Stop the Ignite 3 node.
REPL mode
command spec | description |
---|---|
node stop <nodeName> | Stop node |
non-REPL mode
command spec | description |
---|---|
ignite node stop <nodeName> | Stop node |
Shows the status of the node. Could be starting, started, stopping, and recovering.
REPL mode
command spec | description |
---|---|
node status [--node-url] | Shows the node status |
non-REPL mode
command spec | description |
---|---|
ignite node status [--node-url] | Shows the node status |
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 |
---|---|
ignite node config show [--node-url][--selector] | Read the local node configuration |
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 |
---|---|
ignite node config update [--node-url] <config in HOCON format or path to file> | Update the local node configuration with provided HOCON configuration |
REPL mode
command spec | description |
---|---|
node list | Show the list of nodes running locally |
non-REPL mode
command spec | description |
---|---|
ignite node list | Show the list of nodes running locally |
REPL mode
command spec | description |
---|---|
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 [--cluster-url][--script-file] <query> | Execute sql query and print the result |
REPL mode
command spec | alias | description |
---|---|---|
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 |
REPL mode
command spec | alias | description |
---|---|---|
cli config get <config key> | cli configs (~ default get without parameters) | Show the default config value for the CLI Tool. Displays all default configs if called without parameter |
non-REPL mode
command spec | alias | description |
---|---|---|
ignite cli config get <config key> | ignite cli configs | Show the default config value for the CLI Tool. Displays all default configs if called without parameter |
REPL mode
command spec | description |
---|---|
cli config set <config key-value> | Set the default config value for the CLI Tool |
non-REPL mode
command spec | description |
---|---|
ignite cli config set <config key-value> | Set the default config value for the CLI Tool |
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
REPL mode
command spec | description |
---|---|
topology | Show the topology of the connected cluster |
non-REPL mode
command spec | description |
---|---|
ignite topology [--cluster-url] | Show the topology of the cluster |