Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.4Mb
PDF (A4) - 37.4Mb
PDF (RPM) - 37.0Mb
EPUB - 10.6Mb
HTML Download (TGZ) - 10.3Mb
HTML Download (Zip) - 10.4Mb
HTML Download (RPM) - 9.0Mb
Eclipse Doc Plugin (TGZ) - 11.2Mb
Eclipse Doc Plugin (Zip) - 13.4Mb
Man Pages (TGZ) - 204.7Kb
Man Pages (Zip) - 311.8Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

3.8.2.2 MySQL Shell Connections

MySQL Shell can be configured to connect to a MySQL Server running X Plugin using command-line options at start up or from MySQL Shell itself. The address of the MySQL Server can be specified using individual parameters, such as user, hostname and port, or using a Uniform Resource Identifier (URI) in the format user@host:port/schema, such as mike@myserver:33060/testDB. The following sections describe these methods.

Regardless of the method you choose to connect it is important to understand how passwords are handled by MySQL Shell:

Important

By default connections are assumed to require a password. The password is requested at the login prompt. To specify a password-less account use the --password option, or use a : after the user in a URI.

If you do not specify parameters for a connection the following defaults are used:

  • user defaults to the current system user name

  • host defaults to localhost

  • port defaults to the X Plugin port 33060 when using an X Session, and port 3306 when using a Classic session

MySQL Shell connections using X Protocol always use TCP, using Linux sockets is not supported. MySQL Shell connections using MySQL Protocol can use Linux sockets by specifying the --socket command-line option.

3.8.2.2.1 Connecting using a URI String

You configure the MySQL Server which MySQL Shell connects to by passing the connection data in string format using the --uri command-line option.

Use the following format:

[dbuser[:[dbpassword]]@]host[:port][/schema]

Descriptions of these options:

  • dbuser: specifies the MySQL user account to be used for the authentication process.

  • dbpassword: specifies the dbuser password to be used for the authentication process.

    Warning

    Storing the password in the URI is not recommended.

  • host: specifies the host to which the session object connects. If not specified, localhost is used by default.

  • port: specifies which port the target MySQL server is listening on for the connection. If not specified, 33060 is used by default for the X Protocol enabled sessions, and 3306 is the default for traditional MySQL protocol sessions.

  • schema: Indicates the database to be set as default when the session is established.

If no password is specified using the URI, which is recommended, then the password is prompted for. The following examples show how to use these command-line options:

  • Connect with a Node Session at port 33065.

    shell> mysqlsh --uri user@localhost:33065 --node
    
  • Connect with a Classic Session.

    shell> mysqlsh --uri user@localhost --classic
    

Although using a password-less account is not recommended, you can specify a user without a password using a : after the user name, for example:

shell> mysqlsh --uri user:@localhost

In addition to specifying a URI manually, you can use a stored session. See Section 3.8.5, “Stored Sessions” for more information.

3.8.2.2.2 Connecting using Individual Parameters

In addition to specifying connection parameters using a URI, it is also possible to define the connection data using separate parameters for each value.

Use the following parameters:

The first 5 parameters match the tokens used in the URI format described at Section 3.8.2.2.1, “Connecting using a URI String”.

The --password parameter indicates the user should connect without a password.

For consistency, the following aliases are supported for some parameters:

Attempt to establish an XSession with a specified user at port 33065.

shell> mysqlsh -u user -h localhost -P 33065

Attempt to establish a Classic Session with a specified user.

shell> mysqlsh -u user -h localhost --classic

Attempt to establish a Node Session with a specified user.

shell> mysqlsh --node -u user -h localhost
3.8.2.2.3 Using SSL for Secure Connections

Using SSL is possible when connecting to an SSL enabled MySQL server.

To configure an SSL connection, use the following command-line options:

  • --ssl : This enables or disables connections through SSL. If set to 0, the other SSL command-line options are ignored.

  • --ssl-ca=filename: The path to a file in PEM format that contains a list of trusted SSL certificate authorities.

  • --ssl-cert=filename: The name of the SSL certificate file in PEM format to use for establishing a secure connection.

  • --ssl-key=filename: The name of the SSL key file in PEM format to use for establishing a secure connection.

