Server plugins must be loaded in to the server before they can be used. MySQL enables you to load a plugin at server startup or at runtime. It is also possible to control the activation of loaded plugins at startup, and to unload them at runtime.
Server plugins must be known to the server before they can be
used. A plugin can be made known several ways, as described
here. In the following descriptions,
plugin_name stands for a plugin name
A built-in plugin is known by the server automatically.
Normally, the server enables the plugin at startup; some
built-in plugins permit this to be changed with the
Plugins registered in the
mysql.plugin table serves as a registry
of plugins (other than built-in plugins, which need not be
registered). The server normally enables each plugin listed in
the table at startup, although whether a given plugin is enabled
can be changed with the
If the server is started with the
--skip-grant-tables option, it
does not consult the
mysql.plugin table and
does not load the plugins listed there.
Plugins named with the
A plugin located in a plugin library file can be loaded at
server startup with the
--plugin-load option. Normally,
the server enables the plugin at startup, although this can be
changed with the
The option value is a semicolon-separated list of
plugin_library values. Each
name is the name of a plugin to load,
plugin_library is the name of the
shared library that contains the plugin code. If a plugin
library is named without any preceding plugin name, the server
loads all plugins in 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
--plugin-load is given again.
That is, the option effects a one-time installation that
persists for a single server invocation.
--plugin-load enables plugins to
be loaded even when
--skip-grant-tables is given
(which causes the server to ignore the
--plugin-load also enables
plugins to be loaded at startup under configurations when
plugins cannot be loaded at runtime.
Plugins installed with the
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
installs a plugin at server startup. To install a plugin named
myplugin from a plugin library file named
somepluglib.so, use these lines in a
In this case, the plugin is not registered in
mysql.plugin. Restarting the server without
--plugin-load option 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 server lists
the plugin in the
mysql.plugin table to
ensure that it is loaded on subsequent server 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, use
--plugin-load rather than
If a plugin is named both using a
--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:
2013-09-24T12:35:29.584584Z 0 [ERROR] Function '
plugin_name' already exists 2013-09-24T12:35:29.584616Z 0 [Warning] Couldn't load plugin named '
plugin_name' with soname '
While a plugin is loaded, information about it is available at
runtime from several sources, such as the
SHOW PLUGINS statement.
For more information, see
Section 220.127.116.11, “Obtaining Server Plugin Information”.
If the server knows about a plugin when it starts (for example,
because the plugin is named using a
--plugin-load 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 named after the plugin. In the following
plugin_name stands for
a plugin name such as
csv. As with other options, dashes and
underscores are interchangeable in option names. Also,
activation state values are not case sensitive. For example,
--my-plugin=on are equivalent.
As of MySQL 5.1.36, these options control plugin loading:
Tells the server to disable the plugin.
Tells the server to enable the plugin. (Specifying the
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 are not case sensitive.
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, but must require that
initialization succeeds, and
be disabled. To accomplish that, use these lines in an option
[mysqld] csv=ON blackhole=FORCE archive=OFF
option format is a synonym for
option formats are synonyms for
Before MySQL 5.1.36, plugin options are boolean options (see Section 4.2.5, “Program Option Modifiers”). That is, any of these options enable the plugin:
And these options disable the plugin:
If you upgrade to MySQL 5.1.36 or later from an older version
and previously used options of the form
equivalent options are now
respectively. You also have the choice of requiring plugins to
start successfully by using
If a plugin is disabled, either explicitly with
OFF or implicitly because it was enabled with
ON but failed to initialize, aspects of
server operation that require the plugin will 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 will need to be omitted from the startup command.
In addition, if the server is configured to use
InnoDB as the default storage
engine, it will not start unless you specify another available
storage engine with
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 table, if it is registered
there. For this reason,
PLUGIN statement requires the
DELETE privilege for the
mysql.plugin table. With the plugin no longer
registered in the table, the server will not load the plugin
automatically for subsequent restarts.
UNINSTALL PLUGIN cannot unload
plugins that are built in to the server. These can be identified
as those that have a library name of
the output from
To uninstall a plugin that currently is loaded at server startup with a plugin-loading option, use this procedure.
Remove any options related to the plugin from the
Restart the server.
Plugins normally are installed using either a plugin-loading
option at startup or with
PLUGIN at runtime, but not both. However, removing
options for a plugin from the
file may not be sufficient to uninstall it if at some point
INSTALL PLUGIN has also been
used. If the plugin still appears in the output from
SHOW PLUGINS, use
UNINSTALL PLUGIN to remove it
mysql.plugin table. Then restart
the server again.