MySQL Shell 8.0  /  ...  /  Connecting using a URI String

2.1.2 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 methods such as shell.connect() or dba.createCluster()

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. If you include a zone ID in an IPv6 address, the % character used as the separator must be replaced with %25.

The options you can use in a URI type string for a MySQL Shell connection are described at Section 2.1.1, “Valid Connection 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.


By default, MySQL Shell assumes that connections require a password. The password is requested at the login prompt. If the user has a password-less account, which is insecure and not recommended, or if socket peer-credential authentication is in use (for Unix socket connections), you must explicitly specify that no password is provided and the password prompt is not required. To do this, place a : after the user in the URI type string but do not specify a password after it. For example: