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 globally in the following ways:
When you start MySQL Shell, using the command parameters. See Section 4.3.1, “Connecting using Individual Parameters”.
When MySQL Shell is running, using the
\connectcommand. See Section 3.1, “MySQL Shell Commands”.
These methods of connecting to a MySQL server instance create the
global session, which is a connection that can be used in all of
Python mode. A MySQL Shell global object named
session represents this connection, and the
session holds a reference to it. You
can also create multiple additional session objects that represent
other connections to MySQL server instances, by using the
mysql.getClassicSession() function. These
connections can be used in the modes where you created them, and
one of them at a time can be assigned as MySQL Shell's global
session so it can be used in all modes. For an explanation of
session objects, how to operate on the global session, and how to
create and manage multiple connections from a MySQL Shell
instance, see Section 4.2, “MySQL Shell Sessions”.
All these different ways of connecting to a MySQL server instance support specifying the connection as follows:
Parameters specified with a URI-like string use a syntax such as
firstname.lastname@example.org: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.4, “Pluggable Password Store”. If the user specified has a passwordless 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.
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 email@example.com?connect-timeout=2000 // Increase the timeout to 20 seconds mysql-js> \connect firstname.lastname@example.org?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
Certain operations that open many connections to servers can take
a long time to execute when one or more servers are unreachable,
for example, the
shell.connect() command. The
connection timeout may not provide enough time for a response.
From MySQL Shell 8.0.28, you can use the MySQL Shell
connectTimeout to set the
default connection timeout for any session not using AdminAPI.
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”.
From MySQL Shell 8.0.27, the use of LDAP and Kerberos authentication is supported for classic MySQL protocol connections. For instructions to use these, see Section 4.3.4, “Using LDAP and Kerberos Authentication”.
From MySQL Shell 8.0.28, MySQL Shell supports SSH tunneling to connect to MySQL server instances. For instructions, see Section 4.3.5, “Using an SSH Tunnel”.
You can also request that the connection uses compression for all data sent between the MySQL Shell and the MySQL server instance. For instructions, see Section 4.3.6, “Using Compressed 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
command and specifying the connection parameters.