Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 38.2Mb
PDF (A4) - 38.3Mb
PDF (RPM) - 33.1Mb
HTML Download (TGZ) - 8.1Mb
HTML Download (Zip) - 8.1Mb
HTML Download (RPM) - 7.0Mb
Man Pages (TGZ) - 133.2Kb
Man Pages (Zip) - 189.3Kb
Info (Gzip) - 3.4Mb
Info (Zip) - 3.4Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Connecting Using a Path

4.2.3 Connecting Using a Path

In addition to specifying the connection parameters to an instance of MySQL documented at Section 4.2.2, “Connecting to the MySQL Server”, you can specify the connection to MySQL server using a path. This section consists of:

The following MySQL clients support specifying the connection to MySQL server using a path:

  • MySQL Shell

  • MySQL Router

  • MySQL Connectors which implement X DevAPI

Many of the parameters you specify in a path are similar to those used with the command options, and this section documents all of the valid path parameters. The connection's parameters can be specified as:

Connection Path Parameters

This section describes the parameters available when specifying a connection to MySQL as a path. The following options are valid for use in either a URI type string or in a data dictionary:

  • scheme: specifies the connection protocol to use. Use mysqlx for X Protocol connections and mysql for classic MySQL protocol connections. If no protocol is specified, the server attempts to guess the protocol.

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

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

    Warning

    Storing the password in the connection path is insecure and not recommended.

  • host: specifies the server instance the connection refers to. Can be either an IPv4 address, an IPv6 address or a hostname. If not specified, localhost is used by default.

  • 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.

  • socket: path to a Unix socket or Windows named-pipe. Values are local file paths and must be encoded in URI type strings, using percent encoding or surrounding the path with parentheses, which removes the need to percent encode characters such as the common directory separator /. To connect as root@localhost using the Unix socket /tmp/mysqld.sock either specify the path using parenthesis, for example root@localhost?socket=(/tmp/mysqld.sock), or using percent encoding, for example root@localhost?socket=%2Ftmp%2Fmysqld.sock.

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

  • ?attribute=value: specifies a data dictionary that contains options.

The connection parameters are case insensitive and can only be defined once. If a parameter is defined more than once, an error is generated.

In addition to the parameters listed in the previous list, the following options are also valid when a dictionary is used:

  • ssl-mode: the SSL mode to be used for the connection.

  • ssl-ca: the path to the X.509 certificate authority in PEM format.

  • ssl-capath: the path to the directory that contains the X.509 certificates authorities in PEM format.

  • ssl-cert: The path to the X.509 certificate in PEM format.

  • ssl-key: The path to the X.509 key in PEM format.

  • ssl-crl: The path to file that contains certificate revocation lists.

  • ssl-crlpath: The path to the directory that contains certificate revocation list files.

  • ssl-cipher: the SSL cipher to use.

  • tls-version: List of protocols permitted for secure connections

  • auth-method: Authentication method used for the connection. Defaults to AUTO, meaning that the server attempts to guess. Can be one of the following:

    • AUTO

    • MYSQL41

    • SHA256_MEMORY

    • FROM_CAPABILITIES

    • FALLBACK

    • PLAIN

    When using an X Protocol connection, any configured auth-method is overridden to this sequence of authentication methods: MYSQL41, SHA256_MEMORY, PLAIN.

  • get-server-public-key: Request public key from the server required for RSA key pair-based password exchange. Use when connecting to MySQL 8.0 servers over classic MySQL protocol with SSL mode DISABLED. You must specify the protocol in this case, for example:

    mysql://user@localhost:3306?get-server-key=true
  • server-public-key-path: The path name to a file containing a client-side copy of the public key required by the server for RSA key pair-based password exchange. Use when connecting to MySQL 8.0 servers over classic MySQL protocol with SSL mode DISABLED.

