MySQL Shell API  8.0.17
Unified development interface for MySQL Products
Methods | Properties | List of all members
Shell Class Reference

Gives access to general purpose functions and properties. More...

Methods

dict parse_uri (str uri)
 Utility function to parse a URI string. More...
 
str unparse_uri (dict options)
 SHELL_UNPARSEURI_BRIEF More...
 
str prompt (str message, dict options)
 Utility function to prompt data from the user. More...
 
None connect (ConnectionData connectionData, str password)
 Establishes the shell global session. More...
 
Session get_session ()
 Returns the global session.
 
None set_session (Session session)
 Sets the global session. More...
 
None set_current_schema (str name)
 Sets the active schema on the global session. More...
 
None log (str level, str message)
 Logs an entry to the shell's log file. More...
 
None reconnect ()
 Reconnect the global session.
 
None status ()
 Shows connection status info for the shell. More...
 
list list_credential_helpers ()
 Returns a list of strings, where each string is a name of a helper available on the current platform. More...
 
None store_credential (str url, str password)
 Stores given credential using the configured helper. More...
 
None delete_credential (str url)
 Deletes credential for the given URL using the configured helper. More...
 
None delete_all_credentials ()
 Deletes all credentials managed by the configured helper. More...
 
list list_credentials ()
 Retrieves a list of all URLs stored by the configured helper. More...
 
None enable_pager ()
 Enables pager specified in shell.options.pager for the current scripting mode. More...
 
None disable_pager ()
 Disables pager for the current scripting mode. More...
 
None register_report (str name, str type, Function report, dict description)
 Registers a new user-defined report. More...
 
UserObject create_extension_object ()
 SHELL_CREATEEXTENSIONOBJECT_BRIEF More...
 
Undefined add_extension_object_member (Object object, str name, Value member, dict definition)
 SHELL_ADDEXTENSIONOBJECTMEMBER_BRIEF More...
 
Undefined register_global (str name, Object object, dict definition)
 SHELL_REGISTERGLOBAL_BRIEF More...
 
int dump_rows (ShellBaseResult result, str format)
 SHELL_DUMPROWS_BRIEF More...
 

Properties

Options options
 Gives access to the options that modify the shell behavior.
 
Reports reports
 Gives access to built-in and user-defined reports.
 

Detailed Description

Gives access to general purpose functions and properties.

Member Function Documentation

◆ parse_uri()

dict parse_uri ( str  uri)

Utility function to parse a URI string.

Parameters
uria URI string.
Returns
A dictionary containing all the elements contained on the given URI string.

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 information about the URI format as well as the returned dictionary please look at Connection Data

◆ unparse_uri()

str unparse_uri ( dict  options)

SHELL_UNPARSEURI_BRIEF

Parameters
optionsa dictionary with the connection options.
Returns
A URI string

This function assembles a MySQL connection string which can be used in the shell or X DevAPI connectors.

◆ prompt()

str prompt ( str  message,
dict  options 
)

Utility function to prompt data from the user.

Parameters
messagea string with the message to be shown to the user.
optionsOptional dictionary with options that change the function behavior.
Returns
A string value containing the input from the user.

This function allows creating scripts that require interaction with the user to gather data.

Calling this function with no options will show the given message to the user and wait for the input. The information entered by the user will be the returned value

The options dictionary may contain the following options:

  • defaultValue: a string value to be returned if the provides no data.
  • type: a string value to define the prompt type. The type option supports the following values:
  • password: the user input will not be echoed on the screen.

◆ connect()

Session connect ( ConnectionData  connectionData,
str  password 
)

Establishes the shell global session.

Parameters
connectionDatathe connection data to be used to establish the session.
passwordOptional the password to be used when establishing the session.

This function will establish the global session with the received connection data.

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 in PEM format.
  • ssl-capath: the path to the directory that contains the X509 certificates authorities in PEM format.
  • ssl-cert: The path to the X509 certificate in PEM format.
  • ssl-key: The path to the X509 key 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: SSL Cipher to use.
  • tls-version: List of protocols permitted for secure connections
  • 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/disable compression in client/server protocol, valid values: "true", "false", "1", and "0".

