Documentation Home
MySQL Shell for VS Code


MySQL Shell for VS Code  /  MySQL Shell Consoles  /  Extending MySQL Shell Consoles

Pre-General Availability: 2024-10-04

5.10 Extending MySQL Shell Consoles

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:

MySQL Shell plugins

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\plugins

  • Unix: /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.

Extending MySQL Shell with plugins

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.

Create a report using a MySQL Shell plugin

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"})