5.8.1 Command Line Integration Overview

This section provides an overview of the command-line integration and some basic usage examples. For more detailed information, see Section 5.8.2, “Command Line Integration Details”.

• MySQL Shell Command Line Integration Syntax

• The Objects Available in the Command Line Integration

• MySQL Shell Command Line Integration Argument Syntax

• MySQL Shell Command Line Integration Examples

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. See Using MySQL as a Document Store.

• dba: provides access to AdminAPI, used to manage InnoDB Cluster, InnoDB ClusterSet, and InnoDB ReplicaSet deployments. See Chapter 6, MySQL AdminAPI.

• cluster: represents an InnoDB Cluster.

• clusterset: represents an InnoDB ClusterSet.

• rs: represents an InnoDB ReplicaSet.

• shell: provides access to MySQL Shell functions, such as shell.options for configuring MySQL Shell options (see Section 13.4, “Configuring MySQL Shell Options”).

• util: provides access to MySQL Shell utilities. See Chapter 11, MySQL Shell Utilities.

For more information, see Section 4.5, “MySQL Shell Global Objects”.

MySQL Shell Command Line Integration Syntax

Important

MySQL Shell reads MySQL Server option files and login paths by default. As a result, if you connect to a MySQL Server which uses an option file, it will be used, by default, and attempt to create a global session using that configuration. If you do not want to use the options file, you must add --no-defaults to your command line.

You access the command-line integration by starting the mysqlsh application and passing in the special -- option. When you start MySQL Shell in this way, the -- indicates the end of the list of options (such as the server to connect to, which language to use, and so on) and everything after it is passed to the command-line integration. The command-line integration supports a specific syntax, which is based on the objects and methods used in the MySQL Shell interactive interface. To execute an operation using command-line integration syntax, in your terminal issue:

mysqlsh [options] -- [shell_object]+ object_method [arguments]

The syntax elements are:

• shell_object is a string which maps to a MySQL Shell global object. The command-line integration supports nested objects. To call a function in a nested object, provide the list of objects in the hierarchy separated by spaces, to reach the desired object.

• object_method is the name of the method provided by the last shell_object. The method names can be provided following either the JavaScript, or Python naming convention, or an alternative command-line integration friendly format, where all known functions 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, createCluster becomes create-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 any nested objects must be a child object of the previous object provided in the list. The object_method must match one of the last object in the list's methods, and must be defined in one of the valid formats (JavaScript, Python or command line friendly). If they do not correspond to a valid object and its methods, MySQL Shell exits with status 10.

See the examples at MySQL Shell Command Line Integration Examples.

The Objects Available in the Command Line Integration

To find out which objects and methods are available in the command-line integration it is best to query the MySQL Shell you are working with. This is because in addition to the standard objects bundled with MySQL Shell, additional objects from plugins might also be exposed.

To get the list of objects supported by the command-line integration:

$ mysqlsh -- --help

This displays a list of objects and a brief description of what the object provides.

To get a list of the functions available in the command-line integration for an object:

$ mysqlsh -- object --help

For more information, see Section 5.8.2.4, “Command Line Help”.

MySQL Shell 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. Special characters (such as spaces or \) and quoting are processed by your system's shell (bash, cmd, and so on) before they are passed to MySQL Shell. If you are unfamiliar with how your system shell deals with those character sequences as it parses a command, you should try to avoid them. For example, to pass a parameter with quotes as part of the parameter such as “list, of, names”, using just that syntax on the command line is not enough. You need to use your system's shell syntax for escaping those quotes. If you do not, then MySQL Shell might not receive the actual quotation marks. See Section 5.8.2.2, “Defining Arguments”.

There are two types of arguments that can be used in the list of arguments: anonymous arguments and named arguments. Anonymous arguments are used to define simple type parameters such as strings, numbers, boolean, null. Named arguments are used to define the values for list parameters and the options in a dictionary parameter, they are key-value pairs, where the values are simple types. Their usage must adhere to the following pattern:

[positional_argument | named_argument]*

All parts of the syntax are optional and can be given in any order. These arguments are then converted into the arguments passed to the method call in the following order:

• Named arguments that come from lists cause the values to be appended to the list parameter that originated the named argument

• Named arguments that come from dictionaries cause the values to be added to the dictionary parameter that originated the named argument

• If a dictionary parameter exists with no explicit options defined, this causes it to accept any named argument that does not belong to another List or Dictionary parameter

• Any remaining arguments provided to the function call are processed in the order they are provided

MySQL Shell Command Line Integration Examples

Using the command-line integration, calling MySQL Shell API functions 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

  The equivalent command in MySQL Shell interactive mode:

    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

  The equivalent command in MySQL Shell interactive mode:

  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

  The equivalent command in MySQL Shell interactive mode:

  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

  The equivalent command in MySQL Shell interactive mode:

  mysql-js> cluster.status()

• To configure MySQL Shell to turn the command history on:

  $ mysqlsh -- shell options set_persist history.autoSave true

  The equivalent command in MySQL Shell interactive mode:

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