13.7.3.3 INSTALL PLUGIN Syntax

INSTALL PLUGIN plugin_name SONAME 'shared_library_name'

This statement installs a server plugin. It requires the
INSERT privilege for the
mysql.plugin table.

plugin_name is the name of the plugin
as defined in the plugin descriptor structure contained in the
library file (see Section 22.2.4.2, “Plugin Data Structures”).
Plugin names are not case sensitive. For maximal compatibility,
plugin names should be limited to ASCII letters, digits, and
underscore because they are used in C source files, shell
command lines, M4 and Bourne shell scripts, and SQL
environments.

shared_library_name is the name of
the shared library that contains the plugin code. The name
includes the file name extension (for example,
libmyplugin.so,
libmyplugin.dll, or
libmyplugin.dylib).

The shared library must be located in the plugin directory (the
directory named by the
plugin_dir system variable).
The library must be in the plugin directory itself, not in a
subdirectory. By default,
plugin_dir is the
plugin directory under the directory named
by the pkglibdir configuration variable, but
it can be changed by setting the value of
plugin_dir at server startup.
For example, set its value in a my.cnf
file:

[mysqld]
plugin_dir=/path/to/plugin/directory

If the value of plugin_dir is a
relative path name, it is taken to be relative to the MySQL base
directory (the value of the
basedir system variable).

INSTALL PLUGIN loads and
initializes the plugin code to make the plugin available for
use. A plugin is initialized by executing its initialization
function, which handles any setup that the plugin must perform
before it can be used. When the server shuts down, it executes
the deinitialization function for each plugin that is loaded so
that the plugin has a chance to perform any final cleanup.

INSTALL PLUGIN also registers the
plugin by adding a line that indicates the plugin name and
library file name to the mysql.plugin table.
At server startup, the server loads and initializes any plugin
that is listed in the mysql.plugin table.
This means that a plugin is installed with
INSTALL PLUGIN only once, not
every time the server starts. Plugin loading at startup does not
occur if the server is started with the
--skip-grant-tables option.

A plugin library can contain multiple plugins. For each of them
to be installed, use a separate INSTALL
PLUGIN statement. Each statement names a different
plugin, but all of them specify the same library name.

As of MySQL 5.1.33, INSTALL
PLUGIN causes the server to read option
(my.cnf) files just as during server
startup. This enables the plugin to pick up any relevant options
from those files. It is possible to add plugin options to an
option file even before loading a plugin (if the
loose prefix is used). It is also possible to
uninstall a plugin, edit my.cnf, and
install the plugin again. Restarting the plugin this way enables
it to the new option values without a server restart.

Before MySQL 5.1.33, a plugin is started with each option set to
its default value.

If you recompile a plugin library and need to reinstall it, you
can use either of the following methods:

Use UNINSTALL PLUGIN to
uninstall all plugins in the library, install the new plugin
library file in the plugin directory, and then use
INSTALL PLUGIN to install all
plugins in the library. This procedure has the advantage
that it can be used without stopping the server. However, if
the plugin library contains many plugins, you must issue
many INSTALL PLUGIN and
UNINSTALL PLUGIN statements.

Stop the server, install the new plugin library file in the
plugin directory, and restart the server.