MySQL Shell Plugins – Introduction

The MySQL Shell 8.0.17 introduces a novel way of extending its base functionality through plugins, which are JavaScript or Python scripts that allow the user to:

  • Register reports that can be used in monitoring tasks through the \show and \watch Shell Commands.
  • Create and register new global objects with custom functionality defined by the user.

The Plugin Structure

At its simplest form, a plugin is just a folder containing a plugin registration file which will be executed by the Shell when it starts.

The plugin registration file is a file named init.js for JavaScript plugins and init.py for Python plugins (Will call it the init file for the rest of this blog post).

The plugins are automatically loaded when the Shell starts, for this, the plugin folder must be located at the plugins folder of the user configuration path:

  • Windows: %appdata%/MySQL/mysqlsh/plugins
  • Others: ~/.mysqlsh/plugins

When the Shell starts, it will traverse the content of the plugins directory identifying all the folders that contain an init file. Such init files are the plugins that will be loaded. Once all the plugins are identified, it will start loading them by executing the init files in the corresponding language context.

Extending the Shell with Plugins

The shell global object contains the following functions that can be used to extend the shell functionality by registering user-defined reports or extension objects:

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

When the init files are executed, some of the Shell global objects are available out of the box, this is, they can be used right away on the init file. These objects include:

  • The shell object.
  • The dba object.
  • The mysql  module.
  • The mysqlx module.

By using the functions of the shell object listed above is how the init file can extend the Shell functionality.

Adding a report using a Shell plugin

The reporting feature is available since 8.0.16. On this section, we will create a simple report to monitor the status of an InnoDB cluster.

The .mysqlsh/plugins/monitor/init.js file contains the following:

A backend function that will return the cluster object associated to a given session:

The report backend function in native JavaScript which produces the cluster status report when the global session is established to a cluster member:

The registration of the function above as a report, to make it usable with the \show and \watch Shell commands:

When the Shell is started, the plugin will be loaded and the new status report will be available for execution with the \show and \watch commands:

Adding a new global object using a Shell plugin

Extending the Shell base functionality becomes easy through the Shell extension objects. In general, the process of extending the shell includes:

  • Creating the extension object.
  • Adding functionality to the extension object.
  • Registering the extension object.

When working with InnoDB Cluster we have the cluster object which already provides lots of features, examples of these features include the describe() and satus() functions. Lets say we want to addres a specific use case and we need a function that retrieves the list of members of the InnoDB Cluster.

Let’s define a new object called idc which will work with the InnoDB cluster associated to the global session and will have a function getMembers which will return the list of the cluster members without any additional information.

Let’s update our existing plugin by adding the code needed to achieve our objective.

This is the backend function that will provide the functionality we want.

Now we create the extension object, add the function into it and register it as a global:

When the Shell is started, the plugin will be loaded and the new idc global object will be available and with it, the functionality that has been added into it:

Help Integration

Even the main aspect of the shell extensions is about allowing the user to integrate additional functionality into the Shell, it is important to provide documentation about it. For that reason, the three functions used to register new functionality allow defining help through the following options:

  • brief: Should be a short description of the report/object/function being registered.
  • details: it’s an array of strings with detailed information about the report/function/object being registered. Each string on this array will be a separate paragraph on the displayed help.

Stay Tuned!

Additional blog post will be published about this subject, including:

  • MySQL Shell Plugins – Data Validation: which guides you through the different data validation options when registering functions into an extension object.
  • MySQL Shell Plugins – Plugin Groups: which explains how to organize your plugins in a way that they are contained in a single global object.
  • MySQL Shell Plugins – A Python Approach: which explains how to combine python modules with the MySQL Shell Plugins to create complex plugins.

Resources

For details about the MySQL Shell Plugins please take a look at the MySQL Shell User Guide.

Don’t forget to download it and give it a try, your feedback is very welcome!

You can reach us at #shell channel in https://mysqlcommunity.slack.com/

About Rene Ramirez

Juan Rene Ramirez Monarrez (a.k.a. rennox) is a Software Engineer with a master degree in Computer Science residing in Mexico. He started his career at IBM almost 20 years ago in application development, had a pass on Automation at Freescale Semiconductor (now MXP) and landed at the MySQL world 8 years ago. At MySQL he started working at the Workbench team and now is leading the efforts to make the MySQL Shell the client by excellence for different MySQL products.

Leave a Reply