4.2 MySQL Shell Sessions

4.2.1 Creating the Session Global Object While Starting MySQL Shell

4.2.2 Creating the Session Global Object After Starting MySQL Shell

4.2.3 Scripting Sessions in JavaScript and Python Mode

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

• Session: Use this session object type for new application development to communicate with MySQL Server instances where X Protocol is available. X Protocol offers the best integration with MySQL Server. For X Protocol to be available, X Plugin must be installed and enabled on the MySQL Server instance, which it is by default from MySQL 8.0. In MySQL 5.7, X Plugin must be installed manually. See X Plugin for details. X Plugin listens to the port specified by mysqlx_port, which defaults to 33060, so specify this port with connections using a Session.

• ClassicSession: Use this session object type to interact with MySQL Server instances that do not have X Protocol available. This object is intended for running SQL against servers using classic MySQL protocol. The development API available for this kind of session is very limited. For example, there are none of the X DevAPI CRUD operations, no collection handling, and binding is not supported. For development, prefer Session objects whenever possible.

Important

ClassicSession is specific to MySQL Shell and cannot be used with other implementations of X DevAPI, such as MySQL Connectors.

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:[e-mail]: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:                 [e-mail]
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”.