4.1 Types of Plugins

The plugin API enables creation of plugins that implement several capabilities:

• Loadable functions (UDFs)

• Storage engines

• Full-text parsers

• Daemons

• INFORMATION_SCHEMA tables

• Semisynchronous replication

• Auditing

• Authentication

• Password validation and strength checking

The following sections provide an overview of these plugin types.

• Loadable Function (UDF) Plugins

• Storage Engine Plugins

• Full-Text Parser Plugins

• Daemon Plugins

• INFORMATION_SCHEMA Plugins

• Semisynchronous Replication Plugins

• Audit Plugins

• Authentication Plugins

• Password-Validation Plugins

Loadable Function (UDF) Plugins

Loadable functions can be included in plugin library files and installed on the server.

For information about using the MySQL interface for loadable functions, see Section 6.2, “Adding a Loadable Function”. The steps to compile and install loadable function plugins are described in Loadable Function Compiling and Installing.

Note

Loadable functions previously were known as user-defined functions (UDFs). That terminology was something of a misnomer because “user-defined” also can apply to stored functions written using SQL and native functions added by modifying the server source code.

Storage Engine Plugins

The pluggable storage engine architecture used by MySQL Server enables storage engines to be written as plugins and loaded into and unloaded from a running server. For a description of this architecture, see Overview of MySQL Storage Engine Architecture.

For information on how to use the plugin API to write storage engines, see MySQL Internals: Writing a Custom Storage Engine.

Full-Text Parser Plugins

MySQL has a built-in parser that it uses by default for full-text operations (parsing text to be indexed, or parsing a query string to determine the terms to be used for a search). For full-text processing, “parsing” means extracting words from text or a query string based on rules that define which character sequences make up a word and where word boundaries lie.

When parsing for indexing purposes, the parser passes each word to the server, which adds it to a full-text index. When parsing a query string, the parser passes each word to the server, which accumulates the words for use in a search.

The parsing properties of the built-in full-text parser are described in Full-Text Search Functions. These properties include rules for determining how to extract words from text. The parser is influenced by certain system variables such as ft_min_word_len and ft_max_word_len that cause words shorter or longer to be excluded, and by the stopword list that identifies common words to be ignored.

The plugin API enables you to provide a full-text parser of your own so that you have control over the basic duties of a parser. A parser plugin can operate in either of two roles:

• The plugin can replace the built-in parser. In this role, the plugin reads the input to be parsed, splits it up into words, and passes the words to the server (either for indexing or for word accumulation).

  One reason to use a parser this way is that you need to use different rules from those of the built-in parser for determining how to split up input into words. For example, the built-in parser considers the text “case-sensitive” to consist of two words “case” and “sensitive,” whereas an application might need to treat the text as a single word.

• The plugin can act in conjunction with the built-in parser by serving as a front end for it. In this role, the plugin extracts text from the input and passes the text to the parser, which splits up the text into words using its normal parsing rules. In particular, this parsing will be affected by the ft_xxx system variables and the stopword list.

  One reason to use a parser this way is that you need to index content such as PDF documents, XML documents, or .doc files. The built-in parser is not intended for those types of input but a plugin can pull out the text from these input sources and pass it to the built-in parser.

It is also possible for a parser plugin to operate in both roles. That is, it could extract text from noncleartext input (the front end role), and also parse the text into words (thus replacing the built-in parser).

A full-text plugin is associated with full-text indexes on a per-index basis. That is, when you install a parser plugin initially, that does not cause it to be used for any full-text operations. It simply becomes available. For example, a full-text parser plugin becomes available to be named in a WITH PARSER clause when creating individual FULLTEXT indexes. To create such an index at table-creation time, do this:

CREATE TABLE t
(
  doc CHAR(255),
  FULLTEXT INDEX (doc) WITH PARSER my_parser
) ENGINE=MyISAM;

Or you can add the index after the table has been created:

ALTER TABLE t ADD FULLTEXT INDEX (doc) WITH PARSER my_parser;

