MySQL Shell 8.0  /  ...  /  MySQL Shell Sessions Explained

2.2.1 MySQL Shell Sessions Explained

MySQL Shell is a unified interface to operate MySQL Server through scripting languages such as JavaScript or Python. To maintain compatibility with previous versions, SQL can also be executed in certain modes. A connection to a MySQL server is required. In MySQL Shell these connections are handled by a Session object.

The following types of Session object are available:

  • Session: Use this session type for new application development to communicate with MySQL server instances which have the X Protocol enabled. It offers the best integration with MySQL Server, and therefore, it is used by default.

  • ClassicSession Use this session type to interact with MySQL Servers that do not have the X Protocol enabled. The development API available for this type of session is very limited. For example, there are no CRUD operations, no collection handling, and binding is not supported.


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

Choosing a MySQL Shell Session Type

MySQL Shell creates a Session object by default. You can either configure the session type using MySQL Shell command options, the scheme element of a URI type string, or provide an option to the \connect command. To choose which type of session should be created when starting MySQL Shell, use one of these options:

  • --mysqlx creates a Session, connected using X Protocol.

  • --mysql creates a ClassicSession, connected using MySQL protocol.

To choose which type of session to use when defining a URI type string use one of these options:

  • Specify mysqlx to create an X Protocol session. The X Plugin must be installed on the server instance, see Using MySQL as a Document Store for more information.

  • Specify mysql to create a classic MySQL protocol session.

For more information, see Section 2.1.2, “Connecting using a URI String”.

Creating a Session Using Shell Commands

If you open MySQL Shell without specifying connection parameters, MySQL Shell opens without an established global session. It is possible to establish a global session once MySQL Shell has been started using the MySQL Shell \connect URI command, where URI is a URI type string as defined at Section 2.1.2, “Connecting using a URI String”. For example:

  • \connect -ma URI: Creates a Session, automatically detecting the protocol. Attempts to use X Protocol by default, and falls back to MySQL protocol.

  • \connect -mx | --mysqlx URI: Creates a Session using X Protocol.

  • \connect -mc | --mysql URI: Creates a ClassicSession using MySQL protocol.

For example:

mysql-js> \connect mysqlx://user@localhost

Alternatively, use the shell.connect('URI' method. For example this is equivalent to the above \connect> command:

mysql-js> shell.connect('mysqlx://user@localhost')