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 such as
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
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
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-add option 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
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
myplugin from a plugin library
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.
PLUGIN 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 22.214.171.124, “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
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.
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
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
PLUGIN, an error occurs. This value is available
as of MySQL 5.5.7.
Plugin activation states are visible in the
LOAD_OPTION column of the
are 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
initialization fails, but must require that
BLACKHOLE initialization succeeds, and
ARCHIVE should be disabled. 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
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.5 from a version older
than 5.1.36 and previously used options of the form
the 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
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 at startup. In
InnoDB is the
default storage engine, it will not start unless you specify
another available storage engine with
At runtime, the
PLUGIN 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,
UNINSTALL PLUGIN statement
mysql.plugin table. With the plugin
no longer registered in the table, the server will not load
the plugin automatically for subsequent restarts.
It cannot unload plugins for which the server was started
which prevents plugin unloading at runtime. These can be
identified from the
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
INSTALL PLUGIN at runtime,
but not both. However, removing options for a plugin from
my.cnf 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 from the
mysql.plugin table. Then
restart the server again.