Related Documentation Download this Manual
PDF (US Ltr) - 323.8Kb
PDF (A4) - 321.2Kb
HTML Download (TGZ) - 64.1Kb
HTML Download (Zip) - 74.6Kb

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

3.1 MySQL Shell Connections

MySQL Shell can connect to MySQL Server using both the X Protocol and the classic MySQL protocol. You can configure the MySQL server instance that MySQL Shell is connected to in the following ways:

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

  • A URI type string, such as See Connecting using a URI String for the full syntax.

  • As key-value pairs, such as {user:'myuser', host:'', port:3306, schema:'main-schema'}. These key-value pairs are supplied in language natural constructs for the implementation. This means you can supply connection parameters using key-value pairs as a JSON object in JavaScript, or using key-value pairs in a dictionary in Python. See Connecting using Key-value Pairs for the full syntax.

See Connecting Using a URI 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 is requested at the login prompt, and can be stored using Section 3.2, “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 type string, place a : after the user in the URI type 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

If the connection to the server is lost, MySQL Shell does not attempt to reconnect automatically. Use the \reconnect command to make MySQL Shell try several reconnection attempts for the current global session with the previously supplied 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 both support compression. 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.

On Unix, MySQL Shell connections default to using Unix sockets when the following conditions are met:

  • A TCP port is not specified.

  • A host name is not specified or it is equal to localhost.

  • The --socket or -S option is specified, with or without a path to a socket file.

If you specify --socket with no value and no equals sign, or -S without a value, the default Unix socket file for the protocol is used. If you specify a path to an alternative Unix socket file, that socket file is used.

If a host name is specified but it is not localhost, a TCP connection is established. In this case, if a TCP port is not specified the default value of 3306 is used.

On Windows, for MySQL Shell connections using classic MySQL protocol, if you specify the host name as a period (.), MySQL Shell connects using a named pipe.

  • If you are connecting using a URI type string, specify user@.

  • If you are connecting using a key-value pairs, specify {"host": "."}

  • If you are connecting using individual parameters, specify --host=. or -h .

By default, the pipe name MySQL is used. You can specify an alternative named pipe using the --socket option or as part of the URI type string.

In URI type strings, the path to a Unix socket file or Windows named pipe must either be encoded using percent encoding, or surrounded with parentheses, which removes the need to percent encode characters such as the common directory separator (/). If the path to a Unix socket file is included in the URI type string as part of the query string, the leading slash must be percent encoded, but if it replaces the host name, the leading slash must not be percent encoded, as shown in the following examples:

mysql-js> \connect user@localhost?socket=%2Ftmp%2Fmysqld.sock
mysql-js> \connect user@localhost?socket=(/tmp/mysqld.sock)
mysql-js> \connect user@/tmp%2Fmysqld.sock 
mysql-js> \connect user@(/tmp/mysqld.sock)

On Windows only, the named pipe must be prepended with the characters \\.\ as well as being either encoded using percent encoding or surrounded with parentheses, as shown in the following examples:


For more information on connecting with Unix socket files and Windows named pipes, see Connecting to the MySQL Server and Connecting Using a URI or Key-Value Pairs.