Plugin Overview
Contents
Plugins are server components that enhance MariaDB in some way. These can be anything from new storage engines, plugins for enhancing full-text parsing, or even small enhancements, such as a plugin to get a timestamp as an integer.
Viewing Plugin Information
There are a number of ways to see which plugins are currently active. Note that there are a large number of plugins that are built-in and active by default, and which cannot be removed from the server.
The SHOW PLUGINS statement will list all active plugins.
SHOW PLUGINS; +----------------------------+----------+--------------------+---------+---------+ | Name | Status | Type | Library | License | +----------------------------+----------+--------------------+---------+---------+ ... | mysql_native_password | ACTIVE | AUTHENTICATION | NULL | GPL | | mysql_old_password | ACTIVE | AUTHENTICATION | NULL | GPL | | MRG_MyISAM | ACTIVE | STORAGE ENGINE | NULL | GPL | ... +----------------------------+----------+--------------------+---------+---------+
Plugins with the Library
listed as NULL
are built-in and cannot be uninstalled.
More detailed information can be retrieved by querying the INFORMATION_SCHEMA.PLUGINS table.
SELECT * FROM information_schema.PLUGINS\G ... *************************** 6. row *************************** PLUGIN_NAME: CSV PLUGIN_VERSION: 1.0 PLUGIN_STATUS: ACTIVE PLUGIN_TYPE: STORAGE ENGINE PLUGIN_TYPE_VERSION: 100003.0 PLUGIN_LIBRARY: NULL PLUGIN_LIBRARY_VERSION: NULL PLUGIN_AUTHOR: Brian Aker, MySQL AB PLUGIN_DESCRIPTION: CSV storage engine PLUGIN_LICENSE: GPL LOAD_OPTION: FORCE PLUGIN_MATURITY: Stable PLUGIN_AUTH_VERSION: 1.0 *************************** 7. row *************************** PLUGIN_NAME: MEMORY PLUGIN_VERSION: 1.0 PLUGIN_STATUS: ACTIVE PLUGIN_TYPE: STORAGE ENGINE PLUGIN_TYPE_VERSION: 100003.0 PLUGIN_LIBRARY: NULL PLUGIN_LIBRARY_VERSION: NULL PLUGIN_AUTHOR: MySQL AB PLUGIN_DESCRIPTION: Hash based, stored in memory, useful for temporary tables PLUGIN_LICENSE: GPL LOAD_OPTION: FORCE PLUGIN_MATURITY: Stable PLUGIN_AUTH_VERSION: 1.0 ...
Here, if the PLUGIN_LIBRARY
is NULL
, the plugin is built-in and cannot be uninstalled.
Finally, you can query the mysql.plugin table. This table only contains plugins that have been loaded with INSTALL SONAME, INSTALL PLUGIN or the mysql_plugin utility, not built-in plugins, or plugins loaded with the --plugin-load
option. It also contains much less information, just the name and library.
SELECT * FROM mysql.plugin; +------+------------+ | name | dl | +------+------------+ | PBXT | libpbxt.so | +------+------------+
Installing a Plugin
There are three primary ways to install a plugin:
- A plugin can be installed dynamically with an SQL statement.
- A plugin can be installed with a
mysqld
option, but it requires a server restart. - A plugin can be installed with the
mysql_plugin
utility, while the server is completely offline.
When you are installing a plugin, you also have to ensure that the plugin directory and minimum plugin maturity are properly configured.
Installing a Plugin Dynamically
A plugin can be installed dynamically by executing either the INSTALL SONAME
or the INSTALL PLUGIN
statement.
If a plugin is installed with one of these statements, then a record will be added to the mysql.plugins
table for the plugin. This means that the plugin will automatically be loaded every time the server restarts, unless specifically uninstalled or deactivated.
Installing a Plugin with INSTALL SONAME
You can install a plugin dynamically by executing the INSTALL SONAME
statement. INSTALL SONAME
installs all plugins from the given library. This could be required for some plugin libraries.
For example, to install all plugins in the server_audit
library (which is currently only the server_audit
audit plugin), you could execute the following:
INSTALL SONAME 'server_audit';
Installing a Plugin with INSTALL PLUGIN
You can install a plugin dynamically by executing the INSTALL PLUGIN
statement. INSTALL PLUGIN
installs a single plugin from the given library.
For example, to install the server_audit
audit plugin from the server_audit
library, you could execute the following:
INSTALL PLUGIN server_audit SONAME 'server_audit';
Installing a Plugin with Plugin Load Options
A plugin can be installed with a mysqld
option by providing either the --plugin-load-add
or the --plugin-load
option.
If a plugin is installed with one of these options, then a record will not be added to the mysql.plugins
table for the plugin. This means that if the server is restarted without the same option set, then the plugin will not automatically be loaded.
Installing a Plugin with --plugin-load-add
You can install a plugin with the --plugin-load-add
option by specifying the option as a command-line argument to mysqld
or by specifying the option in a relevant server option group in an option file.
The --plugin-load-add
option uses the following format:
- Plugins can be specified in the format
name=library
, wherename
is the plugin name andlibrary
is the plugin library. This format installs a single plugin from the given library. - Plugins can also be specified in the format
library
, wherelibrary
is the plugin library. This format installs all plugins from the given library. - Multiple plugins can be specified by separating them with semicolons.
For example, to install all plugins in the server_audit
library (which is currently only the server_audit
audit plugin) and also the ed25519
authentication plugin from the auth_ed25519
library, you could set the option to the following values on the command-line:
$ mysqld --user=mysql --plugin-load-add='server_audit' --plugin-load-add='ed25519=auth_ed25519'
You could also set the option to the same values in an option file:
[mariadb] ... plugin_load_add = server_audit plugin_load_add = ed25519=auth_ed25519
Special care must be taken when specifying both the --plugin-load
option and the --plugin-load-add
option together. The --plugin-load
option resets the plugin load list, and this can cause unexpected problems if you are not aware. The --plugin-load-add
option does not reset the plugin load list, so it is much safer to use. See Specifying Multiple Plugin Load Options for more information.
Installing a Plugin with --plugin-load
You can install a plugin with the --plugin-load
option by specifying the option as a command-line argument to mysqld
or by specifying the option in a relevant server option group in an option file.
The --plugin-load
option uses the following format:
- Plugins can be specified in the format
name=library
, wherename
is the plugin name andlibrary
is the plugin library. This format installs a single plugin from the given library. - Plugins can also be specified in the format
library
, wherelibrary
is the plugin library. This format installs all plugins from the given library. - Multiple plugins can be specified by separating them with semicolons.
For example, to install all plugins in the server_audit
library (which is currently only the server_audit
audit plugin) and also the ed25519
authentication plugin from the auth_ed25519
library, you could set the option to the following values on the command-line:
$ mysqld --user=mysql --plugin-load='server_audit;ed25519=auth_ed25519'
You could also set the option to the same values in an option file:
[mariadb] ... plugin_load = server_audit;ed25519=auth_ed25519
Special care must be taken when specifying the --plugin-load
option multiple times, or when specifying both the --plugin-load
option and the --plugin-load-add
option together. The --plugin-load
option resets the plugin load list, and this can cause unexpected problems if you are not aware. The --plugin-load-add
option does not reset the plugin load list, so it is much safer to use. See Specifying Multiple Plugin Load Options for more information.
Specifying Multiple Plugin Load Options
Special care must be taken when specifying the --plugin-load
option multiple times, or when specifying both the --plugin-load
option and the --plugin-load-add
option. The --plugin-load
option resets the plugin load list, and this can cause unexpected problems if you are not aware. The --plugin-load-add
option does not reset the plugin load list, so it is much safer to use.
This can have the following consequences:
- If the
--plugin-load
option is specified multiple times, then only the last instance will have any effect. For example, in the following case, the first instance of the option is reset:
[mariadb] ... plugin_load = server_audit plugin_load = ed25519=auth_ed25519
- If the
--plugin-load
option is specified after the--plugin-load-add
option, then it will also reset the changes made by that option. For example, in the following case, the--plugin-load-add
option does not do anything, because the subsequent--plugin-load
option resets the plugin load list:
[mariadb] ... plugin_load_add = server_audit plugin_load = ed25519=auth_ed25519
- In contrast, if the
--plugin-load
option is specified before the--plugin-load-add
option, then it will work fine, because the--plugin-load-add
option does not reset the plugin load list. For example, in the following case, both plugins are properly loaded:
[mariadb] ... plugin_load = server_audit plugin_load_add = ed25519=auth_ed25519
Installing a Plugin with mysql_plugin
A plugin can be installed with the mysql_plugin
utility if the server is completely offline.
The syntax is:
mysql_plugin [options] <plugin> ENABLE|DISABLE
For example, to install the server_audit
audit plugin, you could execute the following:
mysql_plugin server_audit ENABLE
If a plugin is installed with this utility, then a record will be added to the mysql.plugins
table for the plugin. This means that the plugin will automatically be loaded every time the server restarts, unless specifically uninstalled or deactivated.
Configuring the Plugin Directory
When a plugin is being installed, the server looks for the plugin's shared library in the server's plugin directory. This directory is configured by the plugin_dir
system variable. This can be specified as a command-line argument to mysqld
or it can be specified in a relevant server option group in an option file. For example:
[mariadb] ... plugin_dir = /usr/lib64/mysql/plugin
Configuring the Minimum Plugin Maturity
When a plugin is being installed, the server compares the plugin's maturity level against the server's minimum allowed plugin maturity. This can help prevent users from using unstable plugins on production servers. This minimum plugin maturity is configured by the plugin_maturity
system variable. This can be specified as a command-line argument to mysqld
or it can be specified in a relevant server option group in an option file. For example:
[mariadb] ... plugin_maturity = stable
Controlling Plugin Activation
Plugins that are listed in the mysql.plugin table, or listed as a --plugin-load
option, will by default be loaded. This behavior can be changed, with --plugin-name options.
Option | Description |
---|---|
--plugin_name=OFF | Disables the plugin without removing it from the mysql.plugins table. |
--plugin_name[=ON] | Enables the plugin. If the plugin cannot initialize, the server will run with the plugin disabled. |
--plugin_name=FORCE | Enables the plugin, but if plugin cannot initialize, the server will not start. |
--plugin_name=FORCE_PLUS_PERMANENT | Enables the plugin, but if plugin cannot initialize, the server will not start. In addition, the plugin cannot be uninstalled while the server is running. Added in MariaDB 5.5. |
The plugin status is listed in the PLUGIN_STATUS field of the INFORMATION_SCHEMA.PLUGINS table.
Uninstalling Plugins
Plugins that are found in the mysql.plugin table, that is those that were installed with INSTALL SONAME, INSTALL PLUGIN or mysql_plugin can be uninstalled in one of two ways:
- The UNINSTALL SONAME or the UNINSTALL PLUGIN statement while the server is running
- With mysql_plugin while the server is offline.
Plugins that were enabled as a --plugin-load
option do not need to be uninstalled. If --plugin-load
is omitted the next time the server starts, or the plugin is not listed as one of the --plugin-load
entries, the plugin will not be loaded.
UNINSTALL PLUGIN uninstalls a single installed plugin, while UNINSTALL SONAME uninstalls all plugins belonging to a given library.