MySQL Forge

Resources for the MySQL Community

Category: GUITools

MySQL Workbench Plugins

MySQL Workbench supports scripting and writing plugins to extend its functionality. Currently you can write them in the Lua language, although support for Python and others will be added.

Contents 1 Plugin Installation 2 Writing Plugins 2.1 Plugin Function 2.2 Plugin Registration 2.3 Lua Plugins 2.3.1 Registration 2.4 Python Plugins 3 Workbench Object Structure 3.1 Application Object Tree 3.2 Object Types

[edit] Plugin Installation

[edit] Writing Plugins

Workbench plugins are implemented as GRT modules that follow certain conventions. They are implemented as a file (a .lua file, .py file, .class file etc depending on the language you write it in) that must contain at least 3 functions:

• getModuleInfo(), which tells the GRT that the file is a module;
• getPluginInfo(), which tells the Workbench that the module is a function and registers what plugin functionality it offers;
• the actual plugin function(s).

[edit] Plugin Function

Plugin functions take one argument, which is a list of objects the plugin should act upon. Workbench passes the list of objects currently selected, but if there's no selection, all objects in the current view are given to the plugin. The objects in the list are figure objects, not database objects. For accessing the associated database objects, access the appropriate field (eg: tableFigure.table.columns). See the #Workbench Object Structure section for more information about what objects the Workbench uses to internally represent models.

[edit] Plugin Registration

To get the list of available plugins the Workbench checks all available modules at startup time that extend the PluginInfo interface.

The registration function getPluginInfo() must provide the following meta-information:

• name of the plugins;
• caption/label for plugins;
• description text;
• type of object they can accept and act on;
• a category which will be used to organize the plugin in a menu structure.

This information is stored in an object of type base.Plugin. A list of these objects (one for each plugin function) has to be returned by getPluginInfo().

See the section for each language for an example of how this function should look like.

[edit] Lua Plugins

Visit the quick Lua intro if you're not familiar with the language.

[edit] Registration

In a Lua module, the getModuleInfo() function would look like this.

function getModuleInfo()
  local moduleInfo= {
    name= "MyPlugins", 
    functions= {
      "getPluginInfo::",
      "myPlugin::"
    }, 
    extends= "PluginInfo"
  }
  return moduleInfo
end

For registering a Plugin, you must implement something like this:

function getPluginInfo(args)
  -- create list
  local pluginList= grtV.newList("dict", "base.Plugin")
  local plugin

  -- create a new base.Plugin object and set its values
  -- to provide information about the plugin and add it to the list
  plugin= grtV.newObj("base.Plugin", "myPlugin", 
    "plugin://com.mysql.grt.base.Plugin.myPlugin", "")
  plugin.caption= _("My New Plugin")
  plugin.description= _("A table plugin that changes the figure color " ..
    "if the table has a foreign key")
  plugin.groupPath= "Table/Utilites"
  plugin.moduleName= "myPlugins"
  plugin.moduleFunctionName= "myPluginSetTableColorOnFk"
  plugin.categories= {"database", "table", "foreign key"}
  plugin.objectStructNames= {"db.workbench.TableElement"}
  plugin.singleArgument= 1
  grtV.insert(pluginList, plugin)


  -- repeated for each plugin
  plugin= grtV.newObj("base.Plugin", ...
  grtV.insert(pluginList, plugin)
  ...

  -- return the list of plugin information
  return grt.success(pluginList)
end

After creating the object and setting the caption and description of the plugin the groupPath is set. It specifies where the plugin will appear in the Plugin Menus. Further, the moduleName and moduleFunctionName are set to where the actual implementation is located. The categories property holds a list of keywords that are used in e.g. search for plugins.

To define the object types the plugin can work with the objectStructNames list is set. For a plugin that can operate on tables and views this would be set to {"db.workbench.TableElement", "db.workbench.View"}.

[edit] Python Plugins

[edit] Workbench Object Structure

The best way to explore Workbench objects is from the Workbench GRT shell. Press F4 to bring it up. The main textview can be used to issue Lua (or Python) commands while the sidebar will display the application object tree, list of structures and list of modules available. For writing plugins, the object tree and list of structures are of interest.

[edit] Application Object Tree

The following is a description of the main nodes in the object tree:

• /app Application data such as plugin registry, list of editors and options.
  • /options Contains some default options that are used by Workbench for various things.
• /rdbmsMgmt Internal registry of supported RDBMS modules, known datatypes etc.
• /workbench This node is what you will find the most interesting.
  • /catalog The (physical) database catalog for the current model. Contains the list of tables, stored procedures etc.
  • /model Information about the Workbench model in the current document. Contains list of views, layers, graphical elements etc.

[edit] Object Types

There are basically two types of relevant objects in Workbench for working with in plugins, figure objects and database objects. Figure objects are 1:1 related to graphic elements you place and manipulate on your model. Database objects are how information about database schema objects are represented internally.

Here is a partial list of standard figure object types supported in MySQL Workbench:

• Database Objects Represented in Canvas
  • MySQL Tables
  • MySQL Table Relationships
  • MySQL Routine Groups (for Stored Procedures and Functions)
  • MySQL Views

• Additional/Decorative Objects
  • Notes
  • Layers