MySQL Shell API 9.1.0
Unified development interface for MySQL Products
|
On the API exposed on the MySQL Shell, several functions require some connection data to be provided.
The connection data may be specified in the following formats:
A basic URI string has the following format:
[scheme://][user[:password]@]<host[:port]|socket>[/schema][?option=value&option=value...]
Connection Options
The following options are valid for use either in a URI or in a dictionary:
When these options are defined in a URI, their values must be URL encoded.
The following options are also valid when a dictionary is used:
Base Connection Options
SSH Tunnel Connection Options
The connection options are case insensitive and can only be defined once.
If an option is defined more than once, an error will be generated.
The options specified in the connection data determine the type of connection to be used.
The scheme option defines the protocol to be used on the connection, the following are the accepted values:
If no protocol is specified in the connection data, the shell will first attempt connecting using the X protocol, if the connection fails it will then try to connect using the MySQL protocol.
In general, the Shell connects to the server using TCP connections, unless the connection data contains the options required to create any of the connections described below.
Unix-domain Socket Connections
To connect to a local MySQL server using a Unix-domain socket, the host must be set to 'localhost', no port number should be provided and the socket path should be provided.
When using the MySQL protocol, the socket path might not be provided, in such case a default path for the socket file will be used.
When using a connection dictionary, the socket path is set as the value for the socket option.
When using a URI, the socket path must be URL encoded as follows:
It is possible to skip the URL encoding by enclosing the socket path in parenthesis:
Windows Named Pipe Connections
To connect to MySQL server using a named pipe the host must be set to '.', no port number should be provided.
If the pipe name is not provided the default pipe name will be used: MySQL.
When using a connection dictionary, the named pipe name is set as the value for the socket option.
When using a URI, if the named pipe has invalid characters for a URL, they must be URL encoded. URL encoding can be skipped by enclosing the pipe name in parenthesis:
Named pipe connections are only supported on the MySQL protocol.
Windows Shared Memory Connections
Shared memory connections are only allowed if the server has shared memory connections enabled using the default shared memory base name: MySQL.
To connect to a local MySQL server using shared memory the host should be set to 'localhost' and no port should be provided.
If the server does not have shared memory connections enabled using the default base name, the connection will be done using TCP.
Shared memory connections are only supported on the MySQL protocol.
SSL Mode
The ssl-mode option accepts the following values:
TLS Version
The tls-version option accepts values in the following format: TLSv<version>, e.g. TLSv1.2, TLSv1.3.
Authentication method
In case of classic session, this is the name of the authentication plugin to use, i.e. caching_sha2_password. In case of X protocol session, it should be one of:
Connection Compression
Connection compression is governed by following connection options: "compression", "compression-algorithms", and "compression-level".
"compression" accepts following values:
For convenience "compression" also accepts Boolean: 'True', 'False', '1', and '0' values which map to REQUIRED and DISABLED respectively.
"compression-algorithms" expects comma separated list of algorithms. Supported algorithms include:
If "compression" connection option is not defined, its value will be deduced from "compression-algorithms" value when it is provided.
"compression-level" expects an integer value. Valid range depends on the compression algorithm and server configuration, but generally following is expected:
Connection Attributes
Connection attributes are key-value pairs to be sent to the server at connect time. They are stored at the following PERFORMANCE_SCHEMA tables:
These attributes should be defined when creating a session and are immutable during the life-time of the session.
To define connection attributes on a URI, the connection-attributes should be defined as part of the URI as follows:
root@localhost:port/schema?connection-attributes=[att1=value1,att2=val2,...]
Note that the characters used for the attribute name and value must follow the URI standard, this is, if the character is not allowed it must be percent encoded.
To define connection attributes when creating a session using a dictionary the connection-attributes option should be defined, its value can be set in the following formats:
Note that the connection-attribute values are expected to be strings, if other data type is used in the dictionary, the string representation of the used data will be stored on the database.
URL Encoding
URL encoded values only accept alphanumeric characters and the next symbols: -._~!$'()*+;
Any other character must be URL encoded.
URL encoding is done by replacing the character being encoded by the sequence: %XX
Where XX is the hexadecimal ASCII value of the character being encoded.
If host is a literal IPv6 address it should be enclosed in "[" and "]" characters.
If host is a literal IPv6 address with zone ID, the '%' character separating address from the zone ID needs to be URL encoded.