diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml index b9e22dad80..aeea1a5831 100755 --- a/reference/mysqlnd_ms/book.xml +++ b/reference/mysqlnd_ms/book.xml @@ -203,7 +203,8 @@ Supports using transaction ids to identify up-to-date asynchronous slaves - for reading when session consistency is required. + for reading when session consistency is required. Please, note the restrictions + mentioned in the manual. @@ -261,6 +262,22 @@ + + + + MySQL Fabric + + + + + + Experimental support + for MySQL Fabric is included. + + + + + diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index b0e8f97146..28a308a1ed 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -104,11 +104,19 @@ Introduced most basic support for the MySQL Fabric High Availability and sharding - framework. Please, consider this pre-alpha quality. Both the - server side framework and the client side code is supposed to work flawless. - However, testing has not been performed to the level of prior plugin - alpha releases. Either sides are moving targets, - API changes may happen at any time without prior warning. + framework. + + + Please, consider this pre-alpha quality. Both the + server side framework and the client side code is supposed to work flawless + considering the MySQL Fabric quickstart examples only. However, testing has not been + performed to the level of prior plugin alpha releases. + Either sides are moving targets, API changes may happen at any + time without prior warning. + + + As this is work in progress, the manual may not yet reflect allow + feature limitations and known bugs. diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index 52080f673e..0d3b9c3d96 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -1948,6 +1948,132 @@ select($mysqli, "slave_1", "/*Partition_A*/"); + + +
+ MySQL Fabric + + Version requirement and status + + Work on supporting MySQL Fabric started in version 1.6. Please, + consider the support to be of pre-alpha quality. The manual may + not list all features or feature limitations. This is work in progress. + + + Sharding is the only use case supported by the plugin to date. + + + + MySQL Fabric concepts + + Please, check the MySQL reference manual for more information about MySQL Fabric + and how to set it up. The PHP manual assumes that you are familiar + with the basic concepts and ideas of MySQL Fabric. + + + + MySQL Fabric is a system for managing farms of MySQL servers to achive + High Availability and optionally support sharding. Technically, it is a + middleware to manage and monitor MySQL servers. + + + Clients query MySQL Fabric to obtain lists of MySQL servers, + their state and their roles. For example, clients can can request a list of + slaves for a MySQL Replication group and whether they are ready to + handle SQL requests. Another example is a cluster of sharded MySQL servers + where the client seeks to know which shard to query for a given + table and shard key. If configured to use Fabric, the plugin uses XML RCP over HTTP + to obtain the list at runtime from a MySQL Fabric host. The XML remote + procedure call itself is done in the background and transparent from a + developers point of view. + + + Instead of listing MySQL servers directly in the plugins configuration file + it contains a list of one or more MySQL Fabric hosts + + + + Plugin config: Fabric hosts instead of MySQL servers + + + + + + + Users utilize the new functions + + mysqlnd_ms_fabric_select_shard and + + mysqlnd_ms_fabric_select_global to switch to + the set of servers responsible for a given shard key. Then, the + plugin picks an appropriate server for running queries on. + When doing so, the plugin takes care of additional + load balancing rules set. + + + The below example assumes that MySQL Fabric has been setup + to shard the table test.fabrictest using + the id column of the table as a shard key. + + + + Manual partitioning using SQL hints + +query("CREATE TABLE test.fabrictest(id INT NOT NULL PRIMARY KEY)")) + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); + +/* Switch connection to appropriate shard and insert record */ +mysqlnd_ms_fabric_select_shard($mysqli, "test.fabrictest", 10); +if (!($res = $mysqli->query("INSERT INTO fabrictest(id) VALUES (10)"))) + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); + +/* Try to read newly inserted record */ +mysqlnd_ms_fabric_select_shard($mysqli, "test.fabrictest", 10); +if (!($res = $mysqli->query("SELECT id FROM test WHERE id = 10"))) + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); +?> +]]> + + + + + The example creates the sharded table, inserts a record and reads + the record thereafter. All SQL data definition language (DDL) + operations on a sharded table must be applied to the so called global server group. + Prior to creatingor altering a sharded table, + + mysqlnd_ms_fabric_select_global is called + to switch the given connection to the corresponsing servers of the global + group. Data manipulation (DML) SQL statements must be sent to the shards + directly. The + mysqlnd_ms_fabric_select_shard switches a + connection to shards handling a certain shard key. + + + +