4.2.5 Connecting to the Server Using URI-Like Strings or Key-Value Pairs

scheme: The connection protocol to use. Use mysqlx for X Protocol connections and mysql for classic MySQL protocol connections (see MySQL Shell Sessions Explained). If no protocol is specified, the server attempts to guess the protocol.

user: The MySQL user account to use for the authentication process.

password: The password to use for the authentication process.

host: The host on which the server instance is running. The value can be a host name, IPv4 address, or IPv6 address. If no host is specified, the default is localhost.

port: The TCP/IP network port on which the target MySQL server is listening for connections. If no part is specified, the default is 33060 for X Protocol connections and 3306 for classic MySQL protocol connections.

socket: The path to a Unix socket file or the name of a Windows named pipe. Values are local file paths. In URI-like strings, they must be encoded, using either percent encoding or by surrounding the path with parentheses. Parentheses eliminate the need to percent encode characters such as the / directory separator character. For example, to connect as root@localhost using the Unix socket /tmp/mysql.sock, specify the path using percent encoding as root@localhost?socket=%2Ftmp%2Fmysql.sock, or using parentheses as root@localhost?socket=(/tmp/mysql.sock).

schema: The default database for the connection. If no database is specified, the connection has no default database.

ssl-mode: The desired security state for the connection. The following modes are permissible:

For information about these modes, see the --ssl-mode option description in Command Options for Encrypted Connections.

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

ssl-capath: The path to the directory that contains the X.509 certificates authority files in PEM format.

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

ssl-cipher: The SSL cipher to use.

ssl-crl: The path to the file that contains certificate revocation lists in PEM format.

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

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

tls-version: The permissible TLS protocols for encrypted connections. The value is a list of one or more comma-separated protocol names. For details, see Section 6.3.2, “Encrypted Connection Protocols and Ciphers”. The following versions are permissible:

auth-method: The authentication method to use for the connection. The default is AUTO, meaning that the server attempts to guess. The following methods are permissible:

For X Protocol connections, any configured auth-method is overridden to this sequence of authentication methods: MYSQL41, SHA256_MEMORY, PLAIN.

get-server-public-key: Request from the server the public key 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-public-key=true

This option applies to clients that authenticate with the caching_sha2_password authentication plugin. For that plugin, the server does not send the public key unless requested. This option is ignored for accounts that do not authenticate with that plugin. It is also ignored if RSA-based password exchange is not used, as is the case when the client connects to the server using a secure connection.

If server-public-key-path=file_name is given and specifies a valid public key file, it takes precedence over get-server-public-key.

For information about the caching_sha2_password plugin, see Section 6.4.1.3, “Caching SHA-2 Pluggable Authentication”.

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 file must be in PEM format. This option applies to clients that authenticate with the sha256_password or caching_sha2_password authentication plugin. This option is ignored for accounts that do not authenticate with one of those plugins. It is also ignored if RSA-based password exchange is not used, as is the case when the client connects to the server using a secure connection.

If server-public-key-path=file_name is given and specifies a valid public key file, it takes precedence over get-server-public-key.

For information about the sha256_password and caching_sha2_password plugins, see Section 6.4.1.2, “SHA-256 Pluggable Authentication”, and Section 6.4.1.3, “Caching SHA-2 Pluggable Authentication”.

connect-timeout: An integer value used to configure the number of seconds that clients, such as MySQL Shell, wait until they stop 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 possible. The default is no compression (false or 0). This option is available for MySQL Shell connections using classic MySQL protocol only. See Section 4.2.6, “Connection Compression Control”.

connection-attributes: Controls the key-value pairs that application programs pass to the server at connect time. For general information about connection attributes, see Section 26.12.9, “Performance Schema Connection Attribute Tables”. Clients usually define a default set of attributes, which can be disabled or enabled. For example:

mysqlx://user@host?connection-attributes
mysqlx://user@host?connection-attributes=true
mysqlx://user@host?connection-attributes=false

The default behavior is to send the default attribute set. Applications can specify attributes to be passed in addition to the default attributes. You specify additional connection attributes as a connection-attributes parameter in a connection string. The connection-attributes parameter value must be empty (the same as specifying true), a Boolean value (true or false to enable or disable the default attribute set), or a list or zero or more key=value specifiers separated by commas (to be sent in addition to the default attribute set). Within a list, a missing key value evaluates as an empty string. Further examples:

mysqlx://user@host?connection-attributes=[attr1=val1,attr2,attr3=]
mysqlx://user@host?connection-attributes=[]

Application-defined attribute names cannot begin with _ because such names are reserved for internal attributes.

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

mysqlx://user_name@localhost:33065

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

mysql://user_name@localhost:3333

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

mysqlx://user_name@server.example.com/
mysqlx://user_name@198.51.100.14:123
mysqlx://user_name@[2001:db8:85a3:8d3:1319:8a2e:370:7348]

An X Protocol connection using a socket, with the path provided using either percent encoding or parentheses.

mysqlx://user_name@/path%2Fto%2Fsocket.sock
mysqlx://user_name@(/path/to/socket.sock)

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

# use 'world' as the default database
mysqlx://user_name@198.51.100.1/world

# use 'world_x' as the default database, encoding _ as %5F
mysqlx://user_name@198.51.100.2:33060/world%5Fx

An optional query can be specified, consisting of values each given as a key=value pair or as a single key. To specify multiple values, separate them by , characters. A mix of key=value and key values is permissible. Values can be of type list, with list values ordered by appearance. Strings must be either percent encoded or surrounded by parentheses. 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)

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

{user:'user_name', host:'localhost', port:33065}

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

{user:'user_name', 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_name', host:'server.example.com'}
{user:'user_name', host:198.51.100.14:123}
{user:'user_name', host:[2001:db8:85a3:8d3:1319:8a2e:370:7348]}

An X Protocol connection using a socket.

{user:'user_name', socket:'/path/to/socket/file'}

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

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