in unittest/scripts/auto/js_shell/validation/shell_help_norecord.js [788:1843]
All subsequent text output (except for prompts and user interaction) is
going to be forwarded to the pager.
This behavior is in effect until disablePager() is called or current
scripting mode is changed.
Changing the scripting mode has the same effect as calling
disablePager().
If the value of shell.options.pager option is changed after this method
has been called, the new pager will be automatically used.
If shell.options.pager option is set to an empty string when this method
is called, pager will not be active until shell.options.pager is set to a
non-empty string.
This method has no effect in non-interactive mode.
//@<OUT> Help on getSession
NAME
getSession - Returns the global session.
SYNTAX
shell.getSession()
DESCRIPTION
The returned object will be either a ClassicSession or a Session object,
depending on how the global session was created.
//@<OUT> Help on Help
NAME
help - Provides help about this object and it's members
SYNTAX
shell.help([member])
WHERE
member: If specified, provides detailed information on the given member.
//@<OUT> Help on listCredentialHelpers
NAME
listCredentialHelpers - Returns a list of strings, where each string is a
name of a helper available on the current
platform.
SYNTAX
shell.listCredentialHelpers()
RETURNS
A list of string with names of available credential helpers.
DESCRIPTION
The special values "default" and "<disabled>" are not on the list.
Only values on this list (plus "default" and "<disabled>") can be used to
set the "credentialStore.helper" option.
//@<OUT> Help on listCredentials
NAME
listCredentials - Retrieves a list of all URLs stored by the configured
helper.
SYNTAX
shell.listCredentials()
RETURNS
A list of URLs stored by the configured credential helper.
EXCEPTIONS
Throws RuntimeError in the following scenarios:
- if configured credential helper is invalid.
- if listing the URLs fails.
//@<OUT> Help on listSshConnections
NAME
listSshConnections - Retrieves a list of all active SSH tunnels.
SYNTAX
shell.listSshConnections()
RETURNS
A list of active SSH tunnel connections.
//@<OUT> Help on Log
NAME
log - Logs an entry to the shell's log file.
SYNTAX
shell.log(level, message)
WHERE
level: one of ERROR, WARNING, INFO, DEBUG, DEBUG2, DEBUG3 as a string
message: the text to be logged
DESCRIPTION
Only messages that have a level value equal to or lower than the active
one (set via --log-level) are logged.
//@<OUT> Help on parseUri
NAME
parseUri - Utility function to parse a URI string.
SYNTAX
shell.parseUri(uri)
WHERE
uri: a URI string.
RETURNS
A dictionary containing all the elements contained on the given URI
string.
DESCRIPTION
Parses a URI string and returns a dictionary containing an item for each
found element.
A basic URI string has the following format:
[scheme://][user[:password]@]<host[:port]|socket>[/schema][?option=value&option=value...]
For more details about how a URI is created as well as the returned
dictionary, use \? connection
//@<OUT> Help on Prompt
NAME
prompt - Utility function to prompt data from the user.
SYNTAX
shell.prompt(message[, options])
WHERE
message: a string with the message to be shown to the user.
options: Dictionary with options that change the function behavior.
RETURNS
A string value containing the result based on the user input.
DESCRIPTION
This function allows creating scripts that require interaction with the
user to gather data.
The options dictionary may contain the following options:
- title: a string to identify the prompt.
- description: a string list with a description of the prompt, each entry
represents a paragraph.
- type: a string value to define the prompt type. Supported types
include: text, password, confirm, select, fileOpen, fileSave,
directory. Default value: text.
- defaultValue: defines the default value to be used in case the user
accepts the prompt without providing custom information. The value of
this option depends on the prompt type.
- yes: string value to overwrite the default '&Yes' option on 'confirm'
prompts.
- no: string value to overwrite the default '&No' option on 'confirm'
prompts.
- alt: string value to define an additional option for 'confirm' prompts.
- options: string list of options to be used in 'select' prompts.
General Behavior
The 'title' option is not used in the Shell but it might be useful for
better integration with external plugins handling prompts.
When the 'description' option is provided, each entry will be printed as
a separate paragraph.
Once the description is printed, the content of the message parameter
will be printed and input from the user will be required.
The value of the 'defaultValue' option and the returned value will depend
on the 'type' option, as explained on the following sections.
Open Prompts
These represent prompts without a pre-defined set of valid answers, the
prompt types on this category include: text, password, fileOpen, fileSave
and directory.
The 'defaultValue' on these prompts can be set to a string to be returned
by the function if the user replies to the prompt with an empty string,
if not defined then the prompt will accept and return the empty string.
The returned value on these prompts will be either the value set on
'defaultValue' option or the value entered by the user.
In the case of password type prompts, the data entered by the user will
not be displayed on the screen.
Confirm Prompts
The default behaviour of these prompts if to allow the user answering
Yes/No questions, however, the default '&Yes' and '&No' options can be
overriden through the 'yes' and 'no' options.
An additional option can be added to the prompt by defining the 'alt'
option.
The 'yes', 'no' and 'alt' options are used to define the valid answers
for the prompt. The ampersand (&) symbol can be used to define a single
character which acts as a shortcut for the user to select the indicated
answer.
i.e. using an option like: '&Yes' causes the following to be valid
answers (case insensitive): 'Yes', '&Yes', 'Y'.
All the valid answers must be unique within the prompt call.
If the 'defaultValue' option is defined, it must be set equal to any of
the valid prompt answers, i.e. if the 'yes', 'no' and 'alt' options are
not defined, then 'defaultValue' can be set to one of '&Yes', 'Yes', 'Y',
'&No', 'No' or 'N', case insensitive, otherwise, it must be set to one of
the valid answers based on the values defined in the 'yes', 'no' or 'alt'
options.
This prompt will be shown repeatedly until the user explicitly replies
with one of the valid answers unless a 'defaultValue' is provided, which
will be used in case the user replies with an empty answer.
The returned value will be the label associated to the user provided
answer.
i.e. if the prompt is using the default options ('&Yes' and '&No') and
the user response is 'n' the prompt function will return '&No'.
Select Prompts
These prompts allow the user selecting an option from a pre-defined list
of options.
To define the list of options to be used in the prompt the 'options'
option should be used.
If the 'defaultValue' option is defined, it must be a number representing
the 1 based index of the option to be selected by default.
This prompt will be shown repeatedly until the user explicitly replies
with the 1 based index of the option to be selected unless a default
option is pre-defined through the 'defaultValue' option.
The returned value will be the text of the selected option.
//@<OUT> Help on shell.disconnect
NAME
disconnect - Disconnects the global session.
SYNTAX
shell.disconnect()
//@<OUT> Help on reconnect
NAME
reconnect - Reconnect the global session.
SYNTAX
shell.reconnect()
//@<OUT> Help on registerGlobal
NAME
registerGlobal - Registers an extension object as a shell global object.
SYNTAX
shell.registerGlobal(name, object[, definition])
WHERE
name: The name to be given to the registered global object.
object: The extension object to be registered as a global object.
definition: Dictionary containing help information about the object.
DESCRIPTION
An extension object is created with the shell.createExtensionObject
function. Once registered, the functionality it provides will be
available for use.
The name parameter must comply with the following restrictions:
- It must be a valid scripting identifier.
- It can not be the name of a built in global object.
- It can not be the name of a previously registered object.
The name used to register an object will be exactly the name under which
the object will be available for both Python and JavaScript modes, this
is, no naming convention is enforced on global objects.
The definition parameter is a dictionary with help information about the
object being registered, it allows the following properties:
- brief: a string with a brief description of the object.
- details: a list of strings with additional information about the
object.
When the object is registered, the help data on the definition parameter
as well as the object members is made available through the shell built
in help system. (\?).
//@<OUT> Help on registerReport
NAME
registerReport - Registers a new user-defined report.
SYNTAX
shell.registerReport(name, type, report[, description])
WHERE
name: Name of the registered report.
type: Type of the registered report, one of: 'list', 'report' or 'print'.
report: Function to be called when the report is requested.
description: Dictionary describing the report being registered.
DESCRIPTION
The name of the report must be unique and a valid scripting identifier. A
case-insensitive comparison is used to validate the uniqueness.
The type of the report must be one of: 'list', 'report' or 'print'. This
option specifies the expected result of calling this report as well as
the output format if it is invoked using \show or \watch commands.
The report function must have the following signature: Dict
report(Session session, List argv, Dict options), where:
- session - Session object used by the report to obtain the data.
- argv (optional) - Array of strings representing additional arguments.
- options (optional) - Dictionary with values for various report-specific
options.
Each report returns a dictionary with the following keys:
- report (required) - List of JSON objects containing the report. The
number and types of items in this list depend on type of the report.
The description dictionary may contain the following optional keys:
- brief - A string value providing a brief description of the report.
- details - A list of strings providing a detailed description of the
report.
- options - A list of dictionaries describing the options accepted by the
report. If this is not provided, the report does not accept any
options.
- argc - A string representing the number of additional arguments
accepted by the report. This string can be either: a number specifying
exact number of arguments, * specifying zero or more arguments, two
numbers separated by a '-' specifying a range of arguments or a number
and * separated by a '-' specifying a range of arguments without an
upper bound. If this is not provided, the report does not accept any
additional arguments.
- examples - A list of dictionaries describing the example usage of the
report.
The optional options list must hold dictionaries with the following keys:
- name (string, required) - Name of the option, must be a valid scripting
identifier. This specifies an option name in the long form (--long)
when invoking the report using \show or \watch commands or a key name
of an option when calling this report as a function. Must be unique for
a report.
- shortcut (string, optional) - alternate name of the option, must be an
alphanumeric character. This specifies an option name in the short form
(-s). The short form of an option can only be used when invoking the
report using \show or \watch commands, it is not available when calling
the report as a function. If this key is not specified, option will not
have a short form. Must be unique for a report.
- brief (string, optional) - brief description of the option.
- details (array of strings, optional) - detailed description of the
option.
- type (string, optional) - value type of the option. Allowed values are:
'string', 'bool', 'integer', 'float'. If this key is not specified it
defaults to 'string'. If type is specified as 'bool', this option is a
switch: if it is not specified when invoking the report it defaults to
'false'; if it's specified when invoking the report using \show or
\watch commands it does not accept any value and defaults to 'true'; if
it is specified when invoking the report using the function call it
must have a valid value.
- required (Boolean, optional) - whether this option is required. If this
key is not specified, defaults to false. If option is a 'bool' then
'required' cannot be 'true'.
- values (list of strings, optional) - list of allowed values. Only
'string' options may have this key. If this key is not specified, this
option accepts any values.
- empty (Boolean, optional) - whether this option accepts empty strings.
Only 'string' options may have this key. If this key is not specified,
defaults to false.
The optional examples list must hold dictionaries with the following
keys:
- description (string, required) - Description text of the example.
- args (list of strings, optional) - List of the arguments used in the
example.
- options (dictionary of strings, optional) - Options used in the
example.
The type of the report determines the expected result of a report
invocation:
- The 'list' report returns a list of lists of values, with the first
item containing the names of the columns and remaining ones containing
the rows with values.
- The 'report' report returns a list with a single item.
- The 'print' report returns an empty list.
The type of the report also determines the output form when report is
called using \show or \watch commands:
- The 'list' report will be displayed in tabular form (or vertical if
--vertical option is used).
- The 'report' report will be displayed in YAML format.
- The 'print' report will not be formatted by Shell, the report itself
will print out any output.
The registered report is can be called using \show or \watch commands in
any of the scripting modes.
The registered report is also going to be available as a method of the
shell.reports object.
Users may create custom report files in the init.d folder located in the
Shell configuration path (by default it is ~/.mysqlsh/init.d in Unix and
%AppData%\MySQL\mysqlsh\init.d in Windows).
Custom reports may be written in either JavaScript or Python. The
standard file extension for each case should be used to get them properly
loaded.
All reports registered in those files using the registerReport() method
will be available when Shell starts.
EXCEPTIONS
Throws ArgumentError in the following scenarios:
- if a report with the same name is already registered.
- if 'name' of a report is not a valid scripting identifier.
- if 'type' is not one of: 'list', 'report' or 'print'.
- if 'name' of a report option is not a valid scripting identifier.
- if 'name' of a report option is reused in multiple options.
- if 'shortcut' of a report option is not an alphanumeric character.
- if 'shortcut' of a report option is reused in multiple options.
- if 'type' of a report option holds an invalid value.
- if the 'argc' key of a 'description' dictionary holds an invalid value.
//@<OUT> Help on setCurrentSchema
NAME
setCurrentSchema - Sets the active schema on the global session.
SYNTAX
shell.setCurrentSchema(name)
WHERE
name: The name of the schema to be set as active.
DESCRIPTION
Once the schema is set as active, it will be available through the db
global object.
//@<OUT> Help on setSession
NAME
setSession - Sets the global session.
SYNTAX
shell.setSession(session)
WHERE
session: The session object to be used as global session.
DESCRIPTION
Sets the global session using a session from a variable.
//@<OUT> Help on status
NAME
status - Shows connection status info for the shell.
SYNTAX
shell.status()
DESCRIPTION
This shows the same information shown by the \status command.
//@<OUT> Help on storeCredential
NAME
storeCredential - Stores given credential using the configured helper.
SYNTAX
shell.storeCredential(url[, password])
WHERE
url: URL of the server for the password to be stored.
password: Password for the given URL.
DESCRIPTION
If password is not provided, displays password prompt.
If URL is already in storage, it's value is overwritten.
URL needs to be in the following form: user@(host[:port]|socket).
EXCEPTIONS
Throws ArgumentError if URL has invalid form.
Throws RuntimeError in the following scenarios:
- if configured credential helper is invalid.
- if storing the credential fails.
//@<OUT> BUG28393119 UNABLE TO GET HELP ON CONNECTION DATA, before session
The connection data may be specified in the following formats:
- A URI string
- A dictionary with the connection options
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:
- ssl-mode: The SSL mode to be used in the connection.
- ssl-ca: The path to the X509 certificate authority file in PEM format.
- ssl-capath: The path to the directory that contains the X509 certificate
authority files in PEM format.
- ssl-cert: The path to the SSL public key certificate file in PEM format.
- ssl-key: The path to the SSL private key file in PEM format.
- ssl-crl: The path to file that contains certificate revocation lists.
- ssl-crlpath: The path of directory that contains certificate revocation list
files.
- ssl-cipher: The list of permissible encryption ciphers for connections that
use TLS protocols up through TLSv1.2.
- tls-version: List of protocols permitted for secure connections.
- tls-ciphers: List of TLS v1.3 ciphers to use.
- auth-method: Authentication method.
- 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
with classic MySQL sessions with SSL mode DISABLED.
- 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 with classic MySQL
sessions with SSL mode DISABLED.
- connect-timeout: The connection timeout in milliseconds. If not provided a
default timeout of 10 seconds will be used. Specifying a value of 0 disables
the connection timeout.
- compression: Enable compression in client/server protocol.
- compression-algorithms: Use compression algorithm in server/client protocol.
- compression-level: Use this compression level in the client/server protocol.
- connection-attributes: List of connection attributes to be registered at the
PERFORMANCE_SCHEMA connection attributes tables.
- local-infile: Enable/disable LOAD DATA LOCAL INFILE.
- net-buffer-length: The buffer size for TCP/IP and socket communication.
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
- uri: a URI string.
- scheme: the protocol to be used on the connection.
- user: the MySQL user name to be used on the connection.
- dbUser: alias for user.
- password: the password to be used on the connection.
- dbPassword: same as password.
- host: the hostname or IP address to be used on the connection.
- port: the port to be used in a TCP connection.
- socket: the socket file name to be used on a connection through unix sockets.
- schema: the schema to be selected once the connection is done.
SSH Tunnel Connection Options
- ssh: a SSHURI string used when SSH tunnel is required.
- ssh-password: the password the be used on the SSH connection.
- ssh-identity-file: the key file to be used on the SSH connection.
- ssh-identity-file-password: the SSH key file password.
- ssh-config-file: the SSH configuration file, default is the value of
shell.options['ssh.configFile']
ATTENTION: The dbUser and dbPassword options are will be removed in a future
release.
ATTENTION: The connection options have precedence over options specified in the
connection options uri
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:
- mysql: for connections using the MySQL protocol.
- mysqlx: for connections using the X protocol.
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:
- user@/path%2Fto%2Fsocket.sock
- user@./path%2Fto%2Fsocket.sock
- user@../path%2Fto%2Fsocket.sock
It is possible to skip the URL encoding by enclosing the socket path in
parenthesis:
- user@(/path/to/socket.sock)
- user@(./path/to/socket.sock)
- user@(../path/to/socket.sock)
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:
- user@\\.\named.pipe
- user@(\\.\named.pipe)
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:
- DISABLED
- PREFERRED
- REQUIRED
- VERIFY_CA
- VERIFY_IDENTITY
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:
- AUTO,
- FROM_CAPABILITIES,
- FALLBACK,
- MYSQL41,
- PLAIN,
- SHA256_MEMORY.
Connection Compression
Connection compression is governed by following connection options:
"compression", "compression-algorithms", and "compression-level".
"compression" accepts following values:
- REQUIRED: connection will only be made when compression negotiation is
succesful.
- PREFFERED: (default for X protocol connections) shell will attempt to
establish connection with compression enabled, but if compression negotiation
fails, connection will be established without compression.
- DISABLED: (defalut for classic protocol connections) connection will be
established without compression.
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:
- zstd
- zlib
- lz4 (X protocol only)
- uncompressed - special value, which if it appears in the list, causes
connection to succeed even if compression negotiation fails.
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:
- zstd: 1-22 (default 3)
- zlib: 1-9 (default 3), supported only by X protocol
- lz4: 0-16 (default 2), supported only by X protocol.
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:
- session_account_connect_attrs: attributes for the current session, and other
sessions associated with the session account.
- session_connect_attrs: attributes for all sessions.
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:
- Array of "key=value" pairs.
- Dictionary containing the key-value pairs.
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.
//@<OUT> BUG28393119 UNABLE TO GET HELP ON CONNECTION DATA, after session
The connection data may be specified in the following formats:
- A URI string
- A dictionary with the connection options
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:
- ssl-mode: The SSL mode to be used in the connection.
- ssl-ca: The path to the X509 certificate authority file in PEM format.
- ssl-capath: The path to the directory that contains the X509 certificate
authority files in PEM format.
- ssl-cert: The path to the SSL public key certificate file in PEM format.
- ssl-key: The path to the SSL private key file in PEM format.
- ssl-crl: The path to file that contains certificate revocation lists.
- ssl-crlpath: The path of directory that contains certificate revocation list
files.
- ssl-cipher: The list of permissible encryption ciphers for connections that
use TLS protocols up through TLSv1.2.
- tls-version: List of protocols permitted for secure connections.
- tls-ciphers: List of TLS v1.3 ciphers to use.
- auth-method: Authentication method.
- 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
with classic MySQL sessions with SSL mode DISABLED.
- 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 with classic MySQL
sessions with SSL mode DISABLED.
- connect-timeout: The connection timeout in milliseconds. If not provided a
default timeout of 10 seconds will be used. Specifying a value of 0 disables
the connection timeout.
- compression: Enable compression in client/server protocol.
- compression-algorithms: Use compression algorithm in server/client protocol.
- compression-level: Use this compression level in the client/server protocol.
- connection-attributes: List of connection attributes to be registered at the
PERFORMANCE_SCHEMA connection attributes tables.
- local-infile: Enable/disable LOAD DATA LOCAL INFILE.
- net-buffer-length: The buffer size for TCP/IP and socket communication.
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
- uri: a URI string.
- scheme: the protocol to be used on the connection.
- user: the MySQL user name to be used on the connection.
- dbUser: alias for user.
- password: the password to be used on the connection.
- dbPassword: same as password.
- host: the hostname or IP address to be used on the connection.
- port: the port to be used in a TCP connection.
- socket: the socket file name to be used on a connection through unix sockets.
- schema: the schema to be selected once the connection is done.
SSH Tunnel Connection Options
- ssh: a SSHURI string used when SSH tunnel is required.
- ssh-password: the password the be used on the SSH connection.
- ssh-identity-file: the key file to be used on the SSH connection.
- ssh-identity-file-password: the SSH key file password.
- ssh-config-file: the SSH configuration file, default is the value of
shell.options['ssh.configFile']
ATTENTION: The dbUser and dbPassword options are will be removed in a future
release.
ATTENTION: The connection options have precedence over options specified in the
connection options uri
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:
- mysql: for connections using the MySQL protocol.
- mysqlx: for connections using the X protocol.
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:
- user@/path%2Fto%2Fsocket.sock
- user@./path%2Fto%2Fsocket.sock
- user@../path%2Fto%2Fsocket.sock
It is possible to skip the URL encoding by enclosing the socket path in
parenthesis:
- user@(/path/to/socket.sock)
- user@(./path/to/socket.sock)
- user@(../path/to/socket.sock)
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:
- user@\\.\named.pipe
- user@(\\.\named.pipe)
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:
- DISABLED
- PREFERRED
- REQUIRED
- VERIFY_CA
- VERIFY_IDENTITY
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:
- AUTO,
- FROM_CAPABILITIES,
- FALLBACK,
- MYSQL41,
- PLAIN,
- SHA256_MEMORY.
Connection Compression
Connection compression is governed by following connection options:
"compression", "compression-algorithms", and "compression-level".
"compression" accepts following values:
- REQUIRED: connection will only be made when compression negotiation is
succesful.
- PREFFERED: (default for X protocol connections) shell will attempt to
establish connection with compression enabled, but if compression negotiation
fails, connection will be established without compression.
- DISABLED: (defalut for classic protocol connections) connection will be
established without compression.
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:
- zstd
- zlib
- lz4 (X protocol only)
- uncompressed - special value, which if it appears in the list, causes
connection to succeed even if compression negotiation fails.
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:
- zstd: 1-22 (default 3)
- zlib: 1-9 (default 3), supported only by X protocol
- lz4: 0-16 (default 2), supported only by X protocol.
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:
- session_account_connect_attrs: attributes for the current session, and other
sessions associated with the session account.
- session_connect_attrs: attributes for all sessions.
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:
- Array of "key=value" pairs.
- Dictionary containing the key-value pairs.
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.
SEE ALSO
Additional entries were found matching connection
The following topics were found at the SQL Syntax category:
- ALTER TABLE
- CREATE TABLE
?{(VER(>=5.7.27) && VER(<8.0.0)) || VER(>=8.0.17)}