Movatterモバイル変換

• Installing Plugins

• Controlling Plugin Activation State

• Uninstalling Plugins

• Plugins and Loadable Functions

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 such asinnodb,csv, orvalidate_password.

Built-in Plugins

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--plugin_name[=activation_state] option.

Plugins Registered in the mysql.plugin System Table

Themysql.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 themysql.plugin table, the server also enables the plugin. This can be changed with the--plugin_name[=activation_state] option.

If the server is started with the--skip-grant-tables option, plugins registered in themysql.plugin table 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--plugin-load,--plugin-load-add, or--early-plugin-load option. Normally, for a plugin loaded at startup, the server also enables the plugin. This can be changed with the--plugin_name[=activation_state] option.

The--plugin-load and--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 list ofplugin_library andname=plugin_library values. Eachplugin_library is the name of a library file that contains plugin code, and eachname 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 theplugin_dir system variable.

Plugin-loading options do not register any plugin in themysql.plugin table. For subsequent restarts, the server loads the plugin again only if--plugin-load,--plugin-load-add, or--early-plugin-load is given again. That is, the option produces a one-time plugin-installation operation that persists for a single server invocation.

--plugin-load,--plugin-load-add, and--early-plugin-load enable plugins to be loaded even when--skip-grant-tables is given (which causes the server to ignore themysql.plugin table).--plugin-load,--plugin-load-add, and--early-plugin-load also enable plugins to be loaded at startup that cannot be loaded at runtime.

The--plugin-load-add option complements the--plugin-load option:

For example, these options:

--plugin-load=x --plugin-load-add=y

are equivalent to these options:

--plugin-load-add=x --plugin-load-add=y

and are also equivalent to this option:

--plugin-load="x;y"

But these options:

--plugin-load-add=y --plugin-load=x

are equivalent to this option:

--plugin-load=x

Plugins Installed with the INSTALL PLUGIN Statement

A plugin located in a plugin library file can be loaded at runtime with theINSTALL PLUGIN statement. The statement also registers the plugin in themysql.plugin table to cause the server to load it on subsequent restarts. For this reason,INSTALL PLUGIN requires theINSERT privilege for themysql.plugin table.

The plugin library file base name depends on your platform. Common suffixes are.so for Unix and Unix-like systems,.dll for Windows.

Example: The--plugin-load-add option installs a plugin at server startup. To install a plugin namedmyplugin from a plugin library file namedsomepluglib.so, use these lines in amy.cnf file:

[mysqld]plugin-load-add=myplugin=somepluglib.so

In this case, the plugin is not registered inmysql.plugin. Restarting the server without the--plugin-load-add option causes the plugin not to be loaded at startup.

Alternatively, theINSTALL 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 plugin is listed in themysql.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 usingINSTALL PLUGIN produce an error:

mysql> INSTALL PLUGIN myplugin SONAME 'somepluglib.so';ERROR 1721 (HY000): Plugin 'myplugin' is marked as not dynamicallyinstallable. You have to stop the server to install it.

In this case, you must use--plugin-load,--plugin-load-add, or--early-plugin-load.

If a plugin is named both using a--plugin-load,--plugin-load-add, or--early-plugin-load option and (as a result of an earlierINSTALL PLUGIN statement) in themysql.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 themysql.plugin table), the server loads and enables the plugin by default. It is possible to control activation state for such a plugin using a--plugin_name[=activation_state] startup option, whereplugin_name is the name of the plugin to affect, such asinnodb,csv, orvalidate_password. 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 and--my-plugin=on are equivalent.

Plugin activation states are visible in theLOAD_OPTION column of the Information SchemaPLUGINS table.

Suppose thatCSV,BLACKHOLE, andARCHIVE 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 ifCSV initialization fails, must require thatBLACKHOLE initialization succeeds, and should disableARCHIVE. To accomplish that, use these lines in an option file:

[mysqld]csv=ONblackhole=FORCEarchive=OFF

The--enable-plugin_name option format is a synonym for--plugin_name=ON. The--disable-plugin_name and--skip-plugin_name option formats are synonyms for--plugin_name=OFF.

If a plugin is disabled, either explicitly withOFF or implicitly because it was enabled withON 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 theNO_ENGINE_SUBSTITUTION SQL mode is enabled to cause an error to occur instead.

Disabling a plugin may require adjustment to other options.

At runtime, theUNINSTALL PLUGIN statement disables and uninstalls a plugin known to the server. The statement unloads the plugin and removes it from themysql.plugin system table, if it is registered there. For this reason,UNINSTALL PLUGIN statement requires theDELETE privilege for themysql.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 withINSTALL PLUGIN or at startup with a plugin-loading option, subject to these conditions:

To uninstall a plugin that currently is loaded at server startup with a plugin-loading option, use this procedure.

A plugin when installed may also automatically install related loadable functions. If so, the plugin when uninstalled also automatically uninstalls those functions.