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”.
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 asshell.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”.
As of MySQL Shell 8.0.32, 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 lastshell_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 aobject_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
becomescreate-cluster
.arguments
are the arguments passed to theobject_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.
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”.
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
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);