Server plugins must be loaded into the server before they can be used. MySQL supports plugin loading at server startup and runtime. It is also possible to control the activation state of loaded plugins at startup, and to unload them at runtime.
While a plugin is loaded, information about it is available as described in Section 5.6.2, “Obtaining Server Plugin Information”.
Before a server plugin can be used, it must be installed using
one of the following methods. In the descriptions,
plugin_name stands for a plugin name
A built-in plugin is known by the server automatically. By
default, the server enables the plugin at startup. Some built-in
plugins permit this to be changed with the
Plugins Registered in the mysql.plugin System Table
mysql.plugin system table serves as a
registry of plugins (other than built-in plugins, which need not
be registered). During the normal startup sequence, the server
loads plugins registered in the table. By default, for a plugin
loaded from the
mysql.plugin table, the
server also enables the plugin. This can be changed with the
If the server is started with the
plugins registered in the
are not loaded and are unavailable.
Plugins Named with Command-Line Options
A plugin located in a plugin library file can be loaded at
server startup with the
Normally, for a plugin loaded at startup, the server also
enables the plugin. This can be changed with the
--plugin-load-add options load
plugins after built-in plugins and storage engines have
initialized during the server startup sequence. The
--early-plugin-load option is
used to load plugins that must be available prior to
initialization of built-in plugins and storage engines.
The value of each plugin-loading option is a semicolon-separated
plugin_library is the
name of a library file that contains plugin code, and each
name is the name of a plugin to load.
If a plugin library is named without any preceding plugin name,
the server loads all plugins in the library. With a preceding
plugin name, the server loads only the named plugin from the
library. The server looks for plugin library files in the
directory named by the
plugin_dir system variable.
Plugin-loading options do not register any plugin in the
mysql.plugin table. For subsequent restarts,
the server loads the plugin again only if
--early-plugin-load is given
again. That is, the option produces a one-time
plugin-installation operation that persists for a single server
plugins to be loaded even when
--skip-grant-tables is given
(which causes the server to ignore the
--early-plugin-load also enable
plugins to be loaded at startup that cannot be loaded at
Each instance of
--plugin-loadresets the set of plugins to load at startup, whereas
--plugin-load-addadds a plugin or plugins to the set of plugins to be loaded without resetting the current set. Consequently, if multiple instances of
--plugin-loadare specified, only the last one applies. With multiple instances of
--plugin-load-add, all of them apply.
The argument format is the same as for
--plugin-load, but multiple instances of
--plugin-load-addcan be used to avoid specifying a large set of plugins as a single long unwieldy
--plugin-load-addcan be given in the absence of
--plugin-load, but any instance of
--plugin-load-addthat appears before
--plugin-loadhas no effect because
--plugin-loadresets the set of plugins to load.
For example, these options:
are equivalent to these options:
and are also equivalent to this option:
But these options:
are equivalent to this option:
Plugins Installed with the INSTALL PLUGIN Statement
A plugin located in a plugin library file can be loaded at
runtime with the
statement. The statement also registers the plugin in the
mysql.plugin table to cause the server to
load it on subsequent restarts. For this reason,
INSTALL PLUGIN requires the
INSERT privilege for the
The plugin library file base name depends on your platform.
Common suffixes are
.so for Unix and
.dll for Windows.
option installs a plugin at server startup. To install a plugin
myplugin from a plugin library file
somepluglib.so, use these lines in a
In this case, the plugin is not registered in
mysql.plugin. Restarting the server without
causes the plugin not to be loaded at startup.
statement causes the server to load the plugin code from the
library file at runtime:
INSTALL PLUGIN myplugin SONAME 'somepluglib.so';
INSTALL PLUGIN also causes
“permanent” plugin registration: The plugin is
listed in the
mysql.plugin table to ensure
that the server loads it on subsequent restarts.
Many plugins can be loaded either at server startup or at
runtime. However, if a plugin is designed such that it must be
loaded and initialized during server startup, attempts to load
it at runtime using
PLUGIN produce an error:
mysql> INSTALL PLUGIN myplugin SONAME 'somepluglib.so'; ERROR 1721 (HY000): Plugin 'myplugin' is marked as not dynamically installable. You have to stop the server to install it.
In this case, you must use
If a plugin is named both using a
--early-plugin-load option and
(as a result of an earlier
PLUGIN statement) in the
mysql.plugin table, the server starts but
writes these messages to the error log:
[ERROR] Function 'plugin_name' already exists [Warning] Couldn't load plugin named 'plugin_name' with soname 'plugin_object_file'.
If the server knows about a plugin when it starts (for example,
because the plugin is named using a
--plugin-load-add option or is
registered in the
mysql.plugin table), the
server loads and enables the plugin by default. It is possible
to control activation state for such a plugin using a
startup option, where
the name of the plugin to affect, such as
validate_password. As with other options,
dashes and underscores are interchangeable in option names.
Also, activation state values are not case-sensitive. For
--my-plugin=on are equivalent.
Tells the server to disable the plugin. This may not be possible for certain built-in plugins, such as
Tells the server to enable the plugin. (Specifying the option as
--without a value has the same effect.) If the plugin fails to initialize, the server runs with the plugin disabled.
Tells the server to enable the plugin, but if plugin initialization fails, the server does not start. In other words, this option forces the server to run with the plugin enabled or not at all.
FORCE, but in addition prevents the plugin from being unloaded at runtime. If a user attempts to do so with
UNINSTALL PLUGIN, an error occurs.
Plugin activation states are visible in the
LOAD_OPTION column of the Information Schema
built-in pluggable storage engines and that you want the server
to load them at startup, subject to these conditions: The server
is permitted to run if
fails, must require that
initialization succeeds, and should disable
ARCHIVE. To accomplish that, use these lines
in an option file:
[mysqld] csv=ON blackhole=FORCE archive=OFF
option format is a synonym for
option formats are synonyms for
If a plugin is disabled, either explicitly with
OFF or implicitly because it was enabled with
ON but fails to initialize, aspects of server
operation requiring the plugin change. For example, if the
plugin implements a storage engine, existing tables for the
storage engine become inaccessible, and attempts to create new
tables for the storage engine result in tables that use the
default storage engine unless the
mode is enabled to cause an error to occur instead.
Disabling a plugin may require adjustment to other options. For
example, if you start the server using
options likely also need to be omitted at startup. In addition,
InnoDB is the default
storage engine, it cannot start unless you specify another
available storage engine with
must also set
At runtime, the
statement disables and uninstalls a plugin known to the server.
The statement unloads the plugin and removes it from the
mysql.plugin system table, if it is
registered there. For this reason,
UNINSTALL PLUGIN statement
DELETE privilege for
mysql.plugin table. With the plugin no
longer registered in the table, the server does not load the
plugin during subsequent restarts.
UNINSTALL PLUGIN can unload a
plugin regardless of whether it was loaded at runtime with
INSTALL PLUGIN or at startup with
a plugin-loading option, subject to these conditions:
It cannot unload plugins that are built in to the server. These can be identified as those that have a library name of
NULLin the output from the Information Schema
It cannot unload plugins for which the server was started with
--, which prevents plugin unloading at runtime. These can be identified from the
LOAD_OPTIONcolumn of the
To uninstall a plugin that currently is loaded at server startup with a plugin-loading option, use this procedure.
Remove from the
my.cnffile any options and system variables related to the plugin. If any plugin system variables were persisted to the
mysqld-auto.cnffile, remove them using
RESET PERSISTfor each one to remove it.
Restart the server.
Plugins normally are installed using either a plugin-loading option at startup or with
INSTALL PLUGINat runtime, but not both. However, removing options for a plugin from the
my.cnffile may not be sufficient to uninstall it if at some point
INSTALL PLUGINhas also been used. If the plugin still appears in the output from
SHOW PLUGINS, use
UNINSTALL PLUGINto remove it from the
mysql.plugintable. Then restart the server again.