Base Connection Options

  • 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.
Attention
The dbUser and dbPassword options are will be removed in a future release.

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.

Detailed description of the connection data format is available at Connection Data

The password may be included on the connectionData, the optional parameter should be used only if the connectionData does not contain it already. If both are specified the password parameter will override the password defined on the connectionData.

The connection data may be specified in the following formats:

◆ set_session()

None set_session ( Session  session)

Sets the global session.

Parameters
sessionThe session object to be used as global session.

Sets the global session using a session from a variable.

◆ set_current_schema()

None set_current_schema ( str  name)

Sets the active schema on the global session.

Parameters
nameThe name of the schema to be set as active.

Once the schema is set as active, it will be available through the db global object.

◆ log()

None log ( str  level,
str  message 
)

Logs an entry to the shell's log file.

Parameters
levelone of ERROR, WARNING, INFO, DEBUG, DEBUG2, DEBUG3 as a string
messagethe text to be logged

Only messages that have a level value equal to or lower than the active one (set via --log-level) are logged.

◆ status()

None status ( )

Shows connection status info for the shell.

This shows the same information shown by the \status command.

◆ list_credential_helpers()

list list_credential_helpers ( )

Returns a list of strings, where each string is a name of a helper available on the current platform.

Returns
A list of string with names of available credential helpers.

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.

◆ store_credential()

None store_credential ( str  url,
str  password 
)

Stores given credential using the configured helper.

Parameters
urlURL of the server for the password to be stored.
passwordOptional Password for the given URL.

Throws ArgumentError if URL has invalid form.

Throws RuntimeError in the following scenarios:

  • if configured credential helper is invalid.
  • if storing the credential fails.

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

◆ delete_credential()

None delete_credential ( str  url)

Deletes credential for the given URL using the configured helper.

Parameters
urlURL of the server to delete.

Throws ArgumentError if URL has invalid form.

Throws RuntimeError in the following scenarios:

  • if configured credential helper is invalid.
  • if deleting the credential fails.

URL needs to be in the following form: user@(host[:port]|socket).

◆ delete_all_credentials()

None delete_all_credentials ( )

Deletes all credentials managed by the configured helper.

Throws RuntimeError in the following scenarios:

  • if configured credential helper is invalid.
  • if deleting the credentials fails.

◆ list_credentials()

list list_credentials ( )

Retrieves a list of all URLs stored by the configured helper.

Throws RuntimeError in the following scenarios:

  • if configured credential helper is invalid.
  • if listing the URLs fails.
Returns
A list of URLs stored by the configured credential helper.

◆ enable_pager()

void enable_pager ( )

Enables pager specified in shell.options.pager for the current scripting mode.

All subsequent text output (except for prompts and user interaction) is going to be forwarded to the pager.

This behavior is in effect until disable_pager() is called or current scripting mode is changed.

Changing the scripting mode has the same effect as calling disable_pager().

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.

◆ disable_pager()

void disable_pager ( )

Disables pager for the current scripting mode.

The current value of shell.options.pager option is not changed by calling this method.

This method has no effect in non-interactive mode.

◆ register_report()

None register_report ( str  name,
str  type,
Function  report,
dict  description 
)

Registers a new user-defined report.

Parameters
nameName of the registered report.
typeType of the registered report, one of: 'list', 'report' or 'print'.
reportFunction to be called when the report is requested.
descriptionOptional Dictionary describing the report being registered.

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.

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.

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.

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 register_report() method will be available when Shell starts.

◆ create_extension_object()

std::shared_ptr< Extensible_object > create_extension_object ( )

SHELL_CREATEEXTENSIONOBJECT_BRIEF

An extension object is defined by adding members in it (properties and functions).

