diff --git a/reference/mysqlinfo/set.xml b/reference/mysqlinfo/set.xml index 335e37739c..ab63bc7033 100644 --- a/reference/mysqlinfo/set.xml +++ b/reference/mysqlinfo/set.xml @@ -503,5 +503,6 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq &reference.mysqlnd-qc.book; &reference.mysqlnd-uh.book; &reference.mysqlnd-mux.book; + &reference.mysqlnd-memcache.book; diff --git a/reference/mysqlnd_memcache/book.xml b/reference/mysqlnd_memcache/book.xml new file mode 100644 index 0000000000..0c3d8d3273 --- /dev/null +++ b/reference/mysqlnd_memcache/book.xml @@ -0,0 +1,150 @@ + + + + + Mysqlnd Memache plugin + mysqlnd_memcache + + + &reftitle.intro; + + The mysqlnd memcache plugin (mysqlnd_memcache) is an PHP + extension for transparently translating SQL into requests for the + MySQL InnoDB Memcached Daemon Plugin (server plugin). It includes + experimental support for the MySQL Cluster Memcached Daemon. The server + plugin provides access to data stored inside MySQL InnoDB (respectively + MySQL Cluster NDB) tables using the Memcache protocol. + This PHP extension, which supports all PHP MySQL extensions that use + mysqlnd, will identify tables exported in + this way and will translate specific SELECT queries into Memcache requests. + + + mysqlnd_memcache data flow + + + + + + + This plugin depends on the MySQL InnoDB Memcached Daemon Plugin. It is not + provided to be used with a stand-alone Memcached. For a generic query cache + using Memcached look at the mysqlnd query + cache plugin. For direct Memcache access look at the + memcache and + memcached extensions. + + + + The MySQL native driver for PHP is a C library that ships together with + PHP as of PHP 5.3.0. It serves as a drop-in replacement for the + MySQL Client Library (libmysql/libmysqlclient). Using mysqlnd has + several advantages: no extra downloads are required because it's bundled with PHP, + it's under the PHP license, there is lower memory consumption in certain cases, and + it contains new functionality such as asynchronous queries. + + + The mysqlnd_mmemcache operates, for the most part, + transparently from a user perspective. The mysqlnd memcache + plugin supports all PHP applications, and all MySQL PHP extensions. + It does not change existing APIs. Therefore, it can easily be used with + existing PHP applications. + + + The MySQL Memcache plugins add key-value style access method for data stored + in InnoDB resp. NDB (MySQL Cluster) SQL tables through the Memcache protocol. + This type of key-value access if often faster than using SQL. + +
+ Key Features + + The key features of PECL/mysqlnd_memcache are as follows. + + + + + + Possible performance benefits + + + + + + Client-side: light-weight protocol. + + + + + Server-side: no SQL parsing, direct access to the storage. + + + + + Please, run your own benchmarks! Actual performance results are + highly dependent on setup and hardware used. + + + + + + + +
+ +
+ Limitations + + The initial version is not binary safe. Due to the way the MySQL Memcache + plugins works there are restrictions related to separators. + + + Prepared statements and asynchronous queries are not supported. Result set + meta data support is limited. + + + The mapping information for tables accessible via Memcache is not cached + in the plugin between requests but fetched from the MySQL server each time + a MySQL connection is associated with a Memcache connection. See + mysqlnd_memcache_set for details. + +
+ +
+ On the name + + The shortcut mysqlnd_memcache + stands for mysqlnd memcache plugin. + Memcache refers to support of the MySQL Memcache plugins + for InnoDB and NDB (MySQL Cluster). The plugin is not + related to the Memcached cache server. + +
+ + + &reference.mysqlnd-memcache.quickstart; + &reference.mysqlnd-memcache.setup; + &reference.mysqlnd-memcache.constants; + &reference.mysqlnd-memcache.reference; + &reference.mysqlnd-memcache.changes; + + + + diff --git a/reference/mysqlnd_memcache/changes.xml b/reference/mysqlnd_memcache/changes.xml new file mode 100644 index 0000000000..9db05cab33 --- /dev/null +++ b/reference/mysqlnd_memcache/changes.xml @@ -0,0 +1,61 @@ + + + + + Change History + + This change history is a high level summary of selected changes + that may impact applications and/or break backwards compatibility. + + + See also the CHANGES file in the source distribution + for a complete list of changes. + + +
+ PECL/mysqlnd_memcache 1.0 series + + 1.0.0-alpha + + + + Release date: TBD + + + + + Motto/theme: Basic mapping of SQL SELECT to a MySQL Memcache plugin access. + + + + + + The initial release does map basic SQL SELECT statements to a MySQL Memcache plugin + access. This bares potential performance benefits as the direct + key-value access to MySQL storage using the Memcache protocol is usually + faster than using SQL access. + +
+ + + + diff --git a/reference/mysqlnd_memcache/configure.xml b/reference/mysqlnd_memcache/configure.xml new file mode 100644 index 0000000000..352104f58a --- /dev/null +++ b/reference/mysqlnd_memcache/configure.xml @@ -0,0 +1,42 @@ + + + +
+ &reftitle.install; + + + &pecl.moved; + + + + &pecl.info; + &url.pecl.package;mysqlnd_memcache + + + + &pecl.windows.download; + + +
+ + + diff --git a/reference/mysqlnd_memcache/constants.xml b/reference/mysqlnd_memcache/constants.xml new file mode 100644 index 0000000000..ad8edb3e85 --- /dev/null +++ b/reference/mysqlnd_memcache/constants.xml @@ -0,0 +1,123 @@ + + + + + &reftitle.constants; + &extension.constants; + + + MySQL Memcache Plugin related + + + + + + MYSQLND_MEMCACHE_DEFAULT_REGEXP + (string) + + + + Default regular expression (pcre style) used for matching SELECT + statements that shall be mapped into a MySQL Memcache Plugin + access, if possible. + + + It is possible to use a different but the defailt regular expression for pattern + matching. See also mysqlnd_memcache_set. + + + + + + + + Assorted + + + The plugins version number can be obtained using + MYSQLND_MEMCACHE_VERSION or + MYSQLND_MEMCACHE_VERSION_ID. + MYSQLND_MEMCACHE_VERSION + is the string representation of the numerical version number + MYSQLND_MEMCACHE_VERSION_ID, which is an integer such as 10000. + Developers can calculate the version number as follows. + + + + + + + Version (part) + Example + + + + + Major*10000 + 1*10000 = 10000 + + + Minor*100 + 0*100 = 0 + + + Patch + 0 = 0 + + + MYSQLND_MEMCACHE_VERSION_ID + 10000 + + + + + + + + + + MYSQLND_MEMCACHE_VERSION + (string) + + + + Plugin version string, for example, 1.0.0-alpha. + + + + + + MYSQLND_MEMCACHE_VERSION_ID + (integer) + + + + Plugin version number, for example, 10000. + + + + + + + + + diff --git a/reference/mysqlnd_memcache/figures/mymemflow.dot b/reference/mysqlnd_memcache/figures/mymemflow.dot new file mode 100644 index 0000000000..a69de553d8 --- /dev/null +++ b/reference/mysqlnd_memcache/figures/mymemflow.dot @@ -0,0 +1,32 @@ +/* +Render using +$ dot -Tpng -ofigures/mymemflow.png figures/mymemflow.dot +*/ +graph mymemflow { + rankdir=LR + node [shape=box] + + subgraph clusterPHP { + rankdir=LR + label="PHP" + extmysql [label="ext/mysql"] + extmysql -- mysqlnd_memcache + mysqli -- mysqlnd_memcache + pdo -- mysqlnd_memcache + + subgraph clusterMysqlnd { + label=mysqlnd + mysqlnd_memcache [color=blue] + } + } + + subgraph clusterMySQL { + label="MySQL Server" + color=black + sqlengine [label="SQL Engine"] + innoplugin [label="InnoDB Memcache Daemon" color=blue] + } + + mysqlnd_memcache -- innoplugin [label="memcache protocol" color=blue] + mysqlnd_memcache -- sqlengine [label="MySQL Protocol"] +} diff --git a/reference/mysqlnd_memcache/figures/mymemflow.png b/reference/mysqlnd_memcache/figures/mymemflow.png new file mode 100644 index 0000000000..328d66c138 Binary files /dev/null and b/reference/mysqlnd_memcache/figures/mymemflow.png differ diff --git a/reference/mysqlnd_memcache/functions/mysqlnd-memcache-get-config.xml b/reference/mysqlnd_memcache/functions/mysqlnd-memcache-get-config.xml new file mode 100644 index 0000000000..e50ab3e41b --- /dev/null +++ b/reference/mysqlnd_memcache/functions/mysqlnd-memcache-get-config.xml @@ -0,0 +1,272 @@ + + + + + + mysqlnd_memcache_get_config + Returns information about the plugin configuration + + + + &reftitle.description; + + array + mysqlnd_memcache_get_config + mixedconnection + + + This function returns an array containing all the mysqlnd_memcache related + configuration attached to a MySQL connection. This includes MySQL the + Memcache object provided via mysqlnd_memcache_set + as well as the table mapping configuration which was automatically collected + from the MySQL server. + + + + + &reftitle.parameters; + + + connection + + + A handle to a MySQL server of the type + PDO_MYSQL, mysqli or + ext/mysql for which the configuration is to + be returned. + + + + + + + + &reftitle.returnvalues; + + If the connection is associated with a memcache connection an array will + be returned. Otherwise this function will return false. + + + The returned array has these elements: + + + + mysqlnd_memcache_get_config array structure + + + + Array Key + Description + + + + + memcached + + Instance of Memcached associated to this MySQL connection + by mysqlnd_memcache_set. You can use this to + change settings of the memcache connection or directly querying the + server onthis connection. + + + + pattern + + Regular expression used to match an SQL query being sent to the server. + Queries matching this pattern will be further analyzed to decide whether + the query can be intercepted and sent via the memcache interface or + whether the query is sent using the general MySQL protocol to the + server. The pattern either is the default pattern, + MYSQLND_MEMCACHE_DEFAULT_REGEXP or set via + mysqlnd_memcache_set. + + + + mappings + + An associative array with a list of all configured containers as they + were discovered by this plugin. The key for these elements is the name + of the container in the MySQL configuration. The value is described + below. The contents of this field is created by querying the MySQL + server during associting a MySQL and a memcache connection using + mysqlnd_memcache_set. + + + + mapping_query + An SQL query used during + mysqlnd_memcache_set + to identify the available containers and mappings. The result of that + query is provided in the mappings element. + + + + +
+ + Mapping entry structure + + + + Array Key + Description + + + + + prefix + + A prefix used while accessing data via memcache. With the MySQL InnoDB + Memcache Deamon plugin this usully begins with @@ and ends with a + configurable separator. This prefix is placed in front of the key value + while using the memcache protocol. + + + + schema_name + + Name of the schema (database) which contains the table being accessed. + + + + table_name + + Name of the table which contins the data accessible via memcache + protocol. + + + + id_field_name + + Name of the database field (column) with the id used as key when + accessing the table vi a memcache. Often this is the database field + having a primary key. + + + + separator + + A seprator used to split different field values. This is needed as + memcache only provides access to a single value while MySQL can map + multiple columns to this value. + + + The separator, which can be set in the MySQL Server configuration + should not be part ofany value retrieved via memcache as proper + mapping can't be guranteed. + + + + + + fields + + An array with the names of all fields availle forthis mapping. + + + + +
+ + + + + &reftitle.examples; + + + <function>mysqlnd_memcache_get_config</function> example + +addServer("host", 11211); +mysqlnd_memcache_set($mysqli, $memc); + +var_dump(mysqlnd_memcache_get_config($mysqli)); +?> +]]> + + &example.outputs; + + + object(Memcached)#2 (0) { + } + ["pattern"]=> + string(125) "/^\s*SELECT\s*(.+?)\s*FROM\s*`?([a-z0-9_]+)`?\s*WHERE\s*`?([a-z0-9_]+)`?\s*=\s*(?(?=["'])["']([^"']*)["']|([0-9e\.]*))\s*$/is" + ["mappings"]=> + array(1) { + ["mymem_test"]=> + array(6) { + ["prefix"]=> + string(13) "@@mymem_test." + ["schema_name"]=> + string(4) "test" + ["table_name"]=> + string(10) "mymem_test" + ["id_field_name"]=> + string(2) "id" + ["separator"]=> + string(1) "|" + ["fields"]=> + array(3) { + [0]=> + string(2) "f1" + [1]=> + string(2) "f2" + [2]=> + string(2) "f3" + } + } + } + ["mapping_query"]=> + string(209) " SELECT c.name, + CONCAT('@@', c.name, (SELECT value FROM innodb_memcache.config_options WHERE name = 'table_map_delimiter')) AS key_prefix, + c.db_schema, + c.db_table, + c.key_columns, + c.value_columns, + (SELECT value FROM innodb_memcache.config_options WHERE name = 'separator') AS sep + FROM innodb_memcache.containers c" +} +]]> + + + + + + + &reftitle.seealso; + + + + mysqlnd_memcache_set + + + + + + + + diff --git a/reference/mysqlnd_memcache/functions/mysqlnd-memcache-set.xml b/reference/mysqlnd_memcache/functions/mysqlnd-memcache-set.xml new file mode 100644 index 0000000000..d21bcfdbe5 --- /dev/null +++ b/reference/mysqlnd_memcache/functions/mysqlnd-memcache-set.xml @@ -0,0 +1,175 @@ + + + + + + mysqlnd_memcache_set + Associate a MySQL connection with a Memcache connection + + + + &reftitle.description; + + bool + mysqlnd_memcache_set + mixedmysql_connection + Memcachedmemcache_connection + stringpattern + callbackcallback + + + Associate mysql_connection with + memcache_connection using pattern + as decision Regexp and callback as notification + callback or unset the association of mysql_connection. + + + While associating a MySQL connection with a Memcache connection this function + will query the MySQL server for its configuration. It will automatically + detect whether the server is configured to use the InnoDB Memcache Daemon + Plugin or MySQL Cluster NDB Memcache support. It will also query the server + to automatically identify exported tables and other configuration options. + The results of this automatic configuration can be retrieved using + mysqlnd_memcache_get_config. + + + + + &reftitle.parameters; + + + mysql_connection + + + A handle to a MySQL server of the type + PDO_MYSQL, mysqli or + ext/mysql for which the configuration is to + be set. + + + + + memcache_connection + + + A Memcached instance with an + connection to the MySQL Memcache Daemon plugin. If this parameter + is ommitted mysql_connection will be unassociated + from any memcache connection. If a previous association exists it will be + replaced. + + + + + pattern + + + A regular expression in Perl Compatible + Regular Expression syntax used to identify potential + Memcache-queries. The query should have three sub patterns. The + first subpattern contains the requested field list, the second the name + of the ID column from the query and the third the requested value. If + this parameteris ommitted or set to &null; a default + pattern will be used. + + + + + callback + + + A callback which will be used whenever a query is being sent to + MySQL. The callback will receive a single &boolean; parameter + telling if a query was sent via Memcache. + + + + + + + + &reftitle.returnvalues; + + If the association or disassociation succeds the function returns &true;. In + case of an error &false; is being returned. + + + + + &reftitle.examples; + + + + <function>mysqlnd_memcache_set</function> example with + <function>var_dump</function> as simple debugging callabck. + + +addServer("host", 11211); +mysqlnd_memcache_set($mysqli, $memc, NULL, 'var_dump'); + +/* This query will be intercepted and executed via Memcache protocol */ +echo "Sending query for id via Memcache: "; +$mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1"); + +/* f1 is not configured as valid key field, this won't be sent via Memcache */ +echo "Sending query for f1 via Memcache: "; +$mysqli->query("SELECT id FROM test WHERE f1 = 1"); + +mysqlnd_memcache_set($mysqli); + +/* Now the regular MySQL protocol will be used */ +echo "var_dump won't be invoked: "; +$mysqli->query("SELECT f1, f2, f3 WHERE id = 1"); + +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + + mysqlnd_memcache_get_config + + + + + + + + diff --git a/reference/mysqlnd_memcache/ini.xml b/reference/mysqlnd_memcache/ini.xml new file mode 100644 index 0000000000..cc1501d06c --- /dev/null +++ b/reference/mysqlnd_memcache/ini.xml @@ -0,0 +1,82 @@ + + + +
+ &reftitle.runtime; + &extension.runtime; + + + Mysqlnd_memcache &ConfigureOptions; + + + + &Name; + &Default; + &Changeable; + &Changelog; + + + + + mysqlnd_memcache.enable + 1 + PHP_INI_SYSTEM + + + + +
+ + + &ini.descriptions.title; + + + + + + + mysqlnd_memcache.enable + integer + + + + Enables or disables the plugin. If disabled, the extension will not plug + into + mysqlnd to proxy internal + mysqlnd C API calls. + + + This option is mostly meant to be used by developers building this + extension static into PHP. In general users are encouraged to build + this extension as shared object and unloading it completely if not + needed. + + + + + + + + +
+ + diff --git a/reference/mysqlnd_memcache/quickstart.xml b/reference/mysqlnd_memcache/quickstart.xml new file mode 100644 index 0000000000..987b6afd73 --- /dev/null +++ b/reference/mysqlnd_memcache/quickstart.xml @@ -0,0 +1,187 @@ + + + + Quickstart and Examples + + The mysqlnd memcache plugin is easy to use. + This quickstart will demo typical use-cases, and provide practical advice on getting + started. + + + It is strongly recommended to read the reference sections in addition to the + quickstart. The quickstart tries to avoid discussing theoretical concepts + and limitations. Instead, it will link to the reference sections. It is safe + to begin with the quickstart. However, before using the plugin in mission critical + environments we urge you to read additionally the background information from the + reference sections. + +
+ Setup + + The plugin is implemented as a PHP extension. See also the + installation instructions to + install the + mysqlnd_memcache extension. + + + Compile or configure the PHP MySQL extension (API) (mysqli, + PDO_MYSQL, + mysql) that you plan to use with support + for the mysqlnd library. mysqlnd_memcache + is a plugin for the mysqlnd library. To use the plugin with any of the PHP + MySQL extensions, the extension has to use the mysqlnd library. + + + The mysqlnd_memcche PHP extension depends on the + memcached extension. Refer to the + according installation + instructions for installing that module. + + + Then, load this extension into PHP and activate the plugin in the PHP configuration + file using the PHP configuration directive named + mysqlnd_memcache.enable. + + + + Enabling the plugin (php.ini) + + + + + + + Follow the instructions given in the MySQL Reference Manual on installing + the Memcache plugins for the MySQL server. Activate the plugins and + configure the Memcache access to SQL tables. + + + For all future examples it is assumed that you have created a SQL table + like the following and configured Memcache access to it. + + + + SQL table used for the Quickstart + + + + + +
+
+ Usage + + After associating a MySQL connection with a Memcache connection using + mysqnd_memcache_set the plugin attempts to transparently + replace SQL SELECT + statements by a memcache access. For that purpose the plugin monitors + all SQL statements executed and tries to match the statement string + against MYSQLND_MEMCACHE_DEFAULT_REGEXP. + In case of a match, the mysqlnd memcache plugin checks whether the + SELECT is accessing only columns of a mapped table and + the WHERE clause is limited to a single key lookup. + + + In case of the example SQL table, the plugin will use the Memcache interface + of the MySQL server to fetch results for a SQL query like + SELECT f1, f2, f3 WHERE id = n. + + + + + Basic example. + + +addServer("host", 11211); +mysqlnd_memcache_set($mysqli, $memc); + +/* + This is a query which queries table test using id as key in the WHERE part + and is accessing fields f1, f2 and f3. Therefore mysqlnd_memcache + will intercept it and route it ia memcache. +*/ +$result = $mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1"); +while ($row = $result->fetch_row()) { + print_r($row); +} + +/* + This is a query which queries table test but using f1 in the WHERE clause. + Therefore mysqlnd_memcache can't intercept it. This will be executed + using the MySQL protocol +*/ +$mysqli->query("SELECT id FROM test WHERE f1 = 'Lady'"); +while ($row = $result->fetch_row()) { + print_r($row); +} +?> +]]> + + &example.outputs; + + Hello + [f2] => World + [f3] => ! +) +array( + [id] => 2 +) +]]> + + + + +
+ + + diff --git a/reference/mysqlnd_memcache/reference.xml b/reference/mysqlnd_memcache/reference.xml new file mode 100644 index 0000000000..1b7a6600a3 --- /dev/null +++ b/reference/mysqlnd_memcache/reference.xml @@ -0,0 +1,30 @@ + + + + + Mysqlnd_memcache &Functions; + + &reference.mysqlnd-memcache.entities.functions; + + + + diff --git a/reference/mysqlnd_memcache/setup.xml b/reference/mysqlnd_memcache/setup.xml new file mode 100644 index 0000000000..01f6b4369d --- /dev/null +++ b/reference/mysqlnd_memcache/setup.xml @@ -0,0 +1,68 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + + This extension requires PHP 5.4.4 or newer. + + + For accessing InnoDB tables this PHP extension requires + MySQL Server 5.6.6 or newer with the InnoDB Memcache + Daemon Plugin. + + + For accessing MySQL Cluster NDB tables this PHP extensions + requires MySQL Cluster 7.2 or newer with configured NDB + Memcache API nodes. + + + PHP must be compiled with support for Perl regular + expressions through the pcre extension. + PCRE is included into PHP by default. + + + The memcached extension 2.0.x + must be loaded into PHP. + + + The mysqlnd_memcache memcache + plugin supports all PHP applications and all available PHP MySQL extensions + (mysqli, + mysql, + PDO_MYSQL). + The PHP MySQL extension must be configured to use + mysqlnd in order to be able + to use the mysqlnd_memcache plugin for + mysqlnd. + +
+ + &reference.mysqlnd-memcache.configure; + &reference.mysqlnd-memcache.ini; + + + + diff --git a/reference/mysqlnd_memcache/versions.xml b/reference/mysqlnd_memcache/versions.xml new file mode 100644 index 0000000000..2e5774d723 --- /dev/null +++ b/reference/mysqlnd_memcache/versions.xml @@ -0,0 +1,33 @@ + + + + + + + + + + + +