Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 37.8Mb
PDF (A4) - 37.8Mb
PDF (RPM) - 32.9Mb
HTML Download (TGZ) - 8.0Mb
HTML Download (Zip) - 8.0Mb
HTML Download (RPM) - 6.9Mb
Man Pages (TGZ) - 132.8Kb
Man Pages (Zip) - 189.4Kb
Info (Gzip) - 3.3Mb
Info (Zip) - 3.3Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  Extending MySQL  /  MySQL Services for Components and Plugins

28.3 MySQL Services for Components and Plugins

MySQL server plugins have access to server plugin services. Similarly, server components have access to component services. The following discussion uses the term plugins but also applies to components.

The plugin services interface exposes server functionality that plugins can call. It complements the plugin API and has these characteristics:

  • Services enable plugins to access code inside the server using ordinary function calls. Services are also available to user-defined functions (UDFs).

  • Services are portable and work on multiple platforms.

  • The interface includes a versioning mechanism so that service versions supported by the server can be checked at load time against plugin versions. Versioning protects against incompatibilities between the version of a service that the server provides and the version of the service expected or required by a plugin.

  • For information about plugins for testing plugin services, see Plugins for Testing Plugin Services.

The plugin services interface differs from the plugin API as follows:

  • The plugin API enables plugins to be used by the server. The calling initiative lies with the server to invoke plugins. This enables plugins to extend server functionality or register to receive notifications about server processing.

  • The plugin services interface enables plugins to call code inside the server. The calling initiative lies with plugins to invoke service functions. This enables functionality already implemented in the server to be used by many plugins; they need not individually implement it themselves.

To determine what component services exist and what functions they provide, look in the include/mysql/components directory (and its services directory) of a MySQL source distribution.

To determine what plugin services exist and what functions they provide, look in the include/mysql directory of a MySQL source distribution. The relevant files are:

  • plugin.h includes services.h, which is the umbrella header that includes all available service-specific header files.

  • Service-specific headers have names of the form service_xxx.h.

The MySQL source code contains internal documentation written using Doxygen. This documentation is useful for understanding how MySQL works from a developer perspective. The generated Doxygen content is available at http://dev.mysql.com/doc/dev/mysql-server/latest/; in particular, see http://dev.mysql.com/doc/dev/mysql-server/latest/PAGE_EXTENDING.html. It is also possible to generate this content locally from a MySQL source distribution using the instructions at Section 2.8.7, “Generating MySQL Doxygen Documentation Content”.

Available component services include the following:

  • component_sys_variable_register, component_sys_variable_unregister. Services for registering and unregistering system variables.

  • log_builtins, log_builtins_string. Services for log components. Other log_xxx services may be available, but these are in flux and should not be used.

  • mysql_service_udf_registration, mysql_service_udf_registration_aggregate: Services that enable components and plugins to register and unregister scalar and aggregate user-defined-functions (UDFs). Using these services, components and plugins can manage UDFs for themselves, without the need for CREATE FUNCTION and DROP FUNCTION statements. UDFs registered using these services are listed in the Performance Schema user_defined_functions table; see Section 25.11.16.4, “The user_defined_functions Table”.

  • mysql_string: A set of string service APIs.

  • pfs_plugin_table: A service for dynamic Performance Schema table manipulation.

Available plugin services include the following:

  • get_sysvar_source: A service that enables plugins to retrieve the source of system variable settings.

  • locking_service: A service that implements locks with three attributes: Lock namespace, lock name, and lock mode. This locking interface is available at two levels: 1) As a C language interface, callable as a plugin service from server plugins or user-defined functions; 2) At the SQL level, as a set of user-defined functions that map onto calls to the service routines. For more information, see Section 28.3.1, “The Locking Service”.

  • my_plugin_log_service: A service that enables plugins to report errors and specify error messages. The server writes the messages to its error log.

  • status_variable_registration. A service for registering status variables.

  • my_thd_scheduler: A service for plugins to select a thread scheduler.

  • mysql_keyring: A service for keyring storage. For more information, see Section 28.3.2, “The Keyring Service”.

  • mysql_password_policy: A service for password validation and strength checking.

  • plugin_registry_service: MySQL Server includes a component-based infrastructure for improving server extensibility; see Section 5.5, “MySQL Server Components”. However, MySQL plugins use an interface that predates the component interface. The plugin_registry_service enables plugins to access the component registry and its services.

  • security_context: A service that enables plugins to examine or manipulate thread security contexts. This service provides setter and getter routines to access attributes of the server Security_context class, which includes attributes such as login user and host, authenticated user and host, and client IP address.

  • thd_alloc: A memory-allocation service.

  • thd_wait: A service for plugins to report when they are going to sleep or stall.

The remainder of this section describes how a plugin uses server functionality that is available as a service.

To use a service or services from within a plugin, the plugin source file must include the plugin.h header file to access service-related information:

#include <mysql/plugin.h>

This does not represent any additional setup cost. A plugin must include that file anyway because it contains definitions and structures that every plugin needs.

To access a service, a plugin calls service functions like any other function.

To report an error that the server will write to it error log, first choose an error level. mysql/service_my_plugin_log.h defines these levels:

enum plugin_log_level
{
  MY_ERROR_LEVEL,
  MY_WARNING_LEVEL,
  MY_INFORMATION_LEVEL
};

Then invoke my_plugin_log_message():

int my_plugin_log_message(MYSQL_PLUGIN *plugin, enum plugin_log_level level,
                          const char *format, ...);

For example:

my_plugin_log_message(plugin_ptr, MY_ERROR_LEVEL, "Cannot initialize plugin");

Some services for plugins may be provided by plugins and thus are available only if the service-providing plugin is loaded. Any MySQL component that uses such a service should check whether the service is available.

When you build your plugin, use the -lmysqlservices flag at link time to link in the libmysqlservices library. For example, for CMake, put this in the top-level CMakeLists.txt file:

FIND_LIBRARY(MYSQLSERVICES_LIB mysqlservices
 PATHS "${MYSQL_SRCDIR}/libservices" NO_DEFAULT_PATH)

Put this in the CMakeLists.txt file in the directory containing the plugin source:

# the plugin needs the mysql services library for error logging
TARGET_LINK_LIBRARIES (your_plugin_library_name ${MYSQLSERVICES_LIB})

User Comments
Sign Up Login You must be logged in to post a comment.