An extension object can be either added as a property of another extension object or registered as a shell global object.

An extension object is usable only when it has been registered as a global object or when it has been added into another extension object that is member in an other registered object.

◆ add_extension_object_member()

None add_extension_object_member ( Object  object,
str  name,
Value  member,
dict  definition 
)

SHELL_ADDEXTENSIONOBJECTMEMBER_BRIEF

Parameters
objectThe object to which the member will be added.
nameThe name of the member being added.
memberThe member being added.
definitionOptional dictionary with help information about the member.

The name parameter must be a valid identifier, this is, it should follow the pattern [_|a..z|A..Z]([_|a..z|A..Z|0..9])*

The member parameter can be any of:

  • An extension object
  • A function
  • Scalar values: boolean, integer, float, string
  • Array
  • Dictionary
  • None/Null

When an extension object is added as a member, a read only property will be added into the target extension object.

When a function is added as member, it will be callable on the extension object but it will not be possible to overwrite it with a new value or function.

When any of the other types are added as a member, a read/write property will be added into the target extension object, it will be possible to update the value without any restriction.

IMPORTANT: every member added into an extensible object will be available only when the object is registered, this is, registered as a global shell object, or added as a member of another object that is already registered.

The definition parameter is an optional and can be used to define additional information for the member.

The member definition accepts the following attributes:

  • brief: optional string containing a brief description of the member being added.
  • details: optional array of strings containing detailed information about the member being added.

This information will be integrated into the shell help to be available through the built in help system (\?).

When adding a function, the following attribute is also allowed on the member definition:

  • parameters: a list of parameter definitions for each parameter that the function accepts.

A parameter definition is a dictionary with the following attributes:

  • name: required, the name of the parameter, must be a valid identifier.
  • type: required, the data type of the parameter, allowed values include: string, integer, bool, float, array, dictionary, object.
  • required: a boolean value indicating whether the parameter is mandatory or optional.
  • brief: a string with a short description of the parameter.
  • details: a string array with additional details about the parameter.

The information defined on the brief and details attributes will also be added to the function help on the built in help system (\?).

If a parameter's type is 'string' the following attribute is also allowed on the parameter definition dictionary:

  • values: string array with the only values that are allowed for the parameter.

If a parameter's type is 'object' the following attributes are also allowed on the parameter definition dictionary:

  • class: string defining the class of object allowed as parameter values.
  • classes: string array defining multiple classes of objects allowed as parameter values.

The values for the class(es) properties must be a valid class exposed through the different APIs. For details use:

  • \? mysql
  • \? mysqlx
  • \? adminapi
  • \? shellapi

To get the class name for a global object or a registered extension call the print function passing as parameter the object, i.e. "Shell" is the class name for the built in shell global object:

mysql-js> print(shell)
<Shell>
mysql-js>

If a parameter's type is 'dictionary' the following attribute is also allowed on the parameter definition dictionary:

  • options: list of option definition dictionaries defining the allowed options that can be passed on the dictionary parameter.

An option definition dictionary follows exactly the same rules as the parameter definition dictionary except for one: on a parameter definition dictionary, required parameters must be defined first, option definition dictionaries do not have this restriction.

◆ register_global()

UserObject register_global ( str  name,
Object  object,
dict  definition 
)

SHELL_REGISTERGLOBAL_BRIEF

Parameters
nameThe name to be given to the registered global object.
objectThe extension object to be registered as a global object.
definitionoptional dictionary containing help information about the object.

An extension object is created with the shell.create_extension_object 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. (\?).

◆ dump_rows()

None dump_rows ( ShellBaseResult  result,
str  format 
)

SHELL_DUMPROWS_BRIEF

Parameters
resultThe resultset object to dump
formatOne of table, tabbed, vertical, json, ndjson, json/raw, json/array, json/pretty. Default is table.
Returns
The number of printed rows

This function shows a resultset object returned by a DB Session query in the same formats supported by the shell.

Note that the resultset will be consumed by the function.