5.8 API Command Line Interface

MySQL Shell exposes much of its functionality using an API command syntax that enables you to easily integrate mysqlsh with other tools. This functionality is similar to using the --execute option, but the command interface uses a simplified argument syntax which reduces the quoting and escaping that can be required by terminals. For example if you want to create an InnoDB Cluster using a bash script, you could use this functionality.

The following built-in MySQL Shell global objects are available:

session - represents the current global session.
db - represents the default database for the global session, if that session was established using an X Protocol connection with a default database specified.
cluster - represents an InnoDB Cluster.
dba - provides access to InnoDB cluster administration functions using the AdminAPI. See Chapter 6, Using MySQL AdminAPI.
shell - global provides access to MySQL Shell functions, such as shell.options for configuring MySQL Shell options (see Section 10.4, “Configuring MySQL Shell Options”), and shell.reports for running MySQL Shell reports (see Section 7.1, “Reporting with MySQL Shell”).
util - provides access to MySQL Shell utilities. See Chapter 8, MySQL Shell Utilities.

API Command Line Integration Syntax

When you start MySQL Shell on the command-line using the following special syntax, the -- indicates the end of the list of options and everything after it is treated as a command and its arguments.

mysqlsh [options] -- shell_object object_method [arguments]

where the following applies:

shell_object is a string which maps to a MySQL Shell global object.
object_method is the name of the method provided by the shell_object. The method names can be provided following either the JavaScript, Python or an alternative command line typing friendly format, where all known methods use all lower case letters, and words are separated by hyphens. The name of a object_method is automatically converted from the standard JavaScript style camelCase name, where all case changes are replaced with a - and turned into lowercase. For example, getCluster becomes get-cluster.
arguments are the arguments passed to the object_method when it is called.

shell_object must match one of the exposed global objects, and object_method must match one of the global object's methods in one of the valid formats (JavaScript, Python or command line friendly). If they do not correspond to a valid global object and its methods, MySQL Shell exits with status 10.

API Command Line Integration Argument Syntax

The arguments list is optional and all arguments must follow a syntax suitable for command-line use as described in this section. For example, special characters that are handled by the system shell (bash, cmd, and so on) should be avoided and if quoting is needed, only the quoting of the parent shell should be considered. In other words, if “foo bar” is used as a parameter in bash, the quotes are stripped and escapes are handled.

There are two types of arguments that can be used in the list of arguments: positional arguments and named arguments. Positional arguments are for example simple types such as strings, numbers, boolean, null. Named arguments are key value pairs, where the values are simple types. Their usage must adhere to the following pattern:

[ positional_argument ]* [ { named_argument* } ]* [ named_argument ]*

The rules for using this syntax are:

all parts of the syntax are optional and can be given in any order
nesting of curly brackets is forbidden
all the key values supplied as named arguments must have unique names inside their scope. The scope is either ungrouped or in a group (inside the curly brackets).

These arguments are then converted into the arguments passed to the method call in the following way:

all ungrouped named arguments independent to where they appear are combined into a single dictionary and passed as the last parameter to the method
named arguments grouped inside curly brackets are combined into a single dictionary
positional arguments and dictionaries resulting from grouped named arguments are inserted into the arguments list in the order they appear on the command line

API Interface Examples

Using the API integration, calling MySQL Shell commands is easier and less cumbersome than with the --execute option. The following examples show how to use this functionality:

To check a server instance is suitable for upgrade and return the results as JSON for further processing:

$ mysqlsh -- util check-for-server-upgrade { --user=root --host=localhost --port=3301 } --password='password' --outputFormat=JSON --config-path=/etc/mysql/my.cnf

This maps to the equivalent command in MySQL Shell:

mysql-js> util.checkForServerUpgrade({user:'root', host:'localhost', port:3301}, {password:'password', outputFormat:'JSON', configPath:'/etc/mysql/my.cnf'})

To deploy an InnoDB Cluster sandbox instance, listening on port 1234 and specifying the password used to connect:
```
$ mysqlsh -- dba deploy-sandbox-instance 1234 --password=password 
```
This maps to the equivalent command in MySQL Shell:
```
mysql-js> dba.deploySandboxInstance(1234, {password: password})
```
To create an InnoDB Cluster using the sandbox instance listening on port 1234 and specifying the name mycluster:
```
$ mysqlsh root@localhost:1234 -- dba create-cluster mycluster
```
This maps to the equivalent command in MySQL Shell:
```
mysql-js> dba.createCluster('mycluster')
```
To check the status of an InnoDB Cluster using the sandbox instance listening on port 1234:
```
$ mysqlsh root@localhost:1234 -- cluster status
```
This maps to the equivalent command in MySQL Shell:
```
mysql-js> cluster.status()
```

To configure MySQL Shell to turn the command history on:

$ mysqlsh -- shell.options set_persist history.autoSave true

This maps to the equivalent command in MySQL Shell:

mysql-js> shell.options.set_persist('history.autoSave', true);