The MySQL Shell provides global objects that expose different
functionality, such as
InnoDB Cluster and InnoDB ReplicaSet management
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
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
Dictionaries: key-value pairs where the key is a string
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
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.
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]*
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_objectwhich should be executed.
[anonymous_arguments|named arguments]*: specifies the arguments passed to the
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
$ 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
trueare 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,
--pathare 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
arguments is important as they are processed in
a positional way. On the other hand,
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.