From: mhillyer
Date: December 18 2005 5:19am
Subject: svn commit - mysqldoc@docsrva: r587 - branches/MikePluggable/trunk/refman-5.1 trunk/refman-5.1
List-Archive: http://lists.mysql.com/commits/217
Message-Id: <200512180519.jBI5JtIR011969@docsrva.mysql.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
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 @@
+
+
+ Building and Testing Pluggable Storage Engines
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+
+ Source Modifications Required to Build a Pluggable Storage Engine
+
+
+ When building a pluggable storage engine, avoid using symbol
+ names that already exist in the mysqld source
+ code. This can be as simple as prepending all symbol names with
+ the name of your storage engine.
+
+
+
+ The following line must be added to the start of your
+ storage-engine.cc
+ file:
+
+
+
+#include <plugins.h>
+
+
+
+ The plugins.h file contains declarations
+ related to the MySQL plugin framework.
+
+
+
+ Additionally, the following macro must be appended to your
+ storage-engine.cc
+ file:
+
+
+
+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;
+
+
+
+ The preceding example is from the CSV storage
+ engine.
+
+
+
+ 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
+ handlerton.
+ 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.
+
+
+
+ The init function performs any static
+ initialization required for the plugin, such as creating mutexes
+ and other internal structures.
+
+
+
+ The done function is used to free all
+ resources used by the plugin.
+
+
+
+ The storage engine should have a panic
+ function declared in its
+ handlerton. Upon
+ shutdown of mysqld, the panic function is
+ usually passed an argument of value
+ HA_PANIC_CLOSE, 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
+ HA_PANIC_TRY_CLOSE. 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.
+
+
+
+ In the case of a pluggable storage engine, returning a nonzero
+ value from the handlerton init function
+ does not prevent the storage engine shared library from being
+ loaded -- only the failure of the plugin
+ init function can prevent loading. However,
+ if the handlerton init function returns
+ failure, then the storage engine will be installed in the
+ DISABLED state.
+
+
+
+
+
+
+ Creating a Makefile to Build a Custom Storage Engine
+
+
+ A Makefile.am file can be created for your
+ custom storage engine using Libtool. The
+ following sample Makefile is for the pluggable version of the
+ CSV engine:
+
+
+
+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.%
+
+
+
+
+
+
+ Building a Shared Object
+
+
+ Once the Makefile is created, use the following steps to build a
+ pluggable shared object:
+
+
+
+
+
+
+ Navigate to the directory containing
+ Makefile.am.
+
+
+
+
+
+ Type make to compile the shared object.
+
+
+
+
+
+ Type make install to install the shared
+ object into the MySQL server's library directory.
+
+
+
+
+
+
+
+
+
+ Installing a Custom Storage Engine
+
+
+ Once your storage engine is built, ensure the
+ .so file is in the MySQL server library
+ directory (typically installdir/lib).
+
+
+
+ To install the plugin, issue the INSTALL
+ PLUGIN command:
+
+
+
+INSTALL PLUGIN ha_foo SONAME
+ 'ha_foo.so';
+
+
+
+
+
+
+ Uninstalling a Custom Storage Engine
+
+
+ To uninstall a storage engine, use the UNINSTALL
+ PLUGIN statement:
+
+
+
+UNINSTALL PLUGIN ha_foo;
+
+
+
+ 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.
+
+
+
+
+
+
+ Testing a Custom Storage Engine
+
+
+ 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.
+
+
+
+ Developers of custom storage engines can use the same regression
+ test suite to ensure the reliable operation of their storage
+ engine.
+
+
+
+ For more information on the MySQL Test Suite, see
+ .
+
+
+
+
+ Running the Regression Test Suite
+
+
+ To run the test suite follow these steps:
+
+
+
+
+
+
+ From the MySQL main directory tree change directory to the
+ mysql-test directory.
+
+
+
+
+
+ Run perl ./mysql-test-run.pl.
+
+
+
+
+
+
+ Running the script without options executes the complete test
+ suite on a server running on the local machine.
+
+
+
+ In order to run a subset of tests or a specific test case,
+ execute perl ./mysql-test-run.pl
+ --do-test=abc.This will execute all tests that start
+ with abc (abc*.test).
+
+
+
+ For a complete list of options run perl
+ ./mysql-test-run.pl --help.
+
+
+
+
+
+
+ Customizing Test Script for Custom Engine Use
+
+
+ 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.
+
+
+
+ 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 CREATE TABLE statements within
+ to use your custom engine.
+
+
+
+ Tests are located in the mysql-test/t/.
+
+
+
+ For more information on creating and modifying tests, see
+ .
+
+
+
+
+
+
+
+
API Reference
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 @@
-
- %fixedchars.entities;
-
- %title.entities;
-
- %versions.entities;
+
+ %fixedchars.entities;
+
+ %title.entities;
+
+ %versions.entities;
]>
@@ -357,10 +357,10 @@
ENGINE parameter:
-
-CREATE TABLE engineTest(
-id INT
-) ENGINE = MyISAM;
+
+CREATE TABLE engineTest(
+id INT
+) ENGINE = MyISAM;
@@ -368,8 +368,8 @@
ALTER TABLE statement:
-
-ALTER TABLE engineTest ENGINE = ARCHIVE;
+
+ALTER TABLE engineTest ENGINE = ARCHIVE;
@@ -421,8 +421,8 @@
engine you would first load the ha_example.so module:
-
-INSTALL PLUGIN ha_example SONAME 'ha_example.so';
+
+INSTALL PLUGIN ha_example SONAME 'ha_example.so';
@@ -442,13 +442,14 @@
PLUGIN statement:
-
-UNINSTALL PLUGIN ha_example;
+
+UNINSTALL PLUGIN ha_example;
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.