Documentation Home
MySQL 5.7 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.9Mb
PDF (A4) - 37.9Mb
PDF (RPM) - 36.6Mb
HTML Download (TGZ) - 9.9Mb
HTML Download (Zip) - 9.9Mb
HTML Download (RPM) - 8.7Mb
Man Pages (TGZ) - 207.0Kb
Man Pages (Zip) - 315.4Kb
Info (Gzip) - 3.5Mb
Info (Zip) - 3.5Mb
Excerpts from this Manual Connecting using a URI String

You can configure the MySQL Server which MySQL Shell connects to by passing the connection data in URI type string format. Such strings can be used with the --uri command option, the MySQL Shell \connect command, and the shell.connect() method.

The URI type string should use the following format:


Percent encoding must be used for reserved characters in the elements of the URI type string. For example, if you specify a password that includes the @ character, the character must be replaced by %40.

The elements of a URI type string for a MySQL Shell connection are:

  • scheme: this element is required and specifies the connection protocol to use, currently either mysql for classic connection protocol and mysqlx for X Protocol.

  • user: this element is optional and specifies the MySQL user account to be used for the authentication process.

  • password: this element is optional and specifies the password to be used for the authentication process.


    Storing the password in the URI type string is insecure and not recommended.

  • target: this element is required and specifies the server instance the connection refers to. Can be either TCP connection information, a Unix socket path or a Windows named-pipe. If not specified, localhost is used by default.

    • TCP connection information can be either a host name, an IPv4 address, or an IPv6 address. Can include an optional port number in the format host:port, where port specifies a network port which the target MySQL server is listening on for connections. If not specified, 33060 is used by default for X Protocol connections, and 3306 is the default for classic MySQL protocol connections.

    • Unix socket and Windows named-pipe values are local file paths. There are two ways to specify such paths, using percent encoding or surrounding the path with parentheses, removing the need to percent encode characters such as the common directory separator /. For example, to connect as root@localhost using the Unix socket /tmp/mysqld.sock either specify the path using parenthesis as root@localhost?socket=(/tmp/mysqld.sock) or using percent encoding as root@localhost?socket=%2Ftmp%2Fmysqld.sock%2F.

  • schema: this element is optional and specifies the database to be set as default when the connection is established.

  • ?attribute=value: this element is optional and specifies a data dictionary that contains options.

If no password is specified using the URI type string, which is recommended, then the password is prompted for. The following examples show how to specify URI type strings with the user name user, in each case the password is prompted for:

  • An X Protocol connection to a local server instance listening at port 33065.

  • A classic MySQL protocol X Protocol connection to a local server instance listening at port 3333.

  • An X Protocol connection to a remote server instance, using a host name, an IPv4 address and an IPv6 address.

  • An optional path can be specified, which represents a database schema.

  • An optional query can be specified, consisting of values in the form of a key=value pair or as a single key. The , character is used as a separator for values, a combination of multiple pairs and keys can be specified. Values can be of type list, list values are ordered by appearance. Strings must be percent encoded.


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


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