MySQL Shell API  8.0.21
Unified development interface for MySQL Products
Modules | Classes | Functions
ShellAPI

Modules

 mysql
 Encloses the functions and classes available to interact with a MySQL Server using the traditional MySQL Protocol.
 
 util
 Global object that groups miscellaneous tools like upgrade checker and JSON import.
 

Classes

class  ClassicResult
 
class  ClassicSession
 Enables interaction with a MySQL Server using the MySQL Protocol. More...
 
class  Os
 Gives access to functions which allow to interact with the operating system. More...
 
class  Path
 Gives access to path-related functions. More...
 
class  Shell
 Gives access to general purpose functions and properties. More...
 
class  Options
 
class  Reports
 Gives access to built-in and user-defined reports. More...
 
class  Sys
 Gives access to system specific parameters. More...
 
class  DatabaseObject
 Provides base functionality for database objects. More...
 
class  Column
 Represents the a Column definition on a result. More...
 
class  Row
 Represents the a Row in a Result.When a row object is created, its fields are exposed as properties of the Row object if two conditions are met:
  • Its name must be a valid identifier: [_a-zA-Z][_a-zA-Z0-9]*
  • Its name must be different from names of the members of this object.

In the case a field does not met these conditions, it must be retrieved through the this function. More...

 

Functions

Array dir (Object object)
 Returns a list of enumerable properties on the target object. More...
 
Any require (String module_name_or_path)
 Loads the specified JavaScript module. More...
 

Detailed Description

Shell API and backward compatibility API for MySQL Servers not supporting the X DevAPI.

Function Documentation

◆ dir()

Array dir ( Object  object)

Returns a list of enumerable properties on the target object.

Parameters
objectThe object whose properties will be listed.
Returns
The list of enumerable properties on the object.

Traverses the object retrieving its enumerable properties. The content of the returned list will depend on the object:

  • For a dictionary, returns the list of keys.
  • For an API object, returns the list of members.

Behavior of the function passing other types of objects is undefined and also unsupported.

◆ require()

Any require ( String  module_name_or_path)

Loads the specified JavaScript module.

Parameters
module_name_or_pathThe name or a path to the module to be loaded.
Returns
The exported content of the loaded module.

The module_name_or_path parameter can be either a name of the built-in module (i.e. mysql or mysqlx) or a path to the JavaScript module on the local file system. The local module is searched for in the following folders:

  • if module_name_or_path begins with either './' or '../' characters, use the folder which contains the JavaScipt file or module which is currently being executed or the current working directory if there is no such file or module (i.e. shell is running in interactive mode),
  • folders listed in the sys.path variable.

The file containing the module to be loaded is located by iterating through these folders, for each folder path:

  • append module_name_or_path, if such file exists, use it,
  • append module_name_or_path, append '.js' extension, if such file exists, use it,
  • append module_name_or_path, if such folder exists, append 'init.js' file name, if such file exists, use it.

The loaded module has access to the following variables:

  • exports - an empty object, module should use it to export its functionalities; this is the value returned from the require() function,
  • module - a module object, contains the exports object described above; can be used to i.e. change the type of exports or store module-specific data,
  • __filename - absolute path to the module file,
  • __dirname - absolute path to the directory containing the module file.

Each module is loaded only once, any subsequent call to require() which would use the same module will return a cached value instead.

If two modules form a cycle (try to load each other using the require() function), one of them is going to receive an unfinished copy of the other ones exports object.

Here is a sample module called test.js which stores some data in the module object and exports a function callme():

module.counter = 0;
exports.callme = function() {
const plural = ++module.counter > 1 ? 's' : '';
println(`I was called $(module.counter) time$(plural).`);
};

If placed in the current working directory, it can be used in shell as follows:

mysql-js> var test = require('./test');
mysql-js> test.callme();
I was called 1 time.
mysql-js> test.callme();
I was called 2 times.
mysql-js> test.callme();
I was called 3 times.
Exceptions
TypeErrorin the following scenarios:
  • if module_name_or_path is not a string.
Errorin the following scenarios:
  • if module_name_or_path is empty,
  • if module_name_or_path contains a backslash character,
  • if module_name_or_path is an absolute path,
  • if local module could not be found,
  • if local module could not be loaded.