The ?attribute=value options data dictionary can contain the following options:

  • mycnfPath: the path to the MySQL configuration file of the instance.

  • outputMycnfPath: alternative output path to write the MySQL configuration file of the instance.

  • password: the password to be used by the connection.

  • clusterAdmin: the name of the InnoDB cluster administrator user to be created. The supported format is the standard MySQL account name format.

  • clusterAdminPassword: the password for the InnoDB cluster administrator account.

  • clearReadOnly: a boolean value used to confirm that super_read_only must be disabled.

  • interactive: a boolean value used to disable the interactive wizards which start after issuing commands. For example prompts provided when global variables are not populated, confirmation prompts after changing a instance's configuration.

  • restart: a boolean value used to indicate that a remote restart of the target instance should be performed to finalize the operation.

  • connect-timeout: an integer value used to configure the number of seconds clients, such as MySQL Shell, wait until the client stops trying to connect to an unresponsive MySQL server.

Connecting using a URI String

You can specify a connection to MySQL Server using a URI type string format. Such strings can be used with the MySQL Shell with the --uri command option, the MySQL Shell \connect command, MySQL Connectors which implement X DevAPI, and tools such as MySQL Router.

A URI type string has the following format:

[scheme://][user[:[password]]@]target[:port][/schema][?attribute1=value1&attribute2=value2...
Important

Percent encoding must be used for reserved characters in the elements of the URI type string. For example, if you specify a string 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 parameters you can use in a URI type string for a connection are described at Connection Path Parameters.

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:

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

    mysql://user@localhost:3333
  • An X Protocol connection to a local server instance listening at port 33065.

    mysqlx://user@localhost:33065
  • An X Protocol connection to a remote server instance, using a host name, an IPv4 address and an IPv6 address.

    mysqlx://user@server.example.com/
    mysqlx://user@198.51.100.14:123
    mysqlx://user@[2001:db8:85a3:8d3:1319:8a2e:370:7348]
  • An optional path can be specified, which represents a database schema.

    mysqlx://user@198.51.100.1/world%5Fx
    mysqlx://user@198.51.100.2:33060/world
  • 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 either percent encoded or surrounded by parenthesis. The following are equivalent.

    ssluser@127.0.0.1?ssl-ca=%2Froot%2Fclientcert%2Fca-cert.pem\
    &ssl-cert=%2Froot%2Fclientcert%2Fclient-cert.pem\
    &ssl-key=%2Froot%2Fclientcert%2Fclient-key
    
    ssluser@127.0.0.1?ssl-ca=(/root/clientcert/ca-cert.pem)\
    &ssl-cert=(/root/clientcert/client-cert.pem)\
    &ssl-key=(/root/clientcert/client-key)

The previous examples assume that connections require a password, and with interactive clients the specified user's 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 example with Unix socket connections), you must explicitly specify in the URI type string that no password is being 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:

mysqlx://user:@localhost

Connecting using a Data Dictionary

You can specify a connection to MySQL Server using a data dictionary of key and value pairs. Data dictionaries can be used with MySQL Shell methods such as shell.connect() or dba.createCluster(), and with MySQL Connectors which implement X DevAPI.

Data dictionaries are surrounded by { and } characters and the , character is used as a separator between key and value pairs. The : character is used between keys and values, and strings must be delimited, for example using the ' character. It is not necessary to percent encode strings in data dictionaries, unlike URI type strings.

A data dictionary has the following format:

{ key: value, key: value, ...}

The parameters you can use in a data dictionary for a connection are described at Connection Path Parameters.

If no password is specified using a data dictionary, which is recommended, then the password is prompted for. The following examples show how to specify data dictionaries 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.

    {user:'user', host:'localhost', port:33065}
  • A classic MySQL protocol X Protocol connection to a local server instance listening at port 3333.

    {user:'user', host:'localhost', port:3333}
  • An X Protocol connection to a remote server instance, using a host name, an IPv4 address and an IPv6 address.

    {user:'user', host:'server.example.com'}
    {user:'user', host:198.51.100.14:123}
    {user:'user', host:[2001:db8:85a3:8d3:1319:8a2e:370:7348]}
  • An optional schema can be specified, which represents a database.

    {user:'user', host:'localhost', schema:'world'}

The previous examples assume that connections require a password, and with interactive clients the specified user's 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 example with Unix socket connections), you must explicitly specify that no password is being provided and the password prompt is not required. To do this, provide an empty string using '' after the password key. For example:

{user:'user', password:'', host:'localhost'}

User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.