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 ignite3 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., -u).

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:

• -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, 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:

ignite3 cli config set ignite.cluster-endpoint-url=http://localhost:3344

The configuration file location should be configurable through environment variable:

export IGNITE_CLI_CONFIG_FILE=./.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

non-REPL mode

clear

This is a REPL-only command.

exit

Stop current interactive session. This is a REPL-only command.

connect

Connects to a cluster. This is a REPL-only command.

disconnect

Disconnects the current session. This is a REPL-only command.

sql

REPL mode

non-REPL mode

version

REPL mode

non-REPL mode

cluster

cluster init

Initializes cluster in a way described in IEP-77.

REPL mode

non-REPL mode

meta-storage-node is a list with a minimum 1 argument, cmg-node is a list but could be empty.

Has to be rendered in HOCON format.

REPL mode

non-REPL mode

cluster config update

REPL mode

non-REPL mode

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

non-REPL mode

cluster topology logical

REPL mode

non-REPL mode

node

node status

Shows the status of the node. Could be starting, started, stopping, and recovering.

REPL mode

non-REPL mode

node config show

Has to be rendered in HOCON format.

REPL mode

non-REPL mode

node config update

REPL mode

non-REPL mode

node version

REPL mode

non-REPL mode

node metric enable

REPL mode

non-REPL mode

node metric disable

REPL mode

non-REPL mode

node metric list

REPL mode

non-REPL mode

cli config 

cli config get

REPL mode

non-REPL mode

cli config set

REPL mode

non-REPL mode

cli config show

REPL mode

non-REPL mode

cli config profile

REPL mode

non-REPL mode

cli config profile show

Opened tickets

Closed tickets