You can define extensions to the base functionality of MySQL Shell Consoles in the form of reports and extension objects. Reports and extension objects can be created using JavaScript or Python, and can be used regardless of the active MySQL Shell language.
This section describes:
You can extend MySQL Shell with user-defined plugins that are loaded at startup. Plugins can be written in either JavaScript or Python, and the functions they contain are available in MySQL Shell in both JavaScript and Python modes.
MySQL Shell plugins can be used to contain functions that are registered as MySQL Shell reports. A single plugin can contain and register more than one function, and can contain a mix of reports and members of extension objects. Functions that are registered as reports or members of extension objects by a MySQL Shell plugin are available immediately when MySQL has completed startup.
A MySQL Shell plugin is a folder containing an initialization
script appropriate for the language (an
init.js or init.py
file). The initialization script is the entry point for the
plugin. A plugin can only contain code in one language, so if
you are creating an extension object with a mix of members
defined in Python and members defined in JavaScript, you must
store the members as separate language-appropriate plugins.
The plugins are automatically loaded when the MySQL Shell
starts, for this, the plugin folder must be located in the
plugins folder of the configuration path:
Windows:
C:\Users\<user>\.vscode\extensions\oracle.mysql-shell-for-vs-code-1.2.1-win32-x64\shell\lib\mysqlsh\pluginsUnix:
/home/<user>/.vscode/extensions/oracle.mysql-shell-for-vs-code-1.1.8/shell/lib/mysqlsh/plugins
When the embedded MySQL Shell starts, it reads the contents of
the Plugins folder and identifies all the
sub-folders that contain an init file. Such
init files. When MySQL Shell identifies
all the plugins, it starts loading them by executing the
init files in JavaScript or Python.
The shell global object contains the following
functions that can be used to extend MySQL Shell functionality
by registering user-defined reports or extension objects:
| User defined reports or extension objects | Description |
|---|---|
shell.registerReport(name, type, report[, description]) |
Registers a user-defined report.. |
shell.createExtensionObject() |
Creates an extension object (that later can be registered as a global object). |
shell.addExtensionObjectMember(object, name,
member[,definition]) |
Adds a new member into an extension object. |
shell.registerGlobal(name, object[, definition]) |
Registers an extension object as a shell global object. |
In the following example, we create a simple report to monitor the status of an InnoDB Cluster.
The ../plugins/monitor/init.js file
contains a backend JavaScript function that returns the cluster
object associated to a given session:
function get_cluster(session, context) {
if (session) {
try {
return dba.getCluster();
} catch (err) {
throw "A session to a cluster instance is required: " + err.message
}
} else {
throw "A session must be established to execute this " + context
}
}The backend function of the report, in JavaScript, produces the InnoDB Cluster status report when the global session is established to a InnoDB Cluster member:
// The report backend function in native JavaScript which will be
// used to generate the cluster status report.
function cluster_status(session, argv, options) {
// Gets the cluster using the backend function above
var cluster = get_cluster(session, "report")
// Prints the Cluster status
println(cluster.status())
// A report must return a list always
return {report:[]}
}The registration of the function above as a report:
shell.registerReport("idc_status", "print", cluster_status,
{brief: "Monitors the status of the cluster where the global session is connected"})