MySQL Shell 8.0
To create a new extension object to provide one or more functions,
data types, or further extension objects, use the built-in
shell.createExtensionObject() function in
JavaScript or shell.create_extension_object()
in Python:
shell.createExtensionObject()
To add members to the extension object, use the built-in
shell.addExtensionObjectMember() function in
JavaScript or
shell.add_extension_object_member() in Python:
shell.addExtensionObjectMember(object, name, member[, definition])
Where:
object is the extension object where the
new member is to be added.
name is the name of the new member. The
name must be a valid scripting identifier, so the first
character must be a letter or underscore character, followed
by any number of letters, numbers, or underscore characters.
The name must be unique among the members that have already
been added to the same extension object, and if the member is
a function, the name does not have to match the name of the
defined function. The name should preferably be specified in
camel case, even if you are using Python to define and add the
member. Specifying the member name in camel case enables
MySQL Shell to automatically enforce naming conventions.
MySQL Shell makes the member available in JavaScript mode
using camel case, and in Python mode using snake case.
member is the value of the new member,
which can be any of the following:
A supported basic data type. The supported data types are “none” or “null”, “bool”, “number” (integer or floating point), “string”, “array”, and “dictionary”.
A JavaScript or Python function. You can use native code in the body of functions that are added as members to an extension object, provided that the interface (parameters and return values) is limited to the supported data types in Table 10.1, “Supported data type pairs for extension objects”. The use of other data types in the interface can lead to undefined behavior.
Another extension object.
definition is an optional dictionary that
can contain help information for the member, and also if the
member is a function, a list of parameters that the function
receives. Help information is defined using the following
attributes:
brief is a brief description of the
member.
details is a detailed description of
the member, provided as a list of strings. This is
provided when you use the MySQL Shell
\help command.
Parameters for a function are defined using the following attribute:
parameters is a list of dictionaries
describing each parameter that the function receives. Each
dictionary describes one parameter, and can contain the
following keys:
name (string, required): The name
of the parameter.
type (string, required): The data
type of the parameter, one of “string”,
“integer”, “bool”,
“float”, “array”,
“dictionary”, or “object”.
If the type is “object”, the
class or classes
key can also be used. If the type is
“string”, the values
key can also be used. If the type is
“dictionary”, the
options key can also be used.
class (string, optional, allowed
when data type is “object”): Defines the
object type that is allowed as a parameter.
classes (list of strings, optional,
allowed when data type is “object”): A
list of classes defining the object types that are
allowed as a parameter. The supported object types for
class and
classes are those that are exposed
by the MySQL Shell APIs, for example
Session,
ClassicSession,
Table, or
Collection. An error is raised if
an object type is passed to the function that is not
in this list.
values (list of strings, optional,
allowed when data type is “string”): A
list of values that are valid for the parameter. An
error is raised if a value is passed to the function
that is not in this list.
options (list of options, optional,
allowed when data type is “dictionary”):
A list of options that are allowed for the parameter.
Options use the same definition structure as the
parameters, with the exception that if
required is not specified for an
option, it defaults to false.
MySQL Shell validates the options specified by the
end user and raises an error if an option is passed to
the function that is not in this list. In MySQL Shell
8.0.17 through 8.0.19, this parameter is required when
the data type is “dictionary”, but from
MySQL Shell 8.0.20 it is optional. If you create a
dictionary with no list of options, any options that
the end user specifies for the dictionary are passed
directly through to the function by MySQL Shell with
no validation.
required (bool, optional): Whether
the parameter is required. If
required is not specified for a
parameter, it defaults to true.
brief (string, optional): A short
description of the parameter to be provided as help
information.
details (list of strings,
optional): A detailed description of the parameter to
be provided as help information.
An extension object is considered to be under construction until it has been registered as a MySQL Shell global object, or added as a member to another extension object that is registered as a MySQL Shell global object. An error is returned if you attempt to use an extension object in MySQL Shell when it has not yet been registered.
An extension object can contain a mix of members defined in Python and members defined in JavaScript. MySQL Shell manages the transfer of data from one language to the other as parameters and return values. Table 10.1, “Supported data type pairs for extension objects” shows the data types that MySQL Shell supports when transferring data between languages, and the pairs that are used as representations of each other:
Table 10.1 Supported data type pairs for extension objects
| JavaScript | Python |
|---|---|
| Boolean | Boolean |
| String | String |
| Integer | Long |
| Number | Float |
| Null | None |
| Array | List |
| Map | Dictionary |
An extension object is literally the same object in both languages.