5.8.2.1 Command Line Integration for MySQL Shell API Functions

The MySQL Shell provides global objects that expose different functionality, such as dba for InnoDB Cluster and InnoDB ReplicaSet management operations, util for the utility functions, and so on. Global objects provide functions which are called from the scripting modes in the MySQL Shell. In addition to the interactive MySQL Shell integration, you can use the command-line integration to call object functions directly from the terminal, enabling you to easily integrate with other tools.

When you use the APIs included with MySQL Shell in the interactive mode, the typical function syntax is as follows:

object.functionName(parameter1, parameter2, ..., parameterN)

The parameters define the order in which the data should be provided to the API function. In most cases, API functions expect the parameters in a specific data type, however there are a few exceptions where a specific parameter can handle multiple data types. The data types used for parameters in API functions can be one of the following:

Scalars: string, numbers, booleans, null
Lists
Dictionaries: key-value pairs where the key is a string
Objects

List parameters are typically restricted to contain elements of a pre-defined data type, for example a list of strings, however, there could be list parameters that support items of different data types.

Dictionary parameters accept key-value pairs, where keys are strings. The value associated to a key is usually expected to be of a pre-defined data type. However, there might be cases where different data types are supported for values by the same key. Dictionary parameters can therefore be one of the following types:

A pre-defined set of keys-value pairs is allowed, in which case specifying keys not in the pre-defined set results in an error.
No pre-defined set of key-value pairs exists, the dictionary accepts any key

In other words, some dictionary parameters specify which keys are valid. For those parameters, attempting to use a key outside of that set results in an error. When no pre-defined set of values exists, any value of any data type can be used. Dictionary parameters that do not have a pre-defined list of keys, accept any key-value pair as long as the key is not in the pre-defined set of a different dictionary parameter.

To use the command-line integration to call API functions exposed by global objects without having to start an interactive session in the MySQL Shell you must provide the required data in the correct way. This includes defining the way an API function is called, as well as the way its parameters are mapped from command-line arguments to API arguments.

Important

Not all of the MySQL Shell functions are exposed by the command-line integration. For example a function such as dba.getCluster() relies on returning an object which is then used in further operations. Such operations are not exposed by the command-line integration.

Similarly, the MySQL Shell command-line integration does not support Objects as parameters. Any API function with a parameter of type object cannot be used with the command-line integration. The lifetime of the object is limited to the lifetime of the MySQL Shell invocation that created it. Since mysqlsh exits immediately after executing an object method through this API syntax, any objects received from or passed into an API call would immediately be out of scope. This should be considered while developing MySQL Shell Plugins that you want to expose with the command-line integration.

The general format to call a MySQL Shell API function from the command-line is:

$ mysqlsh [shell options] -- [shell_object]+ object_function [anonymous_arguments|named arguments]*

Where:

shell_object: specifies a global object with functions exposed for command-line usage. Supports nested objects in a list separated by spaces.
object_function: specifies the API function of the last shell_object which should be executed.
[anonymous_arguments|named arguments]*: specifies the arguments passed to the object_function call

For most of the available APIs a single object is required, for example:

$ mysqlsh -- shell status

But for nested objects, the list of objects must be indicated. For example, to call a function exposed by shell.options, such as setPersist(optionName, value), use the syntax:

$ mysqlsh -- shell options set-persist defaultMode py

A similar situation might happen with nested objects defined in MySQL Shell Plugins.

The arguments you pass to functions can be divided into the following types:

Anonymous Arguments: which are raw values provided to the command. For example, in the following call 1, one and true are anonymous arguments:
```
$ mysqlsh -- object command 1 one true
```
Named Arguments: which are key-value pairs provided in the form of --key=value. For example in the following call, --sample and --path are named arguments:
```
$ mysqlsh -- object command 1 one true --sample=3 --path=some/path
```

Given this division of arguments, the general format to call an API function from the command-line integration is:

$ mysqlsh [shell options] -- object command [anonymous arguments][named arguments]

The order of any anonymous arguments is important as they are processed in a positional way. On the other hand, named arguments can appear anywhere as they are processed first and are associated to the corresponding parameter. Once named arguments are processed, the anonymous arguments are processed in a positional way.