Documentation Home
MySQL Shell 8.0
Related Documentation Download this Manual
PDF (US Ltr) - 369.1Kb
PDF (A4) - 366.9Kb
HTML Download (TGZ) - 73.6Kb
HTML Download (Zip) - 85.5Kb


MySQL Shell 8.0  /  MySQL Shell Command Reference  /  mysqlsh — The MySQL Shell

A.1 mysqlsh — The MySQL Shell

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 InnoDB Cluster.

Many of the options described here are related to connections between MySQL Shell and a MySQL Server instance. See Section 4.1, “MySQL Shell Connections” for more information.

mysqlsh supports the following command-line options.

Table A.1 mysqlsh Options

Format Description Introduced
--auth-method Authentication method to use
--cluster Connect to an InnoDB cluster 8.0.4
--connect-timeout Connection timeout for global session 8.0.13
--database The schema to use (alias for --schema)
--dba Enable X Protocol on connection with MySQL 5.7 server
--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
--host Connect to MySQL server on given host
--interactive Emulate Interactive mode in Batch mode
--javascript, --js Start in JavaScript mode
--json Print output in JSON format
--log-level Specify logging level
-ma Detect session protocol automatically 8.0.3
--mysql, -mc Create a session using 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 connection wizard
--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
--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
--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 For connections to localhost, the Unix socket file to use, or pipe name on Windows (ClassicSessions only)
--sql Start in SQL mode, auto-detecting protocol to use for connection
--sqlc Start in SQL mode using a ClassicSession
--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 Security state of connection to server
--tabbed Display output in tab separated format
--table Display output in table format
--tls-version Protocols permitted for encrypted connections
--uri Session information in URI format
--user MySQL user name to use when connecting to server (alias for --dbuser)
--version Display version information and exit
--vertical Display all SQL results vertically

  • --help

    Display a help message and exit.

  • --auth-method=method

    Authentication method to use for the account. Depends on the authentication plugin used for the account's password. MySQL Shell currently supports the following methods:

  • --cluster

    Ensures that the target server is part of an InnoDB cluster and if so, sets the cluster global variable to the cluster object.

  • --column-type-info

    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, -C

    Enable compression for information sent between the client and the server if both support compression. This option is available for classic MySQL Protocol connections only.

  • --connect-timeout

    Configures how long MySQL Shell waits to establish a global session specified through command-line arguments.

  • --database=name

    The default schema to use. This is an alias for --schema.

  • --dba=enableXProtocol

    Enable X Plugin on connection with 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.

  • --dbpassword[=password]

    Deprecated in version 8.0.13 of MySQL Shell. Use --password[=password] instead.

  • --dbuser=user_name

    Deprecated in version 8.0.13 of MySQL Shell. Use --user=user_name instead.

  • --execute=command, -e command

    Execute the command using the currently active language and quit. This option is mutually exclusive with the --file=file_name option.

  • --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.

  • --force

    Continue processing in SQL and Batch modes even if errors occur.

  • --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.

  • --get-server-public-key

    MySQL Shell equivalent of --get-server-public-key.

    Important

    Only supported with classic MySQL protocol connections.

    See Caching SHA-2 Pluggable Authentication.

  • --import

    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 7.2, “JSON Import Utility”.

  • --interactive[=full]

    Emulate Interactive mode in Batch mode.

  • --js

    Start in JavaScript mode.

  • --json[={off|pretty|raw}]

    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.

  • --log-level=N

    Specify the logging level. The value can be either an integer in the range from 1 to 8, or one of none, internal, error, warning, info, debug, debug2, or debug3. See Chapter 8, MySQL Shell Application Log.

  • -ma

    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 MySQL protocol if X Protocol is unavailable.

  • --mysql (--mc)

    Sets the session created at start up to to use a classic MySQL protocol; connection. The --mc option with two hyphens replaced the previous -mc option in version 8.0.13.

  • --mysqlx (--mx)

    Sets the session created at start up to use an X Protocol connection. The --mx option with two hyphens replaced the previous single hyphen -mx option in version 8.0.13.

  • --name-cache

    Enable automatic loading of table names based on the active default schema.

  • --no-name-cache

    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.

  • --no-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 --no-password to explicitly specify that no password is provided and the password prompt is not required.

  • --no-wizard

    Disables the connection wizard which provides help when creating connections.

  • --passwords-from-stdin

    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], -ppassword

    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 (-ppassword) with a value supplies a password to be used for the connection. With the long form --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

    Start in Python mode.

  • --quiet-start[=1|2]

    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.

  • --recreate-schema

    Drop and recreate schema.

  • --redirect-primary

    Ensures that the target server is part of an InnoDB cluster and if it is not a primary, finds the cluster's primary and connects to it. MySQL Shell exits with an error if any of the following is true when using this option:

    • Group Replication is not active

    • InnoDB cluster metadata does not exist

    • There is no quorum

  • --redirect-secondary

    Ensures that the target server is part of an InnoDB cluster 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:

    • 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 in the cluster, for example because there is just one server instance

  • --result-format={table|tabbed|vertical|json|json/raw}

    Set the value of the resultFormat MySQL Shell configuration option for this session. Formats are as follows:

    table

    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.

    tabbed

    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.

    vertical

    Produces output equivalent to the \G terminator for an SQL query. The --vertical or -E aliases can also be used.

    json

    Produces pretty-printed JSON.

    json/raw

    Produces raw JSON.

    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.

  • --schema=name, -D name

    The default schema to use.

  • --server-public-key-path=file_name

    MySQL Shell equivalent of --server-public-key-path.

    Important

    Only supported with classic MySQL protocol connections.

    See caching_sha2_password plugin Caching SHA-2 Pluggable Authentication.

  • --show-warnings

    Cause warnings to be shown after each statement if there are any.

  • --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 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.

  • --sql

    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 type string or use the --port option. See Section 4.1, “MySQL Shell Connections” and MySQL Shell Ports Reference for more information.

  • --sqlc

    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.1, “MySQL Shell Connections” and MySQL Shell Ports Reference for more information.

  • --sqlx

    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.1, “MySQL Shell Connections” and MySQL Shell Ports Reference for more information.

  • --ssl*

    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.

  • --tabbed

    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.

  • --table

    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.

  • --uri=str

    Create a connection upon startup, specifying the connection options in a URI string format, see Connecting Using a URI or Key-Value Pairs.

  • --user=user_name, -u user_name

    The MySQL user name to use when connecting to the server.

  • --version, -V

    Display version information 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.


PREV   HOME   UP