Documentation Home
MySQL Shell 8.0
Related Documentation Download this Manual
PDF (US Ltr) - 0.5Mb
PDF (A4) - 0.5Mb
HTML Download (TGZ) - 109.6Kb
HTML Download (Zip) - 121.1Kb

MySQL Shell 8.0  /  Getting Started with MySQL Shell  /  MySQL Shell Connections

4.3 MySQL Shell Connections

MySQL Shell can connect to MySQL Server using both X Protocol and classic MySQL protocol. You can specify the MySQL server instance to which MySQL Shell connects in the following ways:

These different ways of connecting to a MySQL server instance all support specifying the connection as follows:

  • Parameters specified with a URI-like string use a syntax such as For the full syntax, see Connecting Using URI-Like Connection Strings.

  • Parameters specified with key-value pairs use a syntax such as {user:'myuser', host:'', port:3306, schema:'main-schema'}. These key-value pairs are supplied in language-natural constructs for the implementation. For example, you can supply connection parameters using key-value pairs as a JSON object in JavaScript, or as a dictionary in Python. For the full syntax, see Connecting Using Key-Value Pairs.

See Connecting to the Server Using URI-Like Strings or Key-Value Pairs for more information.


Regardless of how you choose to connect it is important to understand how passwords are handled by MySQL Shell. By default connections are assumed to require a password. The password (which has a maximum length of 128 characters) is requested at the login prompt, and can be stored using Section 4.4, “Pluggable Password Store”. If the user specified has a password-less account, which is insecure and not recommended, or if socket peer-credential authentication is in use (for example when using Unix socket connections), you must explicitly specify that no password is provided and the password prompt is not required. To do this, use one of the following methods:

  • If you are connecting using a URI-like connection string, place a : after the user in the string but do not specify a password after it.

  • If you are connecting using key-value pairs, provide an empty string using '' after the password key.

  • If you are connecting using individual parameters, either specify the --no-password option, or specify the --password= option with an empty value.

If you do not specify parameters for a connection the following defaults are used:

  • user defaults to the current system user name.

  • host defaults to localhost.

  • port defaults to the X Plugin port 33060 when using an X Protocol connection, and port 3306 when using a classic MySQL protocol connection.

Instead of a TCP connection, you can connect using a Unix socket file or a Windows named pipe. For instructions, see Section 4.3.2, “Connecting using Unix Sockets and Windows Named Pipes”.

If the MySQL server instance supports encrypted connections, you can enable and configure the connection to use encryption. For instructions, see Section 4.3.3, “Using Encrypted Connections”.

If the connection to the server is lost, you can use the \reconnect command, which makes MySQL Shell try several reconnection attempts for the current global session using the existing connection parameters. The \reconnect command is specified without any parameters or options. If those attempts are unsuccessful, you can make a fresh connection using the \connect command and specifying the connection parameters.

To configure the connection timeout use the connect-timeout connection parameter. The value of connect-timeout must be a non-negative integer that defines a time frame in milliseconds. The timeout default value is 10000 milliseconds, or 10 seconds. For example:

// Decrease the timeout to 2 seconds.
mysql-js> \connect
// Increase the timeout to 20 seconds
mysql-js> \connect

To disable the timeout set the value of connect-timeout to 0, meaning that the client waits until the underlying socket times out, which is platform dependent.

To enable compression for the connection, use the compression connection parameter, for example:

mysql-js> \connect

When set to true (or 1), this option enables compression of all information sent between the client and the server if possible. The default is no compression (false or 0). If you are connecting using command parameters, the equivalent parameter is --compress (-C). Compression is available for MySQL Shell connections using classic MySQL protocol only. You can set the defaultCompress MySQL Shell configuration option to enable compression for every global session. The MySQL Shell \status command shows whether or not compression is enabled for the session.