Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.0Mb
PDF (A4) - 38.1Mb
PDF (RPM) - 36.7Mb
HTML Download (TGZ) - 9.9Mb
HTML Download (Zip) - 9.9Mb
HTML Download (RPM) - 8.7Mb
Man Pages (TGZ) - 209.7Kb
Man Pages (Zip) - 318.9Kb
Info (Gzip) - 3.5Mb
Info (Zip) - 3.5Mb
Excerpts from this Manual

MySQL 5.7 Reference Manual  /  ...  /  MySQL Shell Global Variables

18.2.3 MySQL Shell Global Variables

MySQL Shell reserves certain variables as global variables, which are assigned to commonly used objects in scripting. This section describes the available global variables and provides examples of working with them. The global variables are:

  • session represents the global session if one has been established.

  • db represents a schema if one has been defined, for example by a URI type string.

  • dba represents the AdminAPI, a component of InnoDB cluster which enables you to administer clusters of server instances. See Chapter 20, InnoDB Cluster.

  • shell provides general purpose functions, for example to configure MySQL Shell.


These words are reserved and cannot be used, for example as names of variables.

By using these global objects, MySQL Shell provides interactive error resolution for common situations. For example:

  • Attempting to use an undefined session global variable.

  • Attempting to retrieve an nonexistent schema using session.

  • Attempting to use an undefined db global variable.

Undefined Global Session

The global session variable is set when a global session is established. When a global session is established, issuing a session statement in MySQL Shell displays the session type and its URI as follows:

mysql-js> session

If no global session has been established, MySQL Shell displays the following:

mysql-js> session

If you attempt to use the session variable when no global session is established, interactive error resolution starts and you are prompted to provide the required information to establish a global session. If the session is successfully established, it is assigned to the session variable. The prompts are:

  • An initial prompt explains that no global session is established and asks if one should be established.

  • If you choose to set a global session, the session type is requested.

  • The URI type string to connect to the server instance is requested. See Section, “Connecting using a URI String”.

  • If required, a password is requested.

For example:

mysql-js> session.uri
The global session is not set, do you want to establish a session?

   1) MySQL Document Store Session through X Protocol
   2) Classic MySQL Session

Please select the session type or ENTER to cancel: 2
Please specify the MySQL server URI: root@localhost
Enter password: 
mysql-js> session

Undefined db Variable

The global db variable is set when a global session is established and a default schema is configured. For example, using a URI type string such as root@localhost/sakila to establish a global session connected to the MySQL Server at localhost, on port 33060, as the user root, assigns the schema sakila to the global variable db. Once a schema is defined, issuing db at the MySQL Shell prompt prints the schema name as follows:

mysql-js> db

If there is no global session established, the following is displayed:

mysql-js> db

If you attempt to use the db variable when no global session has been established, the following error is displayed:

mysql-js> db.getCollections()
LogicError: The db variable is not set, establish a global session first.
at (shell):1:2
in db.getCollections()

If a global session has been established but you attempt to use an undefined db, interactive error resolution begins and you are prompted to define an active schema by providing the schema name. If this succeeds the db variable is set to the defined schema. For example:

mysql-js> db.getCollections()
The db variable is not set, do you want to set the active schema? [y/N]:y
Please specify the schema:world_x
mysql-js> db

Retrieving an Nonexistent Schema

If you attempt to use session to retrieve an nonexistent schema, interactive error resolution provides the option to create the schema.

mysql-js> var mySchema = session.getSchema('my_test')
The schema my_test does not exist, do you want to create it? [y/N]: y

mysql-js> mySchema

In all cases, if you do not provide the information required to resolve each situation, a proper result of executing the requested statement on an undefined variable is displayed.

User Comments
Sign Up Login You must be logged in to post a comment.