Documentation Home
MySQL Shell 8.0
Related Documentation Download this Manual
PDF (US Ltr) - 491.7Kb
PDF (A4) - 492.2Kb
HTML Download (TGZ) - 98.9Kb
HTML Download (Zip) - 110.6Kb

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

4.4.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-like connection 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 (--mx) creates a Session, connected using X Protocol.

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

To choose which type of session to use when defining a URI-like connection 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 Connecting to the Server Using URI-Like Strings or Key-Value Pairs.

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-like connection string as described at Connecting Using URI-Like Connection Strings. For example:

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

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

For example:

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

If you do not specify a protocol with the \connect command, MySQL Shell automatically attempts to use X Protocol for the session's connection, and falls back to MySQL protocol if X Protocol is unavailable. The protocol option -ma, which specified that behavior explicitly, is now deprecated. The use of a single dash with the short form options (that is, -mx and -mc) is also deprecated from version 8.0.13 of MySQL Shell.

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

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