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:
When you start MySQL Shell using the command parameters. See Section 4.2.1, “Connecting using Individual Parameters”.
When MySQL Shell is running using the
\connectcommand. See Section 3.1, “MySQL Shell Commands”.
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
email@example.com:3306/main-schema. For the full syntax, see Connecting Using URI-Like Connection Strings.
Parameters specified with key-value pairs use a syntax such as
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.3, “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
userin the string but do not specify a password after it.
If you are connecting using key-value pairs, provide an empty string using
If you do not specify parameters for a connection the following defaults are used:
userdefaults to the current system user name
portdefaults 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
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 firstname.lastname@example.org?connect-timeout=2000 // Increase the timeout to 20 seconds mysql-js> \connect email@example.com?connect-timeout=20000
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
To enable compression for the connection, use the
compression connection parameter, for example:
mysql-js> \connect firstname.lastname@example.org?compression=true
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
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
\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
-Soption is specified, with or without a path to a socket file.
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. 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-like connection string, specify
If you are connecting using a key-value pairs, specify
If you are connecting using individual parameters, specify
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-like
In URI-like strings, the path to a Unix socket file or Windows
named pipe must be encoded, using either percent encoding or by
surrounding the path with parentheses. Parentheses eliminate the
need to percent encode characters such as the
directory separator character. If the path to a Unix socket file
is included in a URI-like 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%2Fmysql.sock mysql-js> \connect user@localhost?socket=(/tmp/mysql.sock) mysql-js> \connect user@/tmp%2Fmysql.sock mysql-js> \connect user@(/tmp/mysql.sock)
On Windows only, the named pipe must be prepended with the
\\.\ as well as being either encoded
using percent encoding or surrounded with parentheses, as shown in
the following examples:
On Windows, if one or more MySQL Shell sessions are connected to a MySQL Server instance using a named pipe and you need to shut down the server, you must first close the MySQL Shell sessions. Sessions that are still connected in this way can cause the server to hang during the shutdown procedure. If this does happen, exit MySQL Shell and the server will continue with the shutdown procedure.
For more information on connecting with Unix socket files and Windows named pipes, see Connecting to the MySQL Server Using Command Options and Connecting to the Server Using URI-Like Strings or Key-Value Pairs.