MySQL Shell is a command-line shell for MySQL Server that has the capability for
interactive and batch code execution.  It also offers a wealth of APIs that make it easier and more efficient to work with and manage MySQL servers. In 8.0.13, we made an effort to make those APIs easily accessible straight from the command line. We call it the API command line integration and believe that this new way of interacting with Shell global objects will be quite useful for developers, DBAs or anyone wanting to embed built-in shell commands within their own scripts.

Before this API integration, calling methods from MySQL Shell global objects via the command-line interface had to be done using the --execute(-e) option. Doing so can be a bit tricky because of the quoting and escaping that can be necessary.

For instance look at this example of how you would create a cluster with the -e option.

With the new syntax the call can be rewritten in a command line friendly way:

This simple example showcases the advantages of the new syntax. It requires fewer quoting and escaping (sometimes none at all) and by doing so it is less cumbersome and less error-prone to integrate MySQL Shell into your automation scripts. These advantages are more noticeable as examples become more complex.

API Command Line Integration Syntax

The API Command Line Integration introduces a new syntax for invoking built-in shell commands:
mysqlsh [OPTIONS] [URI] -- <object_name> <method_name> [ argument_list ]

The double dashes “--” indicate that an API command will be executed. Parameters to its left are interpreted as parameters for the shell (i.e. connection data) and the parameters to its right are interpreted as parameters for the API call as follows:

• object_name – a case-sensitive string that used to specify the MySQL Shell object to interact with. The supported objects are dba, cluster, shell, shell.options and util.
• method_name – a case-sensitive string with the name of the method to be called on the object specified by object_name in alternative command line typing friendly format, i.e., all lower case, words separated by hyphens. Javascript and Python formats are also supported.
• argument_list – the arguments passed to the call of the method_name method.

If an invalid object_name or method_name is provided, the shell will exit with return code 10.

Argument List Syntax

On this new syntax, both  object_name  and method_name are mandatory case-sensitive strings and have no further rules.  The argument_list, on the other hand, is optional and has a syntax to follow. There are two types of arguments that can be used on the argument_list: positional arguments and named arguments.  Their usage must adhere to the following syntax:
[ positional_argument ]* [ { named_argument* } ]* [ named_argument ]*

• all parts of the syntax are optional and can be given in any order.
• nesting of curly brackets is forbidden.
• all the named_arguments have to have unique key 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 tied together as a single dictionary and passed as the last parameter to the method
• named arguments grouped inside curly brackets are tied together into a single dictionary
• positional arguments and dictionaries resulting from grouped named arguments are inserted into the Argument_list in the order they appear on the command line

This information and more can be accessed on the MySQL Shell built- in help:

Examples

With this new API integration, calling built-in shell commands is easier and less cumbersome than with the -e option. Below are some examples that try to demonstrate it.

Checking if a server can be upgraded

Before 8.0.13:

After:

Importing JSON document to a server

The importing of JSON documents is also a new feature of MySQL Shell 8.0.13. There are two alternative formats for the command line invocation. You can use the Shell API command line integration syntax, which accepts input only from a file, or the --import command, which accepts input from standard input or a file. With the Shell API command line integration syntax, you invoke the utility as follows:

Creating a sandbox

In order to create a sandbox you would have had to do the following:

After 8.0.13 with the new syntax:

Checking if an instance is correctly configured for InnoDB cluster

Before 8.0.13

With the new syntax:

Checking the status of a cluster

Before 8.0.13:

After:

Adding an instance to a cluster

Before 8.0.13:

After:

Try it now and send us your feedback

MySQL Shell 8.0.13 GA is available for download from the following links.

• MySQL developers website: https://dev.mysql.com/downloads/shell/
• MySQL Shell is also available on GitHub: https://github.com/mysql/mysql-shell

The documentation of MySQL Shell can be found here: https://dev.mysql.com/doc/mysql-shell/8.0/en/

Enjoy, and Thank you for using MySQL!