Author: mhillyer
Date: 2005-12-18 06:19:53 +0100 (Sun, 18 Dec 2005)
New Revision: 587
Log:
Add docs on building storage engine, testing storage engine. Also change a couple of notes in the pluggable chapter.
Modified:
branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
trunk/refman-5.1/pluggable-storage.xml
Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
===================================================================
--- branches/MikePluggable/trunk/refman-5.1/custom-engine.xml 2005-12-18 00:35:15 UTC (rev 586)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml 2005-12-18 05:19:53 UTC (rev 587)
@@ -2888,6 +2888,343 @@
</section>
+ <section id="custom-engine-build">
+
+ <title>Building and Testing Pluggable Storage Engines</title>
+
+ <para>
+ With MySQL 5.1 it is possible to build storage engines as shared
+ objects that can be loaded dynamically into a running MySQL
+ server. This new approach makes it easier to deploy custom storage
+ engines because it is no longer necessary to re-compile the MySQL
+ server to install or upgrade a storage engine.
+ </para>
+
+ <para>
+ Building and testing a pluggable storage engine requires some
+ modifications to be made to your storage engine source files,
+ along with the creation of a specialized Makefile.
+ </para>
+
+ <section id="custom-engine-build-source">
+
+ <title>Source Modifications Required to Build a Pluggable Storage Engine</title>
+
+ <para>
+ When building a pluggable storage engine, avoid using symbol
+ names that already exist in the <literal>mysqld</literal> source
+ code. This can be as simple as prepending all symbol names with
+ the name of your storage engine.
+ </para>
+
+ <para>
+ The following line must be added to the start of your
+ <filename><replaceable>storage-engine</replaceable>.cc</filename>
+ file:
+ </para>
+
+<programlisting>
+#include <plugins.h>
+</programlisting>
+
+ <para>
+ The <filename>plugins.h</filename> file contains declarations
+ related to the MySQL plugin framework.
+ </para>
+
+ <para>
+ Additionally, the following macro must be appended to your
+ <filename><replaceable>storage-engine</replaceable>.cc</filename>
+ file:
+ </para>
+
+<programlisting>
+mysql_declare_plugin
+{
+ MYSQL_STORAGE_ENGINE_PLUGIN,
+ &tina_hton,
+ tina_hton.name,
+ "MySQL AB",
+ "CSV Storage Engine",
+ tina_init_func, /* Plugin Init */
+ tina_done_func /* Plugin Deinit */
+}
+mysql_declare_plugin_end;
+</programlisting>
+
+ <para>
+ The preceding example is from the <literal>CSV</literal> storage
+ engine.
+ </para>
+
+ <para>
+ The first element in the macro declares that this plugin is a
+ storage engine. The second element is a pointer to the storage
+ engine's
+ <link
+ linkend="custom-engine-handlerton">handlerton</link>.
+ The third element is the name of the plugin. The fourth element
+ is the author of the plugin. The fifth element is a description
+ of the plugin.
+ </para>
+
+ <para>
+ The <function>init</function> function performs any static
+ initialization required for the plugin, such as creating mutexes
+ and other internal structures.
+ </para>
+
+ <para>
+ The <function>done</function> function is used to free all
+ resources used by the plugin.
+ </para>
+
+ <para>
+ The storage engine should have a <function>panic</function>
+ function declared in its
+ <link linkend="custom-engine-handlerton">handlerton</link>. Upon
+ shutdown of <literal>mysqld</literal>, the panic function is
+ usually passed an argument of value
+ <literal>HA_PANIC_CLOSE</literal>, where the storage engine
+ should close all open tables. However, if the storage engine is
+ a pluggable, and the user attempts to un-install a storage
+ engine at runtime, the value of the panic argument will be
+ <literal>HA_PANIC_TRY_CLOSE</literal>. If the storage engine has
+ any open handler instances, it should return a nonzero fail
+ value, otherwise it should close all files and perform any
+ necessary cleanup.
+ </para>
+
+ <para>
+ In the case of a pluggable storage engine, returning a nonzero
+ value from the handlerton <function>init</function> function
+ does not prevent the storage engine shared library from being
+ loaded -- only the failure of the plugin
+ <function>init</function> function can prevent loading. However,
+ if the handlerton <function>init</function> function returns
+ failure, then the storage engine will be installed in the
+ <literal>DISABLED</literal> state.
+ </para>
+
+ </section>
+
+ <section id="custom-engine-build-makefile">
+
+ <title>Creating a Makefile to Build a Custom Storage Engine</title>
+
+ <para>
+ A <filename>Makefile.am</filename> file can be created for your
+ custom storage engine using <command>Libtool</command>. The
+ following sample Makefile is for the pluggable version of the
+ <literal>CSV</literal> engine:
+ </para>
+
+<programlisting>
+MYSQLDATAdir = $(localstatedir)
+MYSQLSHAREdir = $(pkgdatadir)
+MYSQLBASEdir= $(prefix)
+MYSQLLIBdir= $(pkglibdir)
+INCLUDES = -I$(top_srcdir)/include \
+ -I$(top_srcdir)/regex \
+ -I$(top_srcdir)/sql \
+ -I$(srcdir)
+WRAPLIBS=
+
+lib_LTLIBRARIES = libhacsv.la
+
+libhacsv_la_SOURCES = ha_tina.cc
+
+LDADD =
+
+DEFS = -DMYSQL_SERVER @DEFS@
+
+# Don't update the files from bitkeeper %::SCCS/s.%
+</programlisting>
+
+ </section>
+
+ <section id="custom-engine-build-buildobject">
+
+ <title>Building a Shared Object</title>
+
+ <para>
+ Once the Makefile is created, use the following steps to build a
+ pluggable shared object:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Navigate to the directory containing
+ <filename>Makefile.am</filename>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Type <command>make</command> to compile the shared object.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Type <command>make install</command> to install the shared
+ object into the MySQL server's library directory.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ </section>
+
+ <section id="custom-engine-install">
+
+ <title>Installing a Custom Storage Engine</title>
+
+ <para>
+ Once your storage engine is built, ensure the
+ <filename>.so</filename> file is in the MySQL server library
+ directory (typically <filename>installdir/lib</filename>).
+ </para>
+
+ <para>
+ To install the plugin, issue the <literal>INSTALL
+ PLUGIN</literal> command:
+ </para>
+
+<programlisting>
+INSTALL PLUGIN <replaceable>ha_foo</replaceable> SONAME
+ '<replaceable>ha_foo.so</replaceable>';
+</programlisting>
+
+ </section>
+
+ <section id="custom-engine-uninstall">
+
+ <title>Uninstalling a Custom Storage Engine</title>
+
+ <para>
+ To uninstall a storage engine, use the <literal>UNINSTALL
+ PLUGIN</literal> statement:
+ </para>
+
+<programlisting>
+UNINSTALL PLUGIN <replaceable>ha_foo</replaceable>;
+</programlisting>
+
+ <para>
+ If you uninstall a storage engine that is being used by existing
+ tables, those tables will not be accessible, but will still be
+ present on disk (where applicable). Ensure that there are no
+ tables using a given storage engine before uninstalling it
+ otherwise the table will be inaccessible unless you re-install
+ the storage engine.
+ </para>
+
+ </section>
+
+ <section id="custom-engine-testing">
+
+ <title>Testing a Custom Storage Engine</title>
+
+ <para>
+ The MySQL AB development team follows a test-driven approach for
+ storage engine development: as functionality is developed and
+ bugs are fixed, new tests are added to an extensive regression
+ testing suite to ensure that new functionality works properly
+ and old bugs are not re-introduced.
+ </para>
+
+ <para>
+ Developers of custom storage engines can use the same regression
+ test suite to ensure the reliable operation of their storage
+ engine.
+ </para>
+
+ <para>
+ For more information on the MySQL Test Suite, see
+ <xref linkend="mysql-test-suite"/>.
+ </para>
+
+ <section id="custom-engine-testing-testrun">
+
+ <title>Running the Regression Test Suite</title>
+
+ <para>
+ To run the test suite follow these steps:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ From the MySQL main directory tree change directory to the
+ <filename>mysql-test</filename> directory.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Run <command>perl ./mysql-test-run.pl</command>.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Running the script without options executes the complete test
+ suite on a server running on the local machine.
+ </para>
+
+ <para>
+ In order to run a subset of tests or a specific test case,
+ execute <command>perl ./mysql-test-run.pl
+ --do-test=abc</command>.This will execute all tests that start
+ with <literal>abc</literal> (<literal>abc*.test</literal>).
+ </para>
+
+ <para>
+ For a complete list of options run <command>perl
+ ./mysql-test-run.pl --help</command>.
+ </para>
+
+ </section>
+
+ <section id="custom-engine-testing-custom">
+
+ <title>Customizing Test Script for Custom Engine Use</title>
+
+ <para>
+ The existing tests in the MySQL Test Suite are typically
+ created against specific storage engines. As such, running the
+ full test suite will not result in custom storage engines
+ being tested.
+ </para>
+
+ <para>
+ To add support for your storage engine to the test suite, you
+ must first write tests against your storage engine. The
+ simplest way to do this is to take an existing test script and
+ modify the <literal>CREATE TABLE</literal> statements within
+ to use your custom engine.
+ </para>
+
+ <para>
+ Tests are located in the <filename>mysql-test/t/</filename>.
+ </para>
+
+ <para>
+ For more information on creating and modifying tests, see
+ <xref linkend="extending-mysqltest"/>.
+ </para>
+
+ </section>
+
+ </section>
+
+ </section>
+
<section id="custom-engine-api-reference">
<title>API Reference</title>
Modified: trunk/refman-5.1/pluggable-storage.xml
===================================================================
--- trunk/refman-5.1/pluggable-storage.xml 2005-12-18 00:35:15 UTC (rev 586)
+++ trunk/refman-5.1/pluggable-storage.xml 2005-12-18 05:19:53 UTC (rev 587)
@@ -1,13 +1,13 @@
<?xml version='1.0' encoding='utf-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
- <!ENTITY % fixedchars.entities SYSTEM "../refman-common/fixedchars.ent">
- %fixedchars.entities;
- <!ENTITY % title.entities SYSTEM "../refman-common/titles.en.ent">
- %title.entities;
- <!ENTITY % versions.entities SYSTEM "versions.ent">
- %versions.entities;
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+ <!ENTITY % fixedchars.entities SYSTEM "../refman-common/fixedchars.ent">
+ %fixedchars.entities;
+ <!ENTITY % title.entities SYSTEM "../refman-common/titles.en.ent">
+ %title.entities;
+ <!ENTITY % versions.entities SYSTEM "versions.ent">
+ %versions.entities;
]>
<chapter id="pluggable-storage">
@@ -357,10 +357,10 @@
<literal>ENGINE</literal> parameter:
</para>
-<programlisting>
-CREATE TABLE engineTest(
-id INT
-) ENGINE = MyISAM;
+<programlisting>
+CREATE TABLE engineTest(
+id INT
+) ENGINE = MyISAM;
</programlisting>
<para>
@@ -368,8 +368,8 @@
<literal>ALTER TABLE</literal> statement:
</para>
-<programlisting>
-ALTER TABLE <replaceable>engineTest</replaceable> ENGINE = <replaceable>ARCHIVE</replaceable>;
+<programlisting>
+ALTER TABLE <replaceable>engineTest</replaceable> ENGINE = <replaceable>ARCHIVE</replaceable>;
</programlisting>
</section>
@@ -421,8 +421,8 @@
engine you would first load the ha_example.so module:
</para>
-<programlisting>
-INSTALL PLUGIN <replaceable>ha_example</replaceable> SONAME '<replaceable>ha_example.so</replaceable>';
+<programlisting>
+INSTALL PLUGIN <replaceable>ha_example</replaceable> SONAME '<replaceable>ha_example.so</replaceable>';
</programlisting>
<para>
@@ -442,13 +442,14 @@
PLUGIN</literal> statement:
</para>
-<programlisting>
-UNINSTALL PLUGIN <replaceable>ha_example</replaceable>;
+<programlisting>
+UNINSTALL PLUGIN <replaceable>ha_example</replaceable>;
</programlisting>
<para>
If you unplug a storage engine that is being used by existing
- tables, those tables will not be accessible. Ensure that there are
+ tables, those tables will not be accessible, but will still be
+ present on disk (where applicable). Ensure that there are
no tables using a storage engine before you unplug the storage
engine.
</para>
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r587 - branches/MikePluggable/trunk/refman-5.1 trunk/refman-5.1 | mhillyer | 18 Dec |
