Author: pd221994
Date: 2011-06-21 20:02:15 +0200 (Tue, 21 Jun 2011)
New Revision: 26574
Log:
r49172@dhcp-adc-twvpn-1-vpnpool-10-154-30-168: paul | 2011-06-21 12:46:29 -0500
Replace three scattered sections on plugin loading with a single section
covering same information in less fragmentary manner.
Old::
plugin-installing-uninstalling
registering-plugins
server-plugin-options
New:
server-plugin-loading
Modified:
svk:merge
trunk/refman-5.1/dba-mysqld-server-core.xml
trunk/refman-5.1/extending-mysql.xml
trunk/refman-5.1/sql-syntax-server-administration.xml
trunk/refman-5.5/dba-mysqld-server-core.xml
trunk/refman-5.5/extending-mysql.xml
trunk/refman-5.5/sql-syntax-server-administration.xml
trunk/refman-5.6/dba-mysqld-server-core.xml
trunk/refman-5.6/extending-mysql.xml
trunk/refman-5.6/sql-syntax-server-administration.xml
trunk/refman-6.0/dba-mysqld-server-core.xml
trunk/refman-6.0/extending-mysql.xml
trunk/refman-6.0/sql-syntax-server-administration.xml
Property changes on: trunk
___________________________________________________________________
Modified: svk:merge
===================================================================
Changed blocks: 0, Lines Added: 0, Lines Deleted: 0; 1277 bytes
Modified: trunk/refman-5.1/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.1/dba-mysqld-server-core.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/dba-mysqld-server-core.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 6, Lines Added: 292, Lines Deleted: 21; 14837 bytes
@@ -15002,20 +15002,263 @@
partitioning support, and server extensions.
</para>
- <section id="server-plugin-options">
+ <section id="server-plugin-loading">
- <title>Server Options for Loading Plugins</title>
+ <title>Installing and Uninstalling Plugins</title>
+ <indexterm>
+ <primary>installing plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>activating plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>activating</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>uninstalling plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>uninstalling</secondary>
+ </indexterm>
+
<para>
- The server can control plugin activation using startup options
- named for the plugins. For example, many storage engines can be
- built in pluggable form and loaded when the server starts. In
- the following descriptions,
+ 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.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-installing">Installing
+ plugins</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-activating">Controlling plugin
+ activation</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-uninstalling">Uninstalling
+ plugins</link>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <bridgehead id="server-plugin-installing">
+ Installing Plugins
+ </bridgehead>
+
+ <para>
+ 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,
<replaceable>plugin_name</replaceable> stands for a plugin name
such as <literal>innodb</literal> or <literal>csv</literal>.
</para>
<para>
+ <emphasis role="bold">Built-in plugins:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is built in to the server is known by the server
+ automatically. Normally, the server enables the plugin at
+ startup, although this can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins registered in the
+ <literal>mysql.plugin</literal> table:</emphasis>
+ </para>
+
+ <para>
+ The <literal>mysql.plugin</literal> table serves as a registry
+ of plugins. The server normally enables each plugin listed in
+ the table at startup, although whether a given plugin is enabled
+ can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option. If the server is started with the
+ <option role="mysqld">--skip-grant-tables</option> option, it
+ does not consult this table and does not load the plugins listed
+ there.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins named with the
+ <option role="mysqld">--plugin-load</option> option:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at server startup with the
+ <option role="mysqld">--plugin-load</option> option. Normally,
+ the server enables the plugin at startup, although this can be
+ changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ The option value is a semicolon-separated list of
+ <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+ pairs. Each <replaceable>name</replaceable> is the name of the
+ plugin, and <replaceable>plugin_library</replaceable> 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. Each library file must
+ be located in the directory named by the
+ <literal role="sysvar">plugin_dir</literal> system variable.
+ </para>
+
+ <para>
+ This option does not register any plugin in the
+ <literal>mysql.plugin</literal> table. For subsequent restarts,
+ the server loads the plugin again only if
+ <option role="mysqld">--plugin-load</option> is given again.
+ That is, this option effects a one-time installation that
+ persists only for one server invocation.
+ </para>
+
+ <para>
+ <option role="mysqld">--plugin-load</option> enables plugins to
+ be loaded even when
+ <option role="mysqld">--skip-grant-tables</option> is given
+ (which causes the server to ignore the
+ <literal>mysql.plugin</literal> table).
+ <option role="mysqld">--plugin-load</option> also enables
+ plugins to be loaded at startup under configurations when
+ plugins cannot be loaded at runtime.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins installed with the
+ <literal role="stmt">INSTALL PLUGIN</literal>
+ statement:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at runtime with the <literal role="mysqld">INSTALL
+ PLUGIN</literal> statement. The statement also registers the
+ plugin in the <literal>mysql.plugin</literal> table to cause the
+ server to load it on subsequent restarts. For this reason,
+ <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+ <literal role="priv">INSERT</literal> privilege for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <para>
+ If a plugin is named both using a
+ <option role="mysqld">--plugin-load</option> option and in the
+ <literal>mysql.plugin</literal> table, the server starts but
+ writes these messages to the error log:
+ </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+ <para>
+ Example: The <option role="mysqld">--plugin-load</option> option
+ installs a plugin at server startup. To install a plugin named
+ <literal>myplugin</literal> in a plugin library file named
+ <filename>somepluglib.so</filename>, use these lines in a
+ <filename>my.cnf</filename> file:
+ </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+ <para>
+ In this case, the plugin is not registered in
+ <literal>mysql.plugin</literal>. Restarting the server without
+ the <option role="mysqld">--plugin-load</option> option causes
+ the plugin not to be loaded at startup.
+ </para>
+
+ <para>
+ Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+ statement causes the server to load the plugin code from the
+ library file at runtime:
+ </para>
+
+<programlisting>
+mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+ <para>
+ <literal role="stmt">INSTALL PLUGIN</literal> also causes
+ <quote>permanent</quote> plugin registration: The server lists
+ the plugin in the <literal>mysql.plugin</literal> table to
+ ensure that it is loaded on subsequent server restarts.
+ </para>
+
+ <para>
+ 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
+ <option role="mysqld">--plugin-load</option> rather than
+ <literal role="stmt">INSTALL PLUGIN</literal>.
+ </para>
+
+ <para>
+ While a plugin is loaded, information about it is available at
+ runtime from several sources, such as the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+ and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+ For more information, see
+ <xref linkend="obtaining-plugin-information"/>.
+ </para>
+
+ <bridgehead id="server-plugin-activating">
+ Controlling Plugin Activation
+ </bridgehead>
+
+ <para>
+ If the server knows about a plugin when it starts (for example,
+ because the plugin is named using a
+ <option role="mysqld">--plugin-load</option> option or
+ registered in the <literal>mysql.plugin</literal> table), the
+ server loads and enables the plugin by default. It is possible
+ to control activation for such a plugin using a
+ <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+ startup option named after the plugin. In the following
+ descriptions, <replaceable>plugin_name</replaceable> stands for
+ a plugin name such as <literal>innodb</literal> or
+ <literal>csv</literal>. As with other options, dashes and
+ underscores are interchangeable in option names. For example,
+ <option>--my_plugin=ON</option> and
+ <option>--my-plugin=ON</option> are equivalent.
+ </para>
+
+ <para>
As of MySQL 5.1.36, these options control plugin loading:
</para>
@@ -15027,7 +15270,7 @@
</para>
<para>
- Tells the server not to enable the plugin.
+ Tells the server to disable the plugin.
</para>
</listitem>
@@ -15037,11 +15280,11 @@
</para>
<para>
- Tells the server to enable the plugin. If the plugin fails
- to initialize, the server runs with the plugin disabled.
- Specifying the option as
+ Tells the server to enable the plugin. (Specifying the
+ option as
<option>--<replaceable>plugin_name</replaceable></option>
- without a value also tells the server to enable the plugin.
+ without a value has the same effect.) If the plugin fails to
+ initialize, the server runs with the plugin disabled.
</para>
</listitem>
@@ -15054,7 +15297,7 @@
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
- or not at all.
+ enabled or not at all.
</para>
</listitem>
@@ -15068,12 +15311,13 @@
<para>
Suppose that <literal>CSV</literal>,
<literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
- built as pluggable storage engines and that you want the server
+ 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 <literal>CSV</literal> initialization
fails, but must require that <literal>BLACKHOLE</literal>
- initialization succeed. <literal>ARCHIVE</literal> should be
- disabled. To accomplish that, use these lines in an option file:
+ initialization succeeds, and <literal>ARCHIVE</literal> should
+ be disabled. To accomplish that, use these lines in an option
+ file:
</para>
<programlisting>
@@ -15146,23 +15390,50 @@
</para>
<para>
- Absence of a plugin may require adjustment to other options. For
+ Disabling a plugin may require adjustment to other options. For
example, if <literal role="se">InnoDB</literal> is disabled,
other <filename>innodb_<replaceable>xxx</replaceable></filename>
options likely will need to be omitted from the startup command.
- In addition, if the server would use
+ In addition, if the server is configured to use
<literal role="se">InnoDB</literal> as the default storage
- engine, it will not start unless you select another available
+ engine, it will not start unless you specify another available
storage engine with
<option role="mysqld">--default-storage-engine</option>.
</para>
+ <bridgehead id="server-plugin-uninstalling">
+ Uninstalling Plugins
+ </bridgehead>
+
<para>
- Plugins can also be loaded at runtime, using the
- <literal role="stmt">INSTALL PLUGIN</literal> statement. See
- <xref linkend="plugin-installing-uninstalling"/>.
+ A plugin known to the server can be uninstalled to disable it at
+ runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+ statement. The statement unloads the plugin and removes it from
+ the <literal>mysql.plugin</literal> table if it is registered
+ there. For this reason, <literal role="stmt">UNINSTALL
+ PLUGIN</literal> statement requires the
+ <literal role="priv">DELETE</literal> privilege for the
+ <literal>mysql.plugin</literal> table. With the plugin no longer
+ registered in the table, the server will not load the plugin
+ automatically for subsequent restarts.
</para>
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+ plugins regardless of whether they were loaded with
+ <literal role="stmt">INSTALL PLUGIN</literal> or
+ <option role="mysqld">--plugin-load</option>.
+ </para>
+
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
+ plugins that are built in to the server. These can be identified
+ as those that have a library name of <literal>NULL</literal> in
+ the output from
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+ <literal role="stmt">SHOW PLUGINS</literal>.
+ </para>
+
</section>
<section id="obtaining-plugin-information">
Modified: trunk/refman-5.1/extending-mysql.xml
===================================================================
--- trunk/refman-5.1/extending-mysql.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/extending-mysql.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 3, Lines Added: 4, Lines Deleted: 77; 3763 bytes
@@ -2274,79 +2274,6 @@
</section>
- <section id="registering-plugins">
-
- <title>Registering Plugins with the Server</title>
-
- <para>
- Server plugins must be registered with the server before they
- can be used. You can load a plugin at server startup with the
- <option role="mysqld">plugin-load</option> option or at
- runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
- statement.
- </para>
-
- <para>
- The <option role="mysqld">plugin-load</option> option installs
- a plugin at server startup. To install a plugin named
- <literal>myplugin</literal> in a plugin library file named
- <filename>somepluglib.so</filename>, use these lines in a
- <filename>my.cnf</filename> file:
- </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
- <para>
- In this case, the plugin is not installed permanently.
- Restarting without the
- <option role="mysqld">plugin-load</option> option causes the
- plugin not to be loaded at startup.
- </para>
-
- <para>
- Alternatively, the <literal role="stmt">INSTALL
- PLUGIN</literal> statement causes the server to register the
- plugin and load the plugin code from the library file at
- runtime:
- </para>
-
-<programlisting>
-mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> causes
- <quote>permanent</quote> plugin registration: The server lists
- the plugin in the <literal>mysql.plugin</literal> table to
- ensure that it is loaded on subsequent server restarts.
- </para>
-
- <para>
- 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,
- <literal role="stmt">INSTALL PLUGIN</literal> is not
- appropriate and you must use
- <option role="mysqld">plugin-load</option>.
- </para>
-
- <para>
- To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
- </para>
-
- <para>
- For additional information about plugin loading, see
- <xref linkend="plugin-installing-uninstalling"/>.
- </para>
-
- </section>
-
<!--
<section id="writing-storage-engine-plugins">
@@ -3126,9 +3053,9 @@
<listitem>
<para>
To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table or use the <literal role="stmt">SHOW
+ PLUGINS</literal> statement.
</para>
</listitem>
@@ -3382,7 +3309,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
Modified: trunk/refman-5.1/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.1/sql-syntax-server-administration.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.1/sql-syntax-server-administration.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 2, Lines Added: 1, Lines Deleted: 174; 6415 bytes
@@ -409,8 +409,7 @@
<para>
There are several aspects to the <literal>GRANT</literal>
- statement, described under the following topics in this
- section:
+ statement, described under the following topics in this section:
</para>
<itemizedlist>
@@ -3227,178 +3226,6 @@
<title>Plugin and User-Defined Function Statements</title>
- <section id="plugin-installing-uninstalling">
-
- <title>Installing and Uninstalling Plugins</title>
-
- <indexterm>
- <primary>installing plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>installing</secondary>
- </indexterm>
-
- <indexterm>
- <primary>uninstalling plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>uninstalling</secondary>
- </indexterm>
-
- <para>
- This section compares the various methods of installing and
- uninstalling server plugins. See also
- <xref linkend="server-plugin-options"/>.
- </para>
-
- <para>
- <option role="mysqld">--plugin-load</option> option:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at server startup to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Does not register the plugin in
- <literal>mysql.plugin</literal>. For subsequent restarts,
- the server loads the plugin again only if
- <option role="mysqld">--plugin-load</option> is given again.
- That is, this option effects a one-time installation that
- persists only for one server invocation.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at runtime to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Registers the plugin in the <literal>mysql.plugin</literal>
- table. Registration causes the server to load the plugin
- automatically for subsequent restarts. That is, it effects
- an installation that persists until the plugin is
- uninstalled explicitly.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">INSERT</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Unloads the plugin code at runtime to disable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unregisters the plugin from <literal>mysql.plugin</literal>
- if it is registered there. The server will not load it
- automatically for subsequent restarts.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">DELETE</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- While a plugin is loaded, information about it is available at
- runtime from several sources, such as the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- and the <literal role="stmt">SHOW PLUGINS</literal> statement.
- For more information, see
- <xref linkend="obtaining-plugin-information"/>.
- </para>
-
- <para>
- If <option role="mysqld">--plugin-load</option> is given at
- startup for a plugin already installed with
- <literal role="stmt">INSTALL PLUGIN</literal> during a previous
- server invocation, the server starts but writes these messages
- to the error log:
- </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
- plugins regardless of whether they were loaded with
- <literal role="stmt">INSTALL PLUGIN</literal> or
- <option role="mysqld">--plugin-load</option>. In the latter
- case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
- unregister the plugin from <literal>mysql.plugin</literal>
- because <option role="mysqld">--plugin-load</option> did not
- register it.
- </para>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
- plugins that are compiled into the server. (These can be
- identified as those that have a library name of
- <literal>NULL</literal> in the output from
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
- <literal role="stmt">SHOW PLUGINS</literal>.)
- </para>
-
- <para>
- If the server is started with the
- <option role="mysqld">--skip-grant-tables</option> option, it
- does not consult the <literal>mysql.plugins</literal> table and
- thus does not load plugins installed with the
- <literal role="stmt">INSTALL PLUGIN</literal> statement.
- <option role="mysqld">--plugin-load</option> enables plugins to
- be loaded even when
- <option role="mysqld">--skip-grant-tables</option> is given.
- <option role="mysqld">--plugin-load</option> also enables
- plugins to be loaded at startup under configurations when
- plugins cannot be loaded at runtime.
- </para>
-
- </section>
-
<section id="create-function-udf">
<title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined
Modified: trunk/refman-5.5/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.5/dba-mysqld-server-core.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/dba-mysqld-server-core.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 9, Lines Added: 325, Lines Deleted: 28; 17121 bytes
@@ -15583,23 +15583,262 @@
and server extensions.
</para>
- <section id="server-plugin-options">
+ <section id="server-plugin-loading">
- <title>Server Options for Loading Plugins</title>
+ <title>Installing and Uninstalling Plugins</title>
+ <indexterm>
+ <primary>installing plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>activating plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>activating</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>uninstalling plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>uninstalling</secondary>
+ </indexterm>
+
<para>
- The server can control plugin activation using startup options
- named for the plugins. For example, many storage engines can be
- built in pluggable form and loaded when the server starts. In
- the following descriptions,
+ 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.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-installing">Installing
+ plugins</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-activating">Controlling plugin
+ activation</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-uninstalling">Uninstalling
+ plugins</link>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <bridgehead id="server-plugin-installing">
+ Installing Plugins
+ </bridgehead>
+
+ <para>
+ 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,
<replaceable>plugin_name</replaceable> stands for a plugin name
such as <literal>innodb</literal> or <literal>csv</literal>.
</para>
<para>
- In MySQL ¤t-series;, these options control plugin loading:
+ <emphasis role="bold">Built-in plugins:</emphasis>
</para>
+ <para>
+ A plugin that is built in to the server is known by the server
+ automatically. Normally, the server enables the plugin at
+ startup, although this can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins registered in the
+ <literal>mysql.plugin</literal> table:</emphasis>
+ </para>
+
+ <para>
+ The <literal>mysql.plugin</literal> table serves as a registry
+ of plugins. The server normally enables each plugin listed in
+ the table at startup, although whether a given plugin is enabled
+ can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option. If the server is started with the
+ <option role="mysqld">--skip-grant-tables</option> option, it
+ does not consult this table and does not load the plugins listed
+ there.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins named with the
+ <option role="mysqld">--plugin-load</option> option:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at server startup with the
+ <option role="mysqld">--plugin-load</option> option. Normally,
+ the server enables the plugin at startup, although this can be
+ changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ The option value is a semicolon-separated list of
+ <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+ pairs. Each <replaceable>name</replaceable> is the name of the
+ plugin, and <replaceable>plugin_library</replaceable> 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. Each library file must
+ be located in the directory named by the
+ <literal role="sysvar">plugin_dir</literal> system variable.
+ </para>
+
+ <para>
+ This option does not register any plugin in the
+ <literal>mysql.plugin</literal> table. For subsequent restarts,
+ the server loads the plugin again only if
+ <option role="mysqld">--plugin-load</option> is given again.
+ That is, this option effects a one-time installation that
+ persists only for one server invocation.
+ </para>
+
+ <para>
+ <option role="mysqld">--plugin-load</option> enables plugins to
+ be loaded even when
+ <option role="mysqld">--skip-grant-tables</option> is given
+ (which causes the server to ignore the
+ <literal>mysql.plugin</literal> table).
+ <option role="mysqld">--plugin-load</option> also enables
+ plugins to be loaded at startup under configurations when
+ plugins cannot be loaded at runtime.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins installed with the
+ <literal role="stmt">INSTALL PLUGIN</literal>
+ statement:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at runtime with the <literal role="mysqld">INSTALL
+ PLUGIN</literal> statement. The statement also registers the
+ plugin in the <literal>mysql.plugin</literal> table to cause the
+ server to load it on subsequent restarts. For this reason,
+ <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+ <literal role="priv">INSERT</literal> privilege for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <para>
+ If a plugin is named both using a
+ <option role="mysqld">--plugin-load</option> option and in the
+ <literal>mysql.plugin</literal> table, the server starts but
+ writes these messages to the error log:
+ </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+ <para>
+ Example: The <option role="mysqld">--plugin-load</option> option
+ installs a plugin at server startup. To install a plugin named
+ <literal>myplugin</literal> in a plugin library file named
+ <filename>somepluglib.so</filename>, use these lines in a
+ <filename>my.cnf</filename> file:
+ </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+ <para>
+ In this case, the plugin is not registered in
+ <literal>mysql.plugin</literal>. Restarting the server without
+ the <option role="mysqld">--plugin-load</option> option causes
+ the plugin not to be loaded at startup.
+ </para>
+
+ <para>
+ Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+ statement causes the server to load the plugin code from the
+ library file at runtime:
+ </para>
+
+<programlisting>
+mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+ <para>
+ <literal role="stmt">INSTALL PLUGIN</literal> also causes
+ <quote>permanent</quote> plugin registration: The server lists
+ the plugin in the <literal>mysql.plugin</literal> table to
+ ensure that it is loaded on subsequent server restarts.
+ </para>
+
+ <para>
+ 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
+ <option role="mysqld">--plugin-load</option> rather than
+ <literal role="stmt">INSTALL PLUGIN</literal>.
+ </para>
+
+ <para>
+ While a plugin is loaded, information about it is available at
+ runtime from several sources, such as the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+ and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+ For more information, see
+ <xref linkend="obtaining-plugin-information"/>.
+ </para>
+
+ <bridgehead id="server-plugin-activating">
+ Controlling Plugin Activation
+ </bridgehead>
+
+ <para>
+ If the server knows about a plugin when it starts (for example,
+ because the plugin is named using a
+ <option role="mysqld">--plugin-load</option> option or
+ registered in the <literal>mysql.plugin</literal> table), the
+ server loads and enables the plugin by default. It is possible
+ to control activation for such a plugin using a
+ <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+ startup option named after the plugin. In the following
+ descriptions, <replaceable>plugin_name</replaceable> stands for
+ a plugin name such as <literal>innodb</literal> or
+ <literal>csv</literal>. As with other options, dashes and
+ underscores are interchangeable in option names. For example,
+ <option>--my_plugin=ON</option> and
+ <option>--my-plugin=ON</option> are equivalent.
+ </para>
+
<itemizedlist>
<listitem>
@@ -15608,7 +15847,7 @@
</para>
<para>
- Tells the server not to enable the plugin.
+ Tells the server to disable the plugin.
</para>
</listitem>
@@ -15618,11 +15857,11 @@
</para>
<para>
- Tells the server to enable the plugin. If the plugin fails
- to initialize, the server runs with the plugin disabled.
- Specifying the option as
+ Tells the server to enable the plugin. (Specifying the
+ option as
<option>--<replaceable>plugin_name</replaceable></option>
- without a value also tells the server to enable the plugin.
+ without a value has the same effect.) If the plugin fails to
+ initialize, the server runs with the plugin disabled.
</para>
</listitem>
@@ -15635,7 +15874,7 @@
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
- or not at all.
+ enabled or not at all.
</para>
</listitem>
@@ -15661,14 +15900,21 @@
</para>
<para>
+ The activation state for plugins is visible in the
+ <literal>LOAD_OPTION</literal> column of the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table.
+ </para>
+
+ <para>
Suppose that <literal>CSV</literal>,
<literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
- built as pluggable storage engines and that you want the server
+ 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 <literal>CSV</literal> initialization
fails, but must require that <literal>BLACKHOLE</literal>
- initialization succeed. <literal>ARCHIVE</literal> should be
- disabled. To accomplish that, use these lines in an option file:
+ initialization succeeds, and <literal>ARCHIVE</literal> should
+ be disabled. To accomplish that, use these lines in an option
+ file:
</para>
<programlisting>
@@ -15692,9 +15938,9 @@
</para>
<para>
- Before MySQL ¤t-series;, plugin options are boolean
- options (see <xref linkend="option-modifiers"/>). That is, any
- of these options enable the plugin:
+ Before MySQL 5.1.36, plugin options are boolean options (see
+ <xref linkend="option-modifiers"/>). That is, any of these
+ options enable the plugin:
</para>
<programlisting>
@@ -15714,8 +15960,8 @@
</programlisting>
<para>
- If you upgrade to MySQL ¤t-series; from an older version
- and previously used options of the form
+ If you upgrade to MySQL ¤t-series; from a version older
+ than 5.1.36 and previously used options of the form
<option>--<replaceable>plugin_name</replaceable>=0</option> or
<option>--<replaceable>plugin_name</replaceable>=1</option>, the
equivalent options are now
@@ -15724,7 +15970,9 @@
<option>--<replaceable>plugin_name</replaceable>=ON</option>,
respectively. You also have the choice of requiring plugins to
start successfully by using
- <option>--<replaceable>plugin_name</replaceable>=FORCE</option>.
+ <option>--<replaceable>plugin_name</replaceable>=FORCE</option>
+ or
+ <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>.
</para>
<para>
@@ -15741,23 +15989,72 @@
</para>
<para>
- Absence of a plugin may require adjustment to other options. For
+ Disabling a plugin may require adjustment to other options. For
example, if <literal role="se">InnoDB</literal> is disabled,
other <filename>innodb_<replaceable>xxx</replaceable></filename>
options likely will need to be omitted from the startup command.
- In addition, if the server would use
+ In addition, if the server is configured to use
<literal role="se">InnoDB</literal> as the default storage
- engine, it will not start unless you select another available
+ engine, it will not start unless you specify another available
storage engine with
<option role="mysqld">--default-storage-engine</option>.
</para>
+ <bridgehead id="server-plugin-uninstalling">
+ Uninstalling Plugins
+ </bridgehead>
+
<para>
- Plugins can also be loaded at runtime, using the
- <literal role="stmt">INSTALL PLUGIN</literal> statement. See
- <xref linkend="plugin-installing-uninstalling"/>.
+ A plugin known to the server can be uninstalled to disable it at
+ runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+ statement. The statement unloads the plugin and removes it from
+ the <literal>mysql.plugin</literal> table if it is registered
+ there. For this reason, <literal role="stmt">UNINSTALL
+ PLUGIN</literal> statement requires the
+ <literal role="priv">DELETE</literal> privilege for the
+ <literal>mysql.plugin</literal> table. With the plugin no longer
+ registered in the table, the server will not load the plugin
+ automatically for subsequent restarts.
</para>
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+ plugins regardless of whether they were loaded with
+ <literal role="stmt">INSTALL PLUGIN</literal> or
+ <option role="mysqld">--plugin-load</option>.
+ </para>
+
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> is subject to
+ these exceptions:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ It cannot unload plugins that are built in to the server.
+ These can be identified as those that have a library name of
+ <literal>NULL</literal> in the output from
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+ <literal role="stmt">SHOW PLUGINS</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It cannot unload plugins for which the server was started
+ with
+ <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>,
+ which prevents plugin unloading at runtime. These can be
+ identified from the <literal>LOAD_OPTION</literal> column of
+ the <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
</section>
<section id="obtaining-plugin-information">
Modified: trunk/refman-5.5/extending-mysql.xml
===================================================================
--- trunk/refman-5.5/extending-mysql.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/extending-mysql.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes
@@ -2853,79 +2853,6 @@
</section>
- <section id="registering-plugins">
-
- <title>Registering Plugins with the Server</title>
-
- <para>
- Server plugins must be registered with the server before they
- can be used. You can load a plugin at server startup with the
- <option role="mysqld">plugin-load</option> option or at
- runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
- statement.
- </para>
-
- <para>
- The <option role="mysqld">plugin-load</option> option installs
- a plugin at server startup. To install a plugin named
- <literal>myplugin</literal> in a plugin library file named
- <filename>somepluglib.so</filename>, use these lines in a
- <filename>my.cnf</filename> file:
- </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
- <para>
- In this case, the plugin is not installed permanently.
- Restarting without the
- <option role="mysqld">plugin-load</option> option causes the
- plugin not to be loaded at startup.
- </para>
-
- <para>
- Alternatively, the <literal role="stmt">INSTALL
- PLUGIN</literal> statement causes the server to register the
- plugin and load the plugin code from the library file at
- runtime:
- </para>
-
-<programlisting>
-mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> causes
- <quote>permanent</quote> plugin registration: The server lists
- the plugin in the <literal>mysql.plugin</literal> table to
- ensure that it is loaded on subsequent server restarts.
- </para>
-
- <para>
- 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,
- <literal role="stmt">INSTALL PLUGIN</literal> is not
- appropriate and you must use
- <option role="mysqld">plugin-load</option>.
- </para>
-
- <para>
- To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
- </para>
-
- <para>
- For additional information about plugin loading, see
- <xref linkend="plugin-installing-uninstalling"/>.
- </para>
-
- </section>
-
<!--
<section id="writing-storage-engine-plugins">
@@ -3697,9 +3624,9 @@
<listitem>
<para>
To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table or use the <literal role="stmt">SHOW
+ PLUGINS</literal> statement.
</para>
</listitem>
@@ -3953,7 +3880,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
@@ -4677,7 +4604,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
Modified: trunk/refman-5.5/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.5/sql-syntax-server-administration.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.5/sql-syntax-server-administration.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes
@@ -3107,178 +3107,6 @@
<title>Plugin and User-Defined Function Statements</title>
- <section id="plugin-installing-uninstalling">
-
- <title>Installing and Uninstalling Plugins</title>
-
- <indexterm>
- <primary>installing plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>installing</secondary>
- </indexterm>
-
- <indexterm>
- <primary>uninstalling plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>uninstalling</secondary>
- </indexterm>
-
- <para>
- This section compares the various methods of installing and
- uninstalling server plugins. See also
- <xref linkend="server-plugin-options"/>.
- </para>
-
- <para>
- <option role="mysqld">--plugin-load</option> option:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at server startup to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Does not register the plugin in
- <literal>mysql.plugin</literal>. For subsequent restarts,
- the server loads the plugin again only if
- <option role="mysqld">--plugin-load</option> is given again.
- That is, this option effects a one-time installation that
- persists only for one server invocation.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at runtime to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Registers the plugin in the <literal>mysql.plugin</literal>
- table. Registration causes the server to load the plugin
- automatically for subsequent restarts. That is, it effects
- an installation that persists until the plugin is
- uninstalled explicitly.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">INSERT</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Unloads the plugin code at runtime to disable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unregisters the plugin from <literal>mysql.plugin</literal>
- if it is registered there. The server will not load it
- automatically for subsequent restarts.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">DELETE</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- While a plugin is loaded, information about it is available at
- runtime from several sources, such as the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- and the <literal role="stmt">SHOW PLUGINS</literal> statement.
- For more information, see
- <xref linkend="obtaining-plugin-information"/>.
- </para>
-
- <para>
- If <option role="mysqld">--plugin-load</option> is given at
- startup for a plugin already installed with
- <literal role="stmt">INSTALL PLUGIN</literal> during a previous
- server invocation, the server starts but writes these messages
- to the error log:
- </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
- plugins regardless of whether they were loaded with
- <literal role="stmt">INSTALL PLUGIN</literal> or
- <option role="mysqld">--plugin-load</option>. In the latter
- case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
- unregister the plugin from <literal>mysql.plugin</literal>
- because <option role="mysqld">--plugin-load</option> did not
- register it.
- </para>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
- plugins that are compiled into the server. (These can be
- identified as those that have a library name of
- <literal>NULL</literal> in the output from
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
- <literal role="stmt">SHOW PLUGINS</literal>.)
- </para>
-
- <para>
- If the server is started with the
- <option role="mysqld">--skip-grant-tables</option> option, it
- does not consult the <literal>mysql.plugins</literal> table and
- thus does not load plugins installed with the
- <literal role="stmt">INSTALL PLUGIN</literal> statement.
- <option role="mysqld">--plugin-load</option> enables plugins to
- be loaded even when
- <option role="mysqld">--skip-grant-tables</option> is given.
- <option role="mysqld">--plugin-load</option> also enables
- plugins to be loaded at startup under configurations when
- plugins cannot be loaded at runtime.
- </para>
-
- </section>
-
<section id="create-function-udf">
<title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined
Modified: trunk/refman-5.6/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-5.6/dba-mysqld-server-core.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/dba-mysqld-server-core.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 6, Lines Added: 317, Lines Deleted: 22; 15731 bytes
@@ -15235,23 +15235,262 @@
and server extensions.
</para>
- <section id="server-plugin-options">
+ <section id="server-plugin-loading">
- <title>Server Options for Loading Plugins</title>
+ <title>Installing and Uninstalling Plugins</title>
+ <indexterm>
+ <primary>installing plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>activating plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>activating</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>uninstalling plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>uninstalling</secondary>
+ </indexterm>
+
<para>
- The server can control plugin activation using startup options
- named for the plugins. For example, many storage engines can be
- built in pluggable form and loaded when the server starts. In
- the following descriptions,
+ 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.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-installing">Installing
+ plugins</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-activating">Controlling plugin
+ activation</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-uninstalling">Uninstalling
+ plugins</link>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <bridgehead id="server-plugin-installing">
+ Installing Plugins
+ </bridgehead>
+
+ <para>
+ 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,
<replaceable>plugin_name</replaceable> stands for a plugin name
such as <literal>innodb</literal> or <literal>csv</literal>.
</para>
<para>
- In MySQL ¤t-series;, these options control plugin loading:
+ <emphasis role="bold">Built-in plugins:</emphasis>
</para>
+ <para>
+ A plugin that is built in to the server is known by the server
+ automatically. Normally, the server enables the plugin at
+ startup, although this can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins registered in the
+ <literal>mysql.plugin</literal> table:</emphasis>
+ </para>
+
+ <para>
+ The <literal>mysql.plugin</literal> table serves as a registry
+ of plugins. The server normally enables each plugin listed in
+ the table at startup, although whether a given plugin is enabled
+ can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option. If the server is started with the
+ <option role="mysqld">--skip-grant-tables</option> option, it
+ does not consult this table and does not load the plugins listed
+ there.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins named with the
+ <option role="mysqld">--plugin-load</option> option:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at server startup with the
+ <option role="mysqld">--plugin-load</option> option. Normally,
+ the server enables the plugin at startup, although this can be
+ changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ The option value is a semicolon-separated list of
+ <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+ pairs. Each <replaceable>name</replaceable> is the name of the
+ plugin, and <replaceable>plugin_library</replaceable> 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. Each library file must
+ be located in the directory named by the
+ <literal role="sysvar">plugin_dir</literal> system variable.
+ </para>
+
+ <para>
+ This option does not register any plugin in the
+ <literal>mysql.plugin</literal> table. For subsequent restarts,
+ the server loads the plugin again only if
+ <option role="mysqld">--plugin-load</option> is given again.
+ That is, this option effects a one-time installation that
+ persists only for one server invocation.
+ </para>
+
+ <para>
+ <option role="mysqld">--plugin-load</option> enables plugins to
+ be loaded even when
+ <option role="mysqld">--skip-grant-tables</option> is given
+ (which causes the server to ignore the
+ <literal>mysql.plugin</literal> table).
+ <option role="mysqld">--plugin-load</option> also enables
+ plugins to be loaded at startup under configurations when
+ plugins cannot be loaded at runtime.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins installed with the
+ <literal role="stmt">INSTALL PLUGIN</literal>
+ statement:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at runtime with the <literal role="mysqld">INSTALL
+ PLUGIN</literal> statement. The statement also registers the
+ plugin in the <literal>mysql.plugin</literal> table to cause the
+ server to load it on subsequent restarts. For this reason,
+ <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+ <literal role="priv">INSERT</literal> privilege for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <para>
+ If a plugin is named both using a
+ <option role="mysqld">--plugin-load</option> option and in the
+ <literal>mysql.plugin</literal> table, the server starts but
+ writes these messages to the error log:
+ </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+ <para>
+ Example: The <option role="mysqld">--plugin-load</option> option
+ installs a plugin at server startup. To install a plugin named
+ <literal>myplugin</literal> in a plugin library file named
+ <filename>somepluglib.so</filename>, use these lines in a
+ <filename>my.cnf</filename> file:
+ </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+ <para>
+ In this case, the plugin is not registered in
+ <literal>mysql.plugin</literal>. Restarting the server without
+ the <option role="mysqld">--plugin-load</option> option causes
+ the plugin not to be loaded at startup.
+ </para>
+
+ <para>
+ Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+ statement causes the server to load the plugin code from the
+ library file at runtime:
+ </para>
+
+<programlisting>
+mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+ <para>
+ <literal role="stmt">INSTALL PLUGIN</literal> also causes
+ <quote>permanent</quote> plugin registration: The server lists
+ the plugin in the <literal>mysql.plugin</literal> table to
+ ensure that it is loaded on subsequent server restarts.
+ </para>
+
+ <para>
+ 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
+ <option role="mysqld">--plugin-load</option> rather than
+ <literal role="stmt">INSTALL PLUGIN</literal>.
+ </para>
+
+ <para>
+ While a plugin is loaded, information about it is available at
+ runtime from several sources, such as the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+ and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+ For more information, see
+ <xref linkend="obtaining-plugin-information"/>.
+ </para>
+
+ <bridgehead id="server-plugin-activating">
+ Controlling Plugin Activation
+ </bridgehead>
+
+ <para>
+ If the server knows about a plugin when it starts (for example,
+ because the plugin is named using a
+ <option role="mysqld">--plugin-load</option> option or
+ registered in the <literal>mysql.plugin</literal> table), the
+ server loads and enables the plugin by default. It is possible
+ to control activation for such a plugin using a
+ <literal>--<replaceable>plugin_name</replaceable>[=<replaceable>value</replaceable>]</literal>
+ startup option named after the plugin. In the following
+ descriptions, <replaceable>plugin_name</replaceable> stands for
+ a plugin name such as <literal>innodb</literal> or
+ <literal>csv</literal>. As with other options, dashes and
+ underscores are interchangeable in option names. For example,
+ <option>--my_plugin=ON</option> and
+ <option>--my-plugin=ON</option> are equivalent.
+ </para>
+
<itemizedlist>
<listitem>
@@ -15260,7 +15499,7 @@
</para>
<para>
- Tells the server not to enable the plugin.
+ Tells the server to disable the plugin.
</para>
</listitem>
@@ -15270,11 +15509,11 @@
</para>
<para>
- Tells the server to enable the plugin. If the plugin fails
- to initialize, the server runs with the plugin disabled.
- Specifying the option as
+ Tells the server to enable the plugin. (Specifying the
+ option as
<option>--<replaceable>plugin_name</replaceable></option>
- without a value also tells the server to enable the plugin.
+ without a value has the same effect.) If the plugin fails to
+ initialize, the server runs with the plugin disabled.
</para>
</listitem>
@@ -15287,7 +15526,7 @@
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
- or not at all.
+ enabled or not at all.
</para>
</listitem>
@@ -15313,14 +15552,21 @@
</para>
<para>
+ The activation state for plugins is visible in the
+ <literal>LOAD_OPTION</literal> column of the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table.
+ </para>
+
+ <para>
Suppose that <literal>CSV</literal>,
<literal>BLACKHOLE</literal>, and <literal>ARCHIVE</literal> are
- built as pluggable storage engines and that you want the server
+ 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 <literal>CSV</literal> initialization
fails, but must require that <literal>BLACKHOLE</literal>
- initialization succeed. <literal>ARCHIVE</literal> should be
- disabled. To accomplish that, use these lines in an option file:
+ initialization succeeds, and <literal>ARCHIVE</literal> should
+ be disabled. To accomplish that, use these lines in an option
+ file:
</para>
<programlisting>
@@ -15357,23 +15603,72 @@
</para>
<para>
- Absence of a plugin may require adjustment to other options. For
+ Disabling a plugin may require adjustment to other options. For
example, if <literal role="se">InnoDB</literal> is disabled,
other <filename>innodb_<replaceable>xxx</replaceable></filename>
options likely will need to be omitted from the startup command.
- In addition, if the server would use
+ In addition, if the server is configured to use
<literal role="se">InnoDB</literal> as the default storage
- engine, it will not start unless you select another available
+ engine, it will not start unless you specify another available
storage engine with
<option role="mysqld">--default-storage-engine</option>.
</para>
+ <bridgehead id="server-plugin-uninstalling">
+ Uninstalling Plugins
+ </bridgehead>
+
<para>
- Plugins can also be loaded at runtime, using the
- <literal role="stmt">INSTALL PLUGIN</literal> statement. See
- <xref linkend="plugin-installing-uninstalling"/>.
+ A plugin known to the server can be uninstalled to disable it at
+ runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+ statement. The statement unloads the plugin and removes it from
+ the <literal>mysql.plugin</literal> table if it is registered
+ there. For this reason, <literal role="stmt">UNINSTALL
+ PLUGIN</literal> statement requires the
+ <literal role="priv">DELETE</literal> privilege for the
+ <literal>mysql.plugin</literal> table. With the plugin no longer
+ registered in the table, the server will not load the plugin
+ automatically for subsequent restarts.
</para>
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+ plugins regardless of whether they were loaded with
+ <literal role="stmt">INSTALL PLUGIN</literal> or
+ <option role="mysqld">--plugin-load</option>.
+ </para>
+
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> is subject to
+ these exceptions:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ It cannot unload plugins that are built in to the server.
+ These can be identified as those that have a library name of
+ <literal>NULL</literal> in the output from
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+ <literal role="stmt">SHOW PLUGINS</literal>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ It cannot unload plugins for which the server was started
+ with
+ <option>--<replaceable>plugin_name</replaceable>=FORCE_PLUS_PERMANENT</option>,
+ which prevents plugin unloading at runtime. These can be
+ identified from the <literal>LOAD_OPTION</literal> column of
+ the <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
</section>
<section id="obtaining-plugin-information">
Modified: trunk/refman-5.6/extending-mysql.xml
===================================================================
--- trunk/refman-5.6/extending-mysql.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/extending-mysql.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes
@@ -2853,79 +2853,6 @@
</section>
- <section id="registering-plugins">
-
- <title>Registering Plugins with the Server</title>
-
- <para>
- Server plugins must be registered with the server before they
- can be used. You can load a plugin at server startup with the
- <option role="mysqld">plugin-load</option> option or at
- runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
- statement.
- </para>
-
- <para>
- The <option role="mysqld">plugin-load</option> option installs
- a plugin at server startup. To install a plugin named
- <literal>myplugin</literal> in a plugin library file named
- <filename>somepluglib.so</filename>, use these lines in a
- <filename>my.cnf</filename> file:
- </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
- <para>
- In this case, the plugin is not installed permanently.
- Restarting without the
- <option role="mysqld">plugin-load</option> option causes the
- plugin not to be loaded at startup.
- </para>
-
- <para>
- Alternatively, the <literal role="stmt">INSTALL
- PLUGIN</literal> statement causes the server to register the
- plugin and load the plugin code from the library file at
- runtime:
- </para>
-
-<programlisting>
-mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> causes
- <quote>permanent</quote> plugin registration: The server lists
- the plugin in the <literal>mysql.plugin</literal> table to
- ensure that it is loaded on subsequent server restarts.
- </para>
-
- <para>
- 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,
- <literal role="stmt">INSTALL PLUGIN</literal> is not
- appropriate and you must use
- <option role="mysqld">plugin-load</option>.
- </para>
-
- <para>
- To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
- </para>
-
- <para>
- For additional information about plugin loading, see
- <xref linkend="plugin-installing-uninstalling"/>.
- </para>
-
- </section>
-
<!--
<section id="writing-storage-engine-plugins">
@@ -3697,9 +3624,9 @@
<listitem>
<para>
To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table or use the <literal role="stmt">SHOW
+ PLUGINS</literal> statement.
</para>
</listitem>
@@ -3953,7 +3880,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
@@ -4671,7 +4598,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
Modified: trunk/refman-5.6/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-5.6/sql-syntax-server-administration.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-5.6/sql-syntax-server-administration.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes
@@ -3106,178 +3106,6 @@
<title>Plugin and User-Defined Function Statements</title>
- <section id="plugin-installing-uninstalling">
-
- <title>Installing and Uninstalling Plugins</title>
-
- <indexterm>
- <primary>installing plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>installing</secondary>
- </indexterm>
-
- <indexterm>
- <primary>uninstalling plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>uninstalling</secondary>
- </indexterm>
-
- <para>
- This section compares the various methods of installing and
- uninstalling server plugins. See also
- <xref linkend="server-plugin-options"/>.
- </para>
-
- <para>
- <option role="mysqld">--plugin-load</option> option:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at server startup to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Does not register the plugin in
- <literal>mysql.plugin</literal>. For subsequent restarts,
- the server loads the plugin again only if
- <option role="mysqld">--plugin-load</option> is given again.
- That is, this option effects a one-time installation that
- persists only for one server invocation.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at runtime to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Registers the plugin in the <literal>mysql.plugin</literal>
- table. Registration causes the server to load the plugin
- automatically for subsequent restarts. That is, it effects
- an installation that persists until the plugin is
- uninstalled explicitly.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">INSERT</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Unloads the plugin code at runtime to disable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unregisters the plugin from <literal>mysql.plugin</literal>
- if it is registered there. The server will not load it
- automatically for subsequent restarts.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">DELETE</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- While a plugin is loaded, information about it is available at
- runtime from several sources, such as the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- and the <literal role="stmt">SHOW PLUGINS</literal> statement.
- For more information, see
- <xref linkend="obtaining-plugin-information"/>.
- </para>
-
- <para>
- If <option role="mysqld">--plugin-load</option> is given at
- startup for a plugin already installed with
- <literal role="stmt">INSTALL PLUGIN</literal> during a previous
- server invocation, the server starts but writes these messages
- to the error log:
- </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
- plugins regardless of whether they were loaded with
- <literal role="stmt">INSTALL PLUGIN</literal> or
- <option role="mysqld">--plugin-load</option>. In the latter
- case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
- unregister the plugin from <literal>mysql.plugin</literal>
- because <option role="mysqld">--plugin-load</option> did not
- register it.
- </para>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
- plugins that are compiled into the server. (These can be
- identified as those that have a library name of
- <literal>NULL</literal> in the output from
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
- <literal role="stmt">SHOW PLUGINS</literal>.)
- </para>
-
- <para>
- If the server is started with the
- <option role="mysqld">--skip-grant-tables</option> option, it
- does not consult the <literal>mysql.plugins</literal> table and
- thus does not load plugins installed with the
- <literal role="stmt">INSTALL PLUGIN</literal> statement.
- <option role="mysqld">--plugin-load</option> enables plugins to
- be loaded even when
- <option role="mysqld">--skip-grant-tables</option> is given.
- <option role="mysqld">--plugin-load</option> also enables
- plugins to be loaded at startup under configurations when
- plugins cannot be loaded at runtime.
- </para>
-
- </section>
-
<section id="create-function-udf">
<title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined
Modified: trunk/refman-6.0/dba-mysqld-server-core.xml
===================================================================
--- trunk/refman-6.0/dba-mysqld-server-core.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/dba-mysqld-server-core.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 3, Lines Added: 285, Lines Deleted: 14; 13471 bytes
@@ -16283,20 +16283,263 @@
and server extensions.
</para>
- <section id="server-plugin-options">
+ <section id="server-plugin-loading">
- <title>Server Options for Loading Plugins</title>
+ <title>Installing and Uninstalling Plugins</title>
+ <indexterm>
+ <primary>installing plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>installing</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>activating plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>activating</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>uninstalling plugins</primary>
+ </indexterm>
+
+ <indexterm>
+ <primary>plugins</primary>
+ <secondary>uninstalling</secondary>
+ </indexterm>
+
<para>
- The server can control plugin activation using startup options
- named for the plugins. For example, many storage engines can be
- built in pluggable form and loaded when the server starts. In
- the following descriptions,
+ 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.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-installing">Installing
+ plugins</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-activating">Controlling plugin
+ activation</link>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <link linkend="server-plugin-uninstalling">Uninstalling
+ plugins</link>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <bridgehead id="server-plugin-installing">
+ Installing Plugins
+ </bridgehead>
+
+ <para>
+ 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,
<replaceable>plugin_name</replaceable> stands for a plugin name
such as <literal>innodb</literal> or <literal>csv</literal>.
</para>
<para>
+ <emphasis role="bold">Built-in plugins:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is built in to the server is known by the server
+ automatically. Normally, the server enables the plugin at
+ startup, although this can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins registered in the
+ <literal>mysql.plugin</literal> table:</emphasis>
+ </para>
+
+ <para>
+ The <literal>mysql.plugin</literal> table serves as a registry
+ of plugins. The server normally enables each plugin listed in
+ the table at startup, although whether a given plugin is enabled
+ can be changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option. If the server is started with the
+ <option role="mysqld">--skip-grant-tables</option> option, it
+ does not consult this table and does not load the plugins listed
+ there.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins named with the
+ <option role="mysqld">--plugin-load</option> option:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at server startup with the
+ <option role="mysqld">--plugin-load</option> option. Normally,
+ the server enables the plugin at startup, although this can be
+ changed with the
+ <option>--<replaceable>plugin_name</replaceable></option>
+ option.
+ </para>
+
+ <para>
+ The option value is a semicolon-separated list of
+ <literal><replaceable>name</replaceable>=<replaceable>plugin_library</replaceable></literal>
+ pairs. Each <replaceable>name</replaceable> is the name of the
+ plugin, and <replaceable>plugin_library</replaceable> 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. Each library file must
+ be located in the directory named by the
+ <literal role="sysvar">plugin_dir</literal> system variable.
+ </para>
+
+ <para>
+ This option does not register any plugin in the
+ <literal>mysql.plugin</literal> table. For subsequent restarts,
+ the server loads the plugin again only if
+ <option role="mysqld">--plugin-load</option> is given again.
+ That is, this option effects a one-time installation that
+ persists only for one server invocation.
+ </para>
+
+ <para>
+ <option role="mysqld">--plugin-load</option> enables plugins to
+ be loaded even when
+ <option role="mysqld">--skip-grant-tables</option> is given
+ (which causes the server to ignore the
+ <literal>mysql.plugin</literal> table).
+ <option role="mysqld">--plugin-load</option> also enables
+ plugins to be loaded at startup under configurations when
+ plugins cannot be loaded at runtime.
+ </para>
+
+ <para>
+ <emphasis role="bold">Plugins installed with the
+ <literal role="stmt">INSTALL PLUGIN</literal>
+ statement:</emphasis>
+ </para>
+
+ <para>
+ A plugin that is located in a plugin library file can be loaded
+ at runtime with the <literal role="mysqld">INSTALL
+ PLUGIN</literal> statement. The statement also registers the
+ plugin in the <literal>mysql.plugin</literal> table to cause the
+ server to load it on subsequent restarts. For this reason,
+ <literal role="mysqld">INSTALL PLUGIN</literal> requires the
+ <literal role="priv">INSERT</literal> privilege for the
+ <literal>mysql.plugin</literal> table.
+ </para>
+
+ <para>
+ If a plugin is named both using a
+ <option role="mysqld">--plugin-load</option> option and in the
+ <literal>mysql.plugin</literal> table, the server starts but
+ writes these messages to the error log:
+ </para>
+
+<programlisting>
+100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
+100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
+with soname '<replaceable>plugin_object_file</replaceable>'.
+</programlisting>
+
+ <para>
+ Example: The <option role="mysqld">--plugin-load</option> option
+ installs a plugin at server startup. To install a plugin named
+ <literal>myplugin</literal> in a plugin library file named
+ <filename>somepluglib.so</filename>, use these lines in a
+ <filename>my.cnf</filename> file:
+ </para>
+
+<programlisting>
+[mysqld]
+plugin-load=myplugin=somepluglib.so
+</programlisting>
+
+ <para>
+ In this case, the plugin is not registered in
+ <literal>mysql.plugin</literal>. Restarting the server without
+ the <option role="mysqld">--plugin-load</option> option causes
+ the plugin not to be loaded at startup.
+ </para>
+
+ <para>
+ Alternatively, the <literal role="stmt">INSTALL PLUGIN</literal>
+ statement causes the server to load the plugin code from the
+ library file at runtime:
+ </para>
+
+<programlisting>
+mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
+</programlisting>
+
+ <para>
+ <literal role="stmt">INSTALL PLUGIN</literal> also causes
+ <quote>permanent</quote> plugin registration: The server lists
+ the plugin in the <literal>mysql.plugin</literal> table to
+ ensure that it is loaded on subsequent server restarts.
+ </para>
+
+ <para>
+ 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
+ <option role="mysqld">--plugin-load</option> rather than
+ <literal role="stmt">INSTALL PLUGIN</literal>.
+ </para>
+
+ <para>
+ While a plugin is loaded, information about it is available at
+ runtime from several sources, such as the
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
+ and the <literal role="stmt">SHOW PLUGINS</literal> statement.
+ For more information, see
+ <xref linkend="obtaining-plugin-information"/>.
+ </para>
+
+ <bridgehead id="server-plugin-activating">
+ Controlling Plugin Activation
+ </bridgehead>
+
+ <para>
+ If the server knows about a plugin when it starts (for example,
+ because the plugin is named using a
+ <option role="mysqld">--plugin-load</option> option or
+ registered in the <literal>mysql.plugin</literal> table), the
+ server loads and enables the plugin by default. It is possible
+ to control activation for such a plugin using a
+ <literal>--<replaceable>plugin_name</replaceable></literal>
+ startup option named after the plugin. In the following
+ descriptions, <replaceable>plugin_name</replaceable> stands for
+ a plugin name such as <literal>innodb</literal> or
+ <literal>csv</literal>. As with other options, dashes and
+ underscores are interchangeable in option names. For example,
+ <option>--my_plugin=1</option> and
+ <option>--my-plugin=1</option> are equivalent.
+ </para>
+
+ <para>
Options to load plugins are boolean options and are handled like
other boolean options (see <xref linkend="option-modifiers"/>).
That is, any of these options enable the plugin:
@@ -16335,8 +16578,9 @@
</programlisting>
<para>
- If a plugin is disabled, either explicitly, or implicitly
- because it was enabled but failed to initialize, aspects of
+ If a plugin is disabled, either explicitly with
+ <literal>OFF</literal> or implicitly because it was enabled with
+ <literal>ON</literal> 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
@@ -16347,23 +16591,50 @@
</para>
<para>
- Absence of a plugin may require adjustment to other options. For
+ Disabling a plugin may require adjustment to other options. For
example, if <literal role="se">InnoDB</literal> is disabled,
other <filename>innodb_<replaceable>xxx</replaceable></filename>
options likely will need to be omitted from the startup command.
- In addition, if the server would use
+ In addition, if the server is configured to use
<literal role="se">InnoDB</literal> as the default storage
- engine, it will not start unless you select another available
+ engine, it will not start unless you specify another available
storage engine with
<option role="mysqld">--default-storage-engine</option>.
</para>
+ <bridgehead id="server-plugin-uninstalling">
+ Uninstalling Plugins
+ </bridgehead>
+
<para>
- Plugins can also be loaded at runtime, using the
- <literal role="stmt">INSTALL PLUGIN</literal> statement. See
- <xref linkend="plugin-installing-uninstalling"/>.
+ A plugin known to the server can be uninstalled to disable it at
+ runtime with the <literal role="stmt">UNINSTALL PLUGIN</literal>
+ statement. The statement unloads the plugin and removes it from
+ the <literal>mysql.plugin</literal> table if it is registered
+ there. For this reason, <literal role="stmt">UNINSTALL
+ PLUGIN</literal> statement requires the
+ <literal role="priv">DELETE</literal> privilege for the
+ <literal>mysql.plugin</literal> table. With the plugin no longer
+ registered in the table, the server will not load the plugin
+ automatically for subsequent restarts.
</para>
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
+ plugins regardless of whether they were loaded with
+ <literal role="stmt">INSTALL PLUGIN</literal> or
+ <option role="mysqld">--plugin-load</option>.
+ </para>
+
+ <para>
+ <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
+ plugins that are built in to the server. These can be identified
+ as those that have a library name of <literal>NULL</literal> in
+ the output from
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
+ <literal role="stmt">SHOW PLUGINS</literal>.
+ </para>
+
</section>
<section id="obtaining-plugin-information">
Modified: trunk/refman-6.0/extending-mysql.xml
===================================================================
--- trunk/refman-6.0/extending-mysql.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/extending-mysql.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 4, Lines Added: 5, Lines Deleted: 78; 4084 bytes
@@ -2455,79 +2455,6 @@
</section>
- <section id="registering-plugins">
-
- <title>Registering Plugins with the Server</title>
-
- <para>
- Server plugins must be registered with the server before they
- can be used. You can load a plugin at server startup with the
- <option role="mysqld">plugin-load</option> option or at
- runtime with the <literal role="stmt">INSTALL PLUGIN</literal>
- statement.
- </para>
-
- <para>
- The <option role="mysqld">plugin-load</option> option installs
- a plugin at server startup. To install a plugin named
- <literal>myplugin</literal> in a plugin library file named
- <filename>somepluglib.so</filename>, use these lines in a
- <filename>my.cnf</filename> file:
- </para>
-
-<programlisting>
-[mysqld]
-plugin-load=myplugin=somepluglib.so
-</programlisting>
-
- <para>
- In this case, the plugin is not installed permanently.
- Restarting without the
- <option role="mysqld">plugin-load</option> option causes the
- plugin not to be loaded at startup.
- </para>
-
- <para>
- Alternatively, the <literal role="stmt">INSTALL
- PLUGIN</literal> statement causes the server to register the
- plugin and load the plugin code from the library file at
- runtime:
- </para>
-
-<programlisting>
-mysql> <userinput>INSTALL PLUGIN myplugin SONAME 'somepluglib.so';</userinput>
-</programlisting>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> causes
- <quote>permanent</quote> plugin registration: The server lists
- the plugin in the <literal>mysql.plugin</literal> table to
- ensure that it is loaded on subsequent server restarts.
- </para>
-
- <para>
- 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,
- <literal role="stmt">INSTALL PLUGIN</literal> is not
- appropriate and you must use
- <option role="mysqld">plugin-load</option>.
- </para>
-
- <para>
- To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
- </para>
-
- <para>
- For additional information about plugin loading, see
- <xref linkend="plugin-installing-uninstalling"/>.
- </para>
-
- </section>
-
<!--
<section id="writing-storage-engine-plugins">
@@ -3299,9 +3226,9 @@
<listitem>
<para>
To verify plugin installation, examine the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- or use the <literal role="stmt">SHOW PLUGINS</literal>
- statement.
+ <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal>
+ table or use the <literal role="stmt">SHOW
+ PLUGINS</literal> statement.
</para>
</listitem>
@@ -3555,7 +3482,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
@@ -4129,7 +4056,7 @@
</para>
<para>
- To verify plugin installation, examine the
+ To verify plugin installation, examine the
<literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
or use the <literal role="stmt">SHOW PLUGINS</literal>
statement.
Modified: trunk/refman-6.0/sql-syntax-server-administration.xml
===================================================================
--- trunk/refman-6.0/sql-syntax-server-administration.xml 2011-06-21 18:02:03 UTC (rev 26573)
+++ trunk/refman-6.0/sql-syntax-server-administration.xml 2011-06-21 18:02:15 UTC (rev 26574)
Changed blocks: 1, Lines Added: 0, Lines Deleted: 172; 6126 bytes
@@ -3516,178 +3516,6 @@
<title>Plugin and User-Defined Function Statements</title>
- <section id="plugin-installing-uninstalling">
-
- <title>Installing and Uninstalling Plugins</title>
-
- <indexterm>
- <primary>installing plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>installing</secondary>
- </indexterm>
-
- <indexterm>
- <primary>uninstalling plugins</primary>
- </indexterm>
-
- <indexterm>
- <primary>plugins</primary>
- <secondary>uninstalling</secondary>
- </indexterm>
-
- <para>
- This section compares the various methods of installing and
- uninstalling server plugins. See also
- <xref linkend="server-plugin-options"/>.
- </para>
-
- <para>
- <option role="mysqld">--plugin-load</option> option:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at server startup to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Does not register the plugin in
- <literal>mysql.plugin</literal>. For subsequent restarts,
- the server loads the plugin again only if
- <option role="mysqld">--plugin-load</option> is given again.
- That is, this option effects a one-time installation that
- persists only for one server invocation.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">INSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Loads the plugin code at runtime to enable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Registers the plugin in the <literal>mysql.plugin</literal>
- table. Registration causes the server to load the plugin
- automatically for subsequent restarts. That is, it effects
- an installation that persists until the plugin is
- uninstalled explicitly.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">INSERT</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> statement:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- Unloads the plugin code at runtime to disable it.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Unregisters the plugin from <literal>mysql.plugin</literal>
- if it is registered there. The server will not load it
- automatically for subsequent restarts.
- </para>
- </listitem>
-
- <listitem>
- <para>
- Requires the <literal role="priv">DELETE</literal> privilege
- for the <literal>mysql.plugin</literal> table.
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- While a plugin is loaded, information about it is available at
- runtime from several sources, such as the
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> table
- and the <literal role="stmt">SHOW PLUGINS</literal> statement.
- For more information, see
- <xref linkend="obtaining-plugin-information"/>.
- </para>
-
- <para>
- If <option role="mysqld">--plugin-load</option> is given at
- startup for a plugin already installed with
- <literal role="stmt">INSTALL PLUGIN</literal> during a previous
- server invocation, the server starts but writes these messages
- to the error log:
- </para>
-
-<programlisting>
-100310 19:15:44 [ERROR] Function '<replaceable>plugin_name</replaceable>' already exists
-100310 19:15:44 [Warning] Couldn't load plugin named '<replaceable>plugin_name</replaceable>'
-with soname '<replaceable>plugin_object_file</replaceable>'.
-</programlisting>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> can unload
- plugins regardless of whether they were loaded with
- <literal role="stmt">INSTALL PLUGIN</literal> or
- <option role="mysqld">--plugin-load</option>. In the latter
- case, <literal role="stmt">UNINSTALL PLUGIN</literal> does not
- unregister the plugin from <literal>mysql.plugin</literal>
- because <option role="mysqld">--plugin-load</option> did not
- register it.
- </para>
-
- <para>
- <literal role="stmt">UNINSTALL PLUGIN</literal> cannot unload
- plugins that are compiled into the server. (These can be
- identified as those that have a library name of
- <literal>NULL</literal> in the output from
- <literal role="is">INFORMATION_SCHEMA.PLUGINS</literal> or
- <literal role="stmt">SHOW PLUGINS</literal>.)
- </para>
-
- <para>
- If the server is started with the
- <option role="mysqld">--skip-grant-tables</option> option, it
- does not consult the <literal>mysql.plugins</literal> table and
- thus does not load plugins installed with the
- <literal role="stmt">INSTALL PLUGIN</literal> statement.
- <option role="mysqld">--plugin-load</option> enables plugins to
- be loaded even when
- <option role="mysqld">--skip-grant-tables</option> is given.
- <option role="mysqld">--plugin-load</option> also enables
- plugins to be loaded at startup under configurations when
- plugins cannot be loaded at runtime.
- </para>
-
- </section>
-
<section id="create-function-udf">
<title><literal role="stmt">CREATE FUNCTION</literal> Syntax for User-Defined
| Thread |
|---|
| • svn commit - mysqldoc@oter02: r26574 - in trunk: . refman-5.1 refman-5.5 refman-5.6 refman-6.0 | paul.dubois | 22 Jun |