The only SQL change for associating the parser with the index is the WITH PARSER clause. Searches are specified as before, with no changes needed for queries.

When you associate a parser plugin with a FULLTEXT index, the plugin is required for using the index. If the parser plugin is dropped, any index associated with it becomes unusable. Any attempt to use a table for which a plugin is not available results in an error, although DROP TABLE is still possible.

For more information about full-text plugins, see Section 4.4.4, “Writing Full-Text Parser Plugins”. MySQL 5.6 only supports full-text plugins with MyISAM.

Daemon Plugins

A daemon plugin is a simple type of plugin used for code that should be run by the server but that does not communicate with it. MySQL distributions include an example daemon plugin that writes periodic heartbeat messages to a file.

For more information about daemon plugins, see Section 4.4.5, “Writing Daemon Plugins”.

INFORMATION_SCHEMA Plugins

INFORMATION_SCHEMA plugins enable the creation of tables containing server metadata that are exposed to users through the INFORMATION_SCHEMA database. For example, InnoDB uses INFORMATION_SCHEMA plugins to provide tables that contain information about current transactions and locks.

For more information about INFORMATION_SCHEMA plugins, see Section 4.4.6, “Writing INFORMATION_SCHEMA Plugins”.

Semisynchronous Replication Plugins

MySQL replication is asynchronous by default. With semisynchronous replication, a commit performed on the source side blocks before returning to the session that performed the transaction until at least one replica acknowledges that it has received and logged the events for the transaction. Semisynchronous replication is implemented through complementary source and client plugins. See Semisynchronous Replication.

For more information about semisynchronous replication plugins, see Section 4.4.7, “Writing Semisynchronous Replication Plugins”.

Audit Plugins

The MySQL server provides a pluggable audit interface that enables information about server operations to be reported to interested parties. Audit notification occurs for these operations (although the interface is general and the server could be modified to report others):

• Write a message to the general query log (if the log is enabled)

• Write a message to the error log

• Send a query result to a client

Audit plugins may register with the audit interface to receive notification about server operations. When an auditable event occurs within the server, the server determines whether notification is needed. For each registered audit plugin, the server checks the event against those event classes in which the plugin is interested and passes the event to the plugin if there is a match.

This interface enables audit plugins to receive notifications only about operations in event classes they consider significant and to ignore others. The interface provides for categorization of operations into event classes and further division into event subclasses within each class.

When an audit plugin is notified of an auditable event, it receives a pointer to the current THD structure and a pointer to a structure that contains information about the event. The plugin can examine the event and perform whatever auditing actions are appropriate. For example, the plugin can see what statement produced a result set or was logged, the number of rows in a result, who the current user was for an operation, or the error code for failed operations.

For more information about audit plugins, see Section 4.4.8, “Writing Audit Plugins”.

Authentication Plugins

MySQL supports pluggable authentication. Authentication plugins exist on both the server and client sides. Plugins on the server side implement authentication methods for use by clients when they connect to the server. A plugin on the client side communicates with a server-side plugin to provide the authentication information that it requires. A client-side plugin may interact with the user, performing tasks such as soliciting a password or other authentication credentials to be sent to the server. See Pluggable Authentication.

Pluggable authentication also enables proxy user capability, in which one user takes the identity of another user. A server-side authentication plugin can return to the server the name of the user whose identity the connecting user should have. See Proxy Users.

For more information about authentication plugins, see Section 4.4.9, “Writing Authentication Plugins”.

Password-Validation Plugins

The server provides an interface for writing plugins that test passwords. Such a plugin implements two capabilities:

• Rejection of too-weak passwords in statements that assign passwords (such as CREATE USER, GRANT, and SET PASSWORD statements), and passwords given as arguments to the PASSWORD() and OLD_PASSWORD() functions.

• Assessing the strength of potential passwords for the VALIDATE_PASSWORD_STRENGTH() SQL function.

For information about writing this type of plugin, see Section 4.4.10, “Writing Password-Validation Plugins”.