MySQL Shell 8.0 (part of MySQL 8.0)
MySQL Shell is an advanced command-line client and code editor for MySQL. In addition to SQL, MySQL Shell also offers scripting capabilities for JavaScript and Python. For information about using MySQL Shell, see MySQL Shell 8.0 (part of MySQL 8.0). When MySQL Shell is connected to the MySQL Server through the X Protocol, the X DevAPI can be used to work with both relational and document data, see Using MySQL as a Document Store. MySQL Shell includes the AdminAPI that enables you to work with InnoDB Cluster, see Chapter 6, Using MySQL AdminAPI.
Many of the options described here are related to connections between MySQL Shell and a MySQL Server instance. See Section 4.3, “MySQL Shell Connections” for more information.
mysqlsh supports the following command-line options.
Table A.1 mysqlsh Options
Option Name | Description | Introduced |
---|---|---|
-- | Start of API command line integration | |
--auth-method | Authentication method to use | |
--cluster | Connect to an InnoDB cluster | 8.0.4 |
--column-type-info | Print metadata for columns in result sets | 8.0.14 |
--compress | Compress all information sent between client and server | 8.0.14 |
--connect-timeout | Connection timeout for global session | 8.0.13 |
--credential-store-helper | The Secret Store helper for passwords | 8.0.12 |
--database | The schema to use (alias for --schema) | |
--dba | Enable X Protocol on connection with MySQL 5.7 server | |
--dba-log-sql | Log SQL statements that are executed by AdminAPI operations | 8.0.18 |
--dbpassword | Password to use when connecting to server | |
--dbuser | MySQL user name to use when connecting to server | |
--execute | Execute the command and quit | |
--file | File to process in batch mode | |
--force | Continue in SQL and batch modes even if errors occur | |
--get-server-public-key | Request RSA public key from server | |
--help | Display help message and exit | |
--histignore | Strings that are not added to the history | 8.0.3 |
--host | Host on which MySQL server instance is located | |
--import | Import JSON documents from a file or standard input | 8.0.13 |
--interactive | Emulate Interactive mode in batch mode | |
--js, --javascript | Start in JavaScript mode | |
--json | Print output in JSON format | |
--log-level | Specify logging level | |
-ma | Detect transport protocol for session automatically | 8.0.3 |
--mysql, -mc | Create a session using classic MySQL protocol | 8.0.3 |
--mysqlx, -mx | Create a session using X Protocol | 8.0.3 |
--name-cache | Enable automatic loading of table names based on the active default schema | 8.0.4 |
--no-name-cache | Disable autocompletion | 8.0.4 |
--no-password | No password is provided for this connection | |
--no-wizard, --nw | Disable the interactive wizards | |
--pager | The external pager tool used to display output | 8.0.13 |
--password | Password to use when connecting to server (alias for --dbpassword) | |
--passwords-from-stdin | Read the password from stdin | |
--port | TCP/IP port number for connection | |
--py, --python | Start in Python mode | |
--quiet-start | Start without printing introductory information | |
--recreate-schema | Drop and recreate schema | |
--redirect-primary | Ensure connection to an InnoDB cluster's primary | 8.0.4 |
--redirect-secondary | Ensure connection to an InnoDB cluster's secondary | |
--result-format | Set the output format for this session | 8.0.14 |
--save-passwords | How passwords are stored in the Secret Store | 8.0.12 |
--schema | The schema to use | |
--server-public-key-path | Path name to file containing RSA public key | |
--show-warnings | Show warnings after each statement if there are any (in SQL mode) | |
--socket | Unix socket file or Windows named pipe to use (classic MySQL protocol only) | |
--sql | Start in SQL mode, auto-detecting protocol to use for connection | |
--sqlc | Start in SQL mode using a classic MySQL protocol connection | |
--sqlx | Start in SQL mode using an X Protocol connection | 8.0.3 |
--ssl-ca | File that contains list of trusted SSL Certificate Authorities | |
--ssl-capath | Directory that contains trusted SSL Certificate Authority certificate files | |
--ssl-cert | File that contains X.509 certificate | |
--ssl-cipher | Name of the SSL cipher to use | |
--ssl-crl | File that contains certificate revocation lists | |
--ssl-crlpath | Directory that contains certificate revocation list files | |
--ssl-key | File that contains X.509 key | |
--ssl-mode | Desired security state of connection to server | |
--tabbed | Display output in tab separated format | |
--table | Display output in table format | |
--tls-version | Permissible TLS protocol for encrypted connections | |
--uri | Session information in URI format | |
--user | MySQL user name to use when connecting to server (alias for --dbuser) | |
--verbose | Activate verbose output to the console | 8.0.17 |
--version | Display version information and exit | |
--vertical | Display all SQL results vertically |
--help
, -?
Display a help message and exit.
Marks the end of the list of mysqlsh options and the start of a command and its arguments for MySQL Shell's API command line integration. You can execute methods of the MySQL Shell global objects from the command line using this syntax:
mysqlsh [options
] --object
method
[arguments
]
See Section 5.8, “API Command Line Interface” for more information.
Authentication method to use for the account. Depends on the
authentication plugin used for the account's password. For
MySQL Shell connections using classic MySQL protocol, specify
the name of the authentication plugin, for example
caching_sha2_password
. For MySQL Shell
connections using X Protocol, specify one of the following
options:
Let the library select the authentication method.
Let the library select the authentication method, but do not use any authentication method that is not compatible with MySQL 5.7.
Let the library select the authentication method, using the capabilities announced by the server instance.
Use the challenge-response authentication protocol
supported by MySQL 4.1 and later, which does not send
a plaintext password. This option is compatible with
accounts that use the
mysql_native_password
authentication plugin.
Send a plaintext password for authentication. Use this
option only wih encrypted connections. This option can
be used to authenticate with cached credentials for an
account that uses the
caching_sha2_password
authentication plugin, provided there is an SSL
connection. See
Using X Plugin with the Caching SHA-2 Authentication Plugin.
Authenticate using a hashed password stored in memory.
This option can be used to authenticate with cached
credentials for an account that uses the
caching_sha2_password
authentication plugin, where there is a non-SSL
connection. See
Using X Plugin with the Caching SHA-2 Authentication Plugin.
Ensures that the target server is part of an InnoDB cluster
and if so, sets the cluster
global
variable to the cluster object.
In SQL mode, before printing the returned result set for a query, print metadata for each column in the result set, such as the column type and collation.
The column type is returned as both the type used by
MySQL Shell (Type
), and the type used by
the original database (DBType
). For
MySQL Shell connections using classic MySQL protocol,
DBType
is as returned by the protocol,
and for X Protocol connections, DBType
is inferred from the available information. The column
length (Length
) is returned in bytes.
--compress[={required|preferred|disabled}]
,
-C [{required|preferred|disabled}]
Controls compression of information sent between the client
and the server using this connection. In MySQL Shell 8.0.14
through 8.0.19 this option is available for
classic MySQL protocol connections only, and does not use the
options required
,
preferred
, and
disabled
. In those releases, when you
specify --compress
,
compression is activated if possible. From MySQL Shell
8.0.20 it is also available for X Protocol connections, and
you can optionally specify required
,
preferred
, or
disabled
. When just
--compress
is specified from
MySQL Shell 8.0.20, the meaning is
--compress=required
. See
Section 4.3.4, “Using Compressed Connections” for
information on using MySQL Shell's compression control in
all releases.
Configures how long MySQL Shell waits (in milliseconds) to establish a global session specified through command-line arguments.
--credential-store-helper=
helper
The Secret Store Helper that is to be used to store and retrieve passwords. See Section 4.4, “Pluggable Password Store”.
--database=
,
name
-D
name
The default schema to use. This is an alias for
--schema
.
Enable X Plugin on connection with a MySQL 5.7 server, so that you can use X Protocol connections for subsequent connections. Requires a connection using classic MySQL protocol. Not relevant for MySQL 8.0 servers, which have X Plugin enabled by default.
Log SQL statements that are executed by AdminAPI
operations (excluding sandbox operations). By default, this
category of statement is not written to the MySQL Shell
application log file or sent to the console as verbose
output, even when the
--log-level
and
--verbose
options are set.
The value of the option is an integer in the range from 0 to
2. 0 does not log or display this category of statement,
which is the default behavior if you do not specify the
option. 1 logs SQL statements that are executed by
AdminAPI operations, with the exceptions of
SELECT
statements and
SHOW
statements (this is the
default setting if you specify the option on the command
line without a value). 2 logs SQL statements that are
executed by regular AdminAPI operations in full, including
SELECT
and
SHOW
statements. See
Chapter 9, MySQL Shell Logging and Debug for more
information.
Deprecated in version 8.0.13 of MySQL Shell. Use
--password[=
instead.
password
]
Deprecated in version 8.0.13 of MySQL Shell. Use
--user=
instead.
user_name
--execute=
,
command
-e
command
Execute the command using the currently active language and
quit. This option is mutually exclusive with the
--file=
option.
file_name
--file=
,
file_name
-f
file_name
Specify a file to process in Batch mode. Any options specified after this are used as arguments of the processed file.
Continue processing in SQL and Batch modes even if errors occur.
Specify strings that are not added to the MySQL Shell
history. Strings are separated by a colon. Matching is case
insensitive, and the wildcards * and ? can be used. The
default ignored strings are specified as
“*IDENTIFIED*:*PASSWORD*
”.
See Section 5.5, “Code History”.
--host=
,
host_name
-h
host_name
Connect to the MySQL server on the given host. On Windows,
if you specify --host=.
or -h
.
(giving the host name as a period), MySQL Shell
connects using the default named pipe (which has the name
MySQL
), or an alternative named pipe that
you specify using the
--socket
option.
MySQL Shell equivalent of
--get-server-public-key
.
If
--server-public-key-path=
is given and specifies a valid public key file, it takes
precedence over
file_name
--get-server-public-key
.
Only supported with classic MySQL protocol connections.
Import JSON documents from a file or standard input to a MySQL Server collection or relational table, using the JSON import utility. For instructions, see Section 8.2, “JSON Import Utility”.
Emulate Interactive mode in Batch mode.
--js
,
--javascript
Start in JavaScript mode.
Controls JSON wrapping for MySQL Shell output from this
session. This option is intended for interfacing
MySQL Shell with other programs, for example as part of
testing. For changing query results output to use the JSON
format, see --result-format
.
When the --json
option has
no value or a value of pretty
, the output
is generated as pretty-printed JSON. With a value of
raw
, the output is generated in raw JSON
format. In any of these cases, the
--result-format
option and
its aliases and the value of the
resultFormat
MySQL Shell configuration
option are ignored. With a value of off
,
JSON wrapping does not take place, and result sets are
output as normal in the format specified by the
--result-format
option or
the resultFormat
configuration option.
Change the logging level for the MySQL Shell application
log file, or disable logging to the file. The option
requires a value, which can be either an integer in the
range from 1 to 8, or one of none
,
internal
, error
,
warning
, info
,
debug
, debug2
, or
debug3
. Specifying 1 or
none
disables logging to the application
log file. Level 5 (info
) is the default
if you do not specify this option. See
Chapter 9, MySQL Shell Logging and Debug.
Deprecated in version 8.0.13 of MySQL Shell. Automatically attempts to use X Protocol to create the session's connection, and falls back to classic MySQL protocol if X Protocol is unavailable.
--mysql
,
--mc
Sets the global session created at start up to to use a
classic MySQL protocol connection. The --mc
option with two hyphens replaces the previous single hyphen
-mc
option from MySQL Shell 8.0.13.
--mysqlx
,
--mx
Sets the global session created at start up to use an
X Protocol connection. The --mx
option
with two hyphens replaces the previous single hyphen
-mx
option from MySQL Shell 8.0.13.
Enable automatic loading of table names based on the active default schema.
--no-name-cache
,
-A
Disable loading of table names for autocompletion based on
the active default schema and the DevAPI
db
object. Use \rehash
to reload the name information manually.
When connecting to the server, if the user has a
password-less account, which is insecure and not
recommended, or if socket peer-credential authentication is
in use (for Unix socket connections), you must use
--no-password
to explicitly
specify that no password is provided and the password prompt
is not required.
--no-wizard
,
-nw
Disables the interactive wizards provided by operations such
as creating connections,
dba.configureInstance()
,
and so on. Use this option when you want to script
MySQL Shell and not have the interactive prompts displayed.
For more information see
Section 5.6, “Batch Code Execution” and
Section 5.8, “API Command Line Interface”.
Cluster
.rebootClusterFromCompleteOutage()
The external pager tool used by MySQL Shell to display text
output for statements executed in SQL mode and other
selected commands such as online help. If you do not set a
pager, the pager specified by the PAGER
environment variable is used. See
Section 4.6, “Using a Pager”.
Read the password from standard input, rather than from the terminal. This option does not affect any other password behaviors, such as the password prompt.
--password[=
,
password
]-p
password
The password to use when connecting to the server. The maximum password length that is accepted for connecting to MySQL Shell is 128 characters.
--password=
(password
-p
)
with a value supplies a password to be used for the
connection. With the long form
password
--password=
, you must use an equals
sign and not a space between the option and its value.
With the short form -p
, there must be
no space between the option and its value. If a space is
used in either case, the value is not interpreted as a
password and might be interpreted as another connection
parameter.
Specifying a password on the command line should be considered insecure. See End-User Guidelines for Password Security. You can use an option file to avoid giving the password on the command line.
--password
with no value
and no equal sign, or -p
without a
value, requests the password prompt.
--password=
with an
empty value has the same effect as
--no-password
, which
specifies that the user is connecting without a
password. When connecting to the server, if the user has
a password-less account, which is insecure and not
recommended, or if socket peer-credential authentication
is in use (for Unix socket connections), you must use
one of these methods to explicitly specify that no
password is provided and the password prompt is not
required.
--port=
,
port_num
-P
port_num
The TCP/IP port number to use for the connection. The default is port 33060.
--py
,
--python
Start in Python mode.
Execute the specified Python module as a script in
MySQL Shell's Python mode.
--pym
works in the same way
as Python's -m
command line option. This
option is available from MySQL Shell 8.0.22.
Start without printing introductory information.
MySQL Shell normally prints information about the product,
information about the session (such as the default schema
and connection ID), warning messages, and any errors that
are returned during startup and connection. When you specify
--quiet-start
with no value or a value of
1, information about the MySQL Shell product is not
printed, but session information, warnings, and errors are
printed. With a value of 2, only errors are printed.
Drop and recreate the schema that was specified in the
connection options, either as part of a URI-like connection
string or using the
--schema
,
--database
, or
-D
option. The schema is deleted if it
exists.
Ensures that the target server is part of an InnoDB Cluster or InnoDB ReplicaSet and if it is not the primary, finds the primary and connects to it. MySQL Shell exits with an error if any of the following is true when using this option:
No instance is specified
On an InnoDB Cluster, Group Replication is not active
InnoDB cluster metadata does not exist
There is no quorum
Ensures that the target server belongs to an
InnoDB ReplicaSet, and if so, populates the
rs
global variable with the
InnoDB ReplicaSet. You can then administer the
InnoDB ReplicaSet using the rs
global
variable, for example by issuing
rs.status()
.
Ensures that the target server is part of a single-primary InnoDB cluster or InnoDB ReplicaSet and if it is not a secondary, finds a secondary and connects to it. MySQL Shell exits with an error if any of the following is true when using this option:
On an InnoDB Cluster, Group Replication is not active
InnoDB cluster metadata does not exist
There is no quorum
The cluster is not single-primary and is running in multi-primary mode
There is no secondary available, for example because there is just one server instance
--result-format={table|tabbed|vertical|json|json/pretty|ndjson|json/raw|json/array}
Set the value of the resultFormat
MySQL Shell configuration option for this session. Formats
are as follows:
The default for interactive mode, unless another value
has been set persistently for the
resultFormat
configuration option
in the configuration file, in which case that default
applies. The --table
alias can also be used.
The default for batch mode, unless another value has
been set persistently for the
resultFormat
configuration option
in the configuration file, in which case that default
applies. The --tabbed
alias can also be used.
Produces output equivalent to the
\G
terminator for an SQL query. The
--vertical
or
-E
aliases can also be used.
Produces pretty-printed JSON.
Produces raw JSON delimited by newlines.
Produces raw JSON wrapped in a JSON array.
If the --json
command line
option is used to activate JSON wrapping for output for the
session, the --result-format
option and its aliases and the value of the
resultFormat
configuration option are
ignored.
--save-passwords={always|prompt|never}
Controls whether passwords are automatically stored in the
secret store. always
means passwords are
always stored unless they are already in the store or the
server URL is excluded by a filter. never
means passwords are never stored. prompt
,
which is the default, means users are asked whether to store
the password or not. See
Section 4.4, “Pluggable Password Store”.
--schema=
,
name
-D
name
The default schema to use.
--server-public-key-path=
file_name
MySQL Shell equivalent of
--server-public-key-path
.
If
--server-public-key-path=
is given and specifies a valid public key file, it takes
precedence over
file_name
--get-server-public-key
.
Only supported with classic MySQL protocol connections.
See caching_sha2_password
plugin
Caching SHA-2 Pluggable Authentication.
When true is specified, which is the default, in SQL mode, MySQL Shell displays warnings after each SQL statement if there are any. If false is specified, warning are not displayed.
--socket[=
,
path
]-S
[path]
On Unix, when a path is specified, the path is the name of
the Unix socket file to use for the connection. If you
specify --socket
with no value and no
equal sign, or -S
without a value, the
default Unix socket file for the appropriate protocol is
used.
On Windows, the path is the name of the named pipe to use
for the connection. The pipe name is not case-sensitive. On
Windows, you must specify a path, and the
--socket
option is available for
classic MySQL protocol sessions only.
You cannot specify a socket if you specify a port or a host
name other than localhost
on Unix or a
period (.) on Windows.
Start in SQL mode, auto-detecting the protocol to use if it
is not specified as part of the connection information. When
the protocol to use is not specified, defaults to an
X Protocol connection, falling back to a classic MySQL protocol
connection. To force a connection to use a specific protocol
see the --sqlx
or
--sqlc
options.
Alternatively, specify a protocol to use as part of a
URI-like connection string or use the
--port
option. See
Section 4.3, “MySQL Shell Connections” and
MySQL Shell
Ports Reference for more information.
Start in SQL mode forcing the connection to use classic MySQL protocol, for example to use MySQL Shell with a server that does not support X Protocol. If you do not specify the port as part of the connection, when you provide this option MySQL Shell uses the default classic MySQL protocol port which is usually 3306. The port you are connecting to must support classic MySQL protocol, so for example if the connection you specify uses the X Protocol default port 33060, the connection fails with an error. See Section 4.3, “MySQL Shell Connections” and MySQL Shell Ports Reference for more information.
Start in SQL mode forcing the connection to use X Protocol. If you do not specify the port as part of the connection, when you provide this option MySQL Shell uses the default X Protocol port which is usually 33060. The port you are connecting to must support X Protocol, so for example if the connection you specify uses the classic MySQL protocol default port 3306, the connection fails with an error. See Section 4.3, “MySQL Shell Connections” and MySQL Shell Ports Reference for more information.
Options that begin with
--ssl
specify whether to
connect to the server using SSL and indicate where to find
SSL keys and certificates. The mysqlsh
SSL options function in the same way as the SSL options for
MySQL Server, see
Command Options for Encrypted Connections for more
information.
mysqlsh accepts these SSL options:
--ssl-mode
,
--ssl-ca
,
--ssl-capath
,
--ssl-cert
,
--ssl-cipher
,
--ssl-crl
,
--ssl-crlpath
,
--ssl-key
,
--tls-version
.
Display results in tab separated format in interactive mode.
The default for that mode is table format. This option is an
alias of the
--result-format=tabbed
option.
Display results in table format in batch mode. The default
for that mode is tab separated format. This option is an
alias of the
--result-format=table
option.
Create a connection upon startup, specifying the connection options in a URI-like string as described at Connecting to the Server Using URI-Like Strings or Key-Value Pairs.
--user=
,
user_name
-u
user_name
The MySQL user name to use when connecting to the server.
Activate verbose output to the console and specify the level of detail. The value is an integer in the range from 0 to 4. 0 displays no messages, which is the default verbosity setting when you do not specify the option. 1 displays error, warning and informational messages (this is the default setting if you specify the option on the command line without a value). 2, 3, and 4 add higher levels of debug messages. See Chapter 9, MySQL Shell Logging and Debug for more information.
--version
,
-V
Display the version of MySQL Shell and exit.
--vertical
,
-E
Display results vertically, as when the
\G
terminator is used for an SQL query.
This option is an alias of the
--result-format=vertical
option.