Extension Objects

Extension Objects

The MySQL Shell allows for an extension of its base functionality by using special objects called Extension Objects.

Once an extension object has been created it is possible to attach different type of object members such as:

• Functions
• Properties
• Other extension objects

Once an extension object has been fully defined it can be registered as a regular Global Object. This way the object and its members will be available in the scripting languages the MySQL Shell supports, just as any other global object such as shell, util, etc.

Extending the MySQL Shell with extension objects follows this pattern:

• Creation of a new extension object.
• Addition of members (properties, functions)
• Registration of the object

Creation of a new extension object is done through the shell.createExtensionObject function.

Members can be attached to the extension object by calling the shell.addExtensionObjectMember function.

Registration of an extension object as a global object can be done by calling the shell.registerGlobal function.

Alternatively, the extension object can be added as a member of another extension object by calling the shell.addExtensionObjectMember function.

You can get more details on these functions by executing:

• \? createExtensionObject
• \? addExtensionObjectMember
• \? registerGlobal

Naming Convention

The core MySQL Shell APIs follow a specific naming convention for object members. Extension objects should follow the same naming convention for consistency reasons.

• JavaScript members use camelCaseNaming
• Python members use snake_case_naming

To simplify this across languages, it is important to use camelCaseNaming when specifying the 'name' parameter of the shell.addExtensionObjectMember function.

The MySQL Shell will then automatically handle the snake_case_naming for that member when it is switched to Python mode.

NOTE: the naming convention is only applicable for extension object members. However, when a global object is registered, the name used to register that object will be exactly the same in both JavaScript and Python modes.

Example:

# Sample python function to be added to an extension object
def some_python_function():
  print ("Hello world!")
 
# The extension object is created
obj = shell.create_extension_object()
 
# The sample function is added as member
# NOTE: The member name using camelCaseNaming
shell.add_extension_object_member(obj, "mySampleFunction", some_python_function)
 
# The extension object is registered
shell.register_global("myCustomObject", obj)

Calling in JavaScript:

// Member is available using camelCaseNaming
mysql-js> myCustomObject.mySampleFunction()
Hello World!
mysql-js>

Calling in Python:

# Member is available using snake_case_naming
mysql-py> myCustomObject.my_sample_function()
Hello World!
mysql-py>

Automatic Loading of Extension Objects

The MySQL Shell startup logic scans for extension scripts at the following paths:

• Windows: %AppData%/MySQL/mysqlsh/init.d
• Others ~/.mysqlsh/init.d

An extension script is either a JavaScript (*.js) or Python (*.py) file which will be automatically processed when the MySQL Shell starts.

These scripts can be used to define extension objects so there are available right away when the MySQL Shell starts.