In MySQL Shell, connections to MySQL Server instances are handled by a session object. The following types of session object are available:

When you make the first connection to a MySQL Server instance, which can be done either while starting MySQL Shell or afterwards, a MySQL Shell global object named session is created to represent this connection. This particular session object is global because once created, it can be used in all of the MySQL Shell execution modes: SQL mode, JavaScript mode, and Python mode. The connection it represents is therefore referred to as the global session. The variable session holds a reference to this session object, and can be used in MySQL Shell in JavaScript mode and Python mode to work with the connection.

The session global object can be either the Session type of session object or the ClassicSession type of session object, according to the protocol you select when making the connection to a MySQL Server instance. You can choose the protocol, and therefore the session object type, using a command option, or specify it as part of the connection data that you provide. To see information about the current global session, issue:

mysql-js []> session

<ClassicSession:user@example.com:3330>

When the global session is connected, this shows the session object type and the address of the MySQL Server instance to which the global session is connected.

If you choose a protocol explicitly or indicate it implicitly when making a connection, MySQL Shell tries to create the connection using that protocol, and returns an error if this fails. If your connection parameters do not indicate the protocol, MySQL Shell first tries to make the connection using X Protocol (returning the Session type of session object), and if this fails, tries to make the connection using classic MySQL protocol (returning the ClassicSession type of session object).

To verify the results of your connection attempt, use MySQL Shell's \status command or the shell.status() method. These display the connection protocol and other information about the connection represented by the session global object, or return “Not Connected” if the session global object is not connected to a MySQL server. For example:

mysql-js []> shell.status()
MySQL Shell version 8.0.18

Session type:                 X Protocol
Connection Id:                198
Current schema:               
Current user:                 user@example.com
SSL:                          Cipher in use: TLS_AES_256_GCM_SHA384 TLSv1.3
Using delimiter:              ;
Server version:               8.0.18 MySQL Community Server - GPL
Protocol version:             X Protocol
Client library:               8.0.18
Connection:                   TCP/IP
TCP port:                     33060
Server characterset:          utf8mb4
Schema characterset:          utf8mb4
Client characterset:          utf8mb4
Conn. characterset:           utf8mb4
Compression:                  Enabled (zstd)
Uptime:                       31 min 42.0000 sec

Threads: 8  Questions: 2622  Slow queries: 0  Opens: 298  Flush tables: 3  Open tables: 217  Queries per second avg: 1.378

This section focuses on explaining the session objects that represent connections to MySQL Server instances, and the session global object. For full instructions and examples for each of the ways mentioned in this section to connect to MySQL Server instances, and the other options that are available for the connections, see Section 4.3, “MySQL Shell Connections”.