Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 44.7Mb
PDF (A4) - 44.7Mb
PDF (RPM) - 40.5Mb
HTML Download (TGZ) - 10.5Mb
HTML Download (Zip) - 10.5Mb
HTML Download (RPM) - 9.1Mb
Man Pages (TGZ) - 205.8Kb
Man Pages (Zip) - 309.0Kb
Info (Gzip) - 3.9Mb
Info (Zip) - 3.9Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Connecting Using a URI or Key-Value Pairs

4.2.3 Connecting Using a URI or Key-Value Pairs

In addition to specifying the connection parameters to an instance of MySQL server documented at Section 4.2.2, “Connecting to the MySQL Server”, you can specify the connection using a URI-type string or key-value pairs. The following MySQL clients support specifying the connection to MySQL server instance using a URI-type string or key-value pairs:

  • MySQL Shell

  • MySQL Router

  • MySQL Connectors which implement X DevAPI

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

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

This section consists of:

Base Connection Parameters

This section describes the parameters available when specifying a connection to MySQL. The following parameters can be provided as either a URI type string or in a key-value pairs. In a URI type string they conform to the base URI, see Connecting using a URI String. Alternatively they can be specified as key-value pairs, see Connecting using Key-value Pairs.

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

Connection Options

You can specify options for the connection, either as part of a URI type string by appending ?attribute=value, or as key-value pairs. The following options are available:

  • ssl-mode: the SSL mode to be used for the connection. The following values are valid:

    • DISABLED

    • PREFERRED

    • REQUIRED

    • VERIFY_CA

    • VERIFY_IDENTITY

  • 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: TLS version permitted for secure connections. The following values are valid:

    • TLSv1

    • TLSv1.1

    • TLSv1.2 (Supported only by commercial edition)

  • auth-method: Authentication method used for the connection. Defaults to AUTO, meaning that the server attempts to guess. The following values are valid:

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

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

  • compression: When set to true (or 1), this option enables compression of all information sent between the client and the server if both support compression. The default is no compression (false or 0). This option is available for MySQL Shell connections using classic MySQL protocol only.

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 Base Connection 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 X Protocol connection using a socket, with the path either provided using percent encoding or parenthesis.

    mysqlx://user@/path%2Fto%2Fsocket.sock
    mysqlx://user@(/path/to/socket.sock)
  • 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 Key-value Pairs

You can specify a connection to MySQL Server using key-value pairs. These key-value pairs are supplied in language natural constructs for the implementation. This means you can supply connection parameters using key-value pairs as a JSON object in JavaScript, or using key-value pairs in a dictionary in Python. Regardless of the way the key-value pairs are supplied, the concept remains the same - the keys as specified in this section can be assigned values that are used to specify a connection. You can specify connections using key-value pairs in MySQL Shell's shell.connect() method or InnoDB cluster's dba.createCluster() method, and with some of the MySQL Connectors which implement X DevAPI.

Generally, key-value pairs are surrounded by { and } characters and the , character is used as a separator between key-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, unlike URI type strings.

A connection specified as key-value pairs has the following format:

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

The parameters you can use as keys for a connection are described at Base Connection Parameters.

If no password is specified, which is recommended, then in interactive clients the password is prompted for. The following examples show how to specify connections using key-value pairs with the user name user:

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

    {user:'user', host:'localhost', port:33065}
  • A classic MySQL 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 X Protocol connection using a socket.

    {user:'user', socket:'/path/to/socket/file/'}
  • 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.