The --ssl option is assumed to be 1 (enabled) if the other SSL options are set.

3.8.2.2.4 Connecting using both URI and Individual Parameters

When the --uri option is specified in combination with some of the individual parameters, the address specified by the --uri option is used as the base connection data and the values provided using individual parameters override the corresponding value from the URI. If the --user option is used, it would replace any user specified as part of a URI.

For example to establish an XSession and override user from the URI:

shell> mysqlsh --uri user@localhost:33065 --user otheruser
3.8.2.2.5 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 following Shell Commands:

  • \connect URI: Creates an XSession.

  • \connect -n URI: Creates a Node Session.

  • \connect -c URI: Creates a Classic Session.

Configure the connection using the URI parameter, which follows the same syntax as for the --uri command-line option. For additional information, see Section 3.8.2.2.1, “Connecting using a URI String”.

For example:

mysql-js> \connect root@localhost
Creating XSession to root@localhost...
Enter password: ****
No default schema selected.
mysql-js>
3.8.2.2.5.1 Creating a Secure Session Using SSL

To establish an SSL connection, the URI parameter passed to the connect shell commands must include the SSL information as URL parameters. For example:

mysql-js> \connect root@localhost?ssl_ca=/path/to/ca/file&\
ssl_cert=/path/to/cert/file&ssl_key=/path/to/key/file
Creating XSession to root@localhost...
Enter password: ****
No default schema selected.
mysql-js>
3.8.2.2.6 Connections in JavaScript and Python

When a connection is made using the command-line options or by using any of the shell commands, a global session object is created. This session is global because once created, it can be used in any of the MySQL Shell execution modes.

Any global session object is available in JavaScript or Python modes because a variable called session holds a reference to it.

In SQL mode, both Node and Classic sessions can be used because they both expose SQL execution. In SQL mode an XSession cannot be used.

In addition to the global session object, sessions can be established and assigned to a different variable by using the functions available in the mysql and mysqlx JavaScript and Python modules.

For example, the following functions are provided by these modules:

  • mysql.getSession(connectionData[, password])

  • mysqlx.getNodeSession(connectionData[, password])

  • mysql.getClassicSession(connectionData[, password])

The first of these functions is used to create an XSession which features the most comprehensive development API and supports X Protocol.

The second creates a Node Session which connects to a X Protocol enabled MySQL Server and allows SQL Execution.

The latter returns a Classic Session object which uses the traditional MySQL protocol and has a very limited development API.

connectionData can be either a URI as specified above or a dictionary containing the connection parameters. See Section 3.8.2.2.1, “Connecting using a URI String”.

The following example shows how to create a Node Session using the X Protocol:

mysql-js> var mysqlx=require('mysqlx').mysqlx;

mysql-js> var session=mysqlx.getNodeSession('root@localhost');

mysql-js> print(session)
<NodeSession:root@localhost>
mysql-js>

The following example shows how to create a Node Session using the X Protocol so that you can execute SQL:

mysql-js> var mysqlx=require('mysqlx').mysqlx;

mysql-js> var session=mysqlx.getNodeSession({host: 'localhost', dbUser: 'root'});

mysql-js> print(session)
<NodeSession:root@localhost>
mysql-js>

The following example shows how to create a Classic Session:

mysql-js> var mysql=require('mysql').mysql;

mysql-js> var session = mysql.getClassicSession('root@localhost:3307');
mysql-js> print(session)
<ClassicSession:root@localhost:3307>
mysql-js>
3.8.2.2.6.1 Using SSL for Secure Connections

To establish an SSL connection, set the SSL information in the connectionData dictionary. For example:

mysql-js> var mysqlx=require('mysqlx').mysqlx;

mysql-js> var session=mysqlx.getNodeSession({host: 'localhost',
                                             dbUser: 'root',
                                             dbPassword: 'mypasswd',
                                             ssl_ca: "path_to_ca_file",
                                             ssl_cert: "path_to_cert_file",
                                             ssl_key: "path_to_key_file"});

mysql-js> print(session)
<NodeSession:root@localhost>
mysql-js>

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