THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
| ID | IEP-88 |
| Author | |
| Sponsor | |
| Created |
|
| Status | DRAFT |
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 completion: 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 ignite command is executed without parameters.
Communication with the cluster
The tool should connect to a remote cluster via REST endpoints provided by the cluster. REST client can be generated from Open API specification (see IEP-87). For SQL REPL mode the JDBC is used.
This approach seems to be de-facto standard for client-server communicaiton model. CLI can connect to any cluster it has network connection to.
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-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.
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 default set cluster-url=http://localhost:3344
Exit codes
Exit codes have to be mapped with Ignite 3 error codes.
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 help | Full list of commands with their descriptions | |
ignite help <command> | ignite <command> --help[-h] | Detailed help for a specific command |
connect
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 |
disconnect
Disconnects the current session. This is a REPL-only command.
| command spec | description |
|---|---|
disconnect | Disconnect the current session |
status
REPL mode
| command spec | description |
|---|---|
status | Show the status of the connected cluster |
non-REPL mode
| command spec | description |
|---|---|
ignite status [--cluster-url] | Show the status of the cluster |
init
REPL mode
| command spec | description |
|---|---|
init [--configuration-file] | Initialize the connected cluster with a distributed configuration |
non-REPL mode
| command spec | description |
|---|---|
ignite init [--cluster-url][--configuration-file] | Initialize the cluster with a distributed configuration |
config show
REPL mode
| command spec | description |
|---|---|
config show [--selector][--node-id] | Read the connected cluster (or local node if --node-id specified) configuration |
non-REPL mode
| command spec | description |
|---|---|
ignite config show [--cluster-url][--selector][--node-id] | Read the cluster (or local node if --node-id specified) configuration |
config update
REPL mode
| command spec | description |
|---|---|
config update [--node-id] <config in HOCON format or path to file> | Update the connected cluster (or local node if --node-id specified) configuration with provided HOCON configuration |
non-REPL mode
| command spec | description |
|---|---|
ignite config update [--cluster-url][--node-id] <config in HOCON format or path to file> | Update the cluster (or local node if --node-id specified) configuration with provided HOCON configuration |
sql
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 |
version
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 |
default get
REPL mode
| command spec | alias | description |
|---|---|---|
default get <config key> | defaults (~ 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 default get <config key> | ignite defaults | Show the default config value for the CLI Tool. Displays all default configs if called without parameter |
default set
REPL mode
| command spec | description |
|---|---|
default set <config key-value> | Set the default config value for the CLI Tool |
non-REPL mode
| command spec | description |
|---|---|
ignite default set <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
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 |
Open tickets
Closed tickets
Overview
Content Tools
Apps
