svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ book.xml changes.xml quickstart.xml

From: Date: Tue, 11 Mar 2014 11:18:23 +0000
Subject: svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ book.xml changes.xml quickstart.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-12190@lists.php.net to get a copy of this message
uw Tue, 11 Mar 2014 11:18:23 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=332949 Log: Copying README.fabric example to quickstart: at least mentioning/covering the Fabric support Changed paths: U phpdoc/en/trunk/reference/mysqlnd_ms/book.xml U phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml U phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml Modified: phpdoc/en/trunk/reference/mysqlnd_ms/book.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/book.xml 2014-03-10 16:30:15 UTC (rev 332948) +++ phpdoc/en/trunk/reference/mysqlnd_ms/book.xml 2014-03-11 11:18:23 UTC (rev 332949) @@ -203,7 +203,8 @@ <listitem> <para> 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. </para> </listitem> <listitem> @@ -261,6 +262,22 @@ </itemizedlist> </para> </listitem> + + <listitem> + <para> + MySQL Fabric + </para> + <para> + <itemizedlist> + <listitem> + <para> + <link linkend="mysqlnd-ms.quickstart.mysql_fabric">Experimental support</link> + for MySQL Fabric is included. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> </itemizedlist> </para> </section> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2014-03-10 16:30:15 UTC (rev 332948) +++ phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2014-03-11 11:18:23 UTC (rev 332949) @@ -104,12 +104,20 @@ <listitem> <para> 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. + </para> + <para> + 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. </para> + <para> + As this is work in progress, the manual may not yet reflect allow + feature limitations and known bugs. + </para> </listitem> <listitem> <para> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml 2014-03-10 16:30:15 UTC (rev 332948) +++ phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml 2014-03-11 11:18:23 UTC (rev 332949) @@ -1948,6 +1948,132 @@ </para> </section> + + + <section xml:id="mysqlnd-ms.quickstart.mysql_fabric"> + <title>MySQL Fabric</title> + <note> + <title>Version requirement and status</title> + <para> + 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. + </para> + <para> + Sharding is the only use case supported by the plugin to date. + </para> + </note> + <note> + <title>MySQL Fabric concepts</title> + <para> + 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. + </para> + </note> + <para> + 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. + </para> + <para> + 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. + </para> + <para> + Instead of listing MySQL servers directly in the plugins configuration file + it contains a list of one or more MySQL Fabric hosts + </para> + <para> + <example> + <title>Plugin config: Fabric hosts instead of MySQL servers</title> + <programlisting role="ini"> +<![CDATA[ +{ + "myapp": { + "fabric": { + "hosts": [ + { + "host" : "127.0.0.1", + "port" : 8080 + } + ] + } + } +} +]]> + </programlisting> + </example> + </para> + <para> + Users utilize the new functions + <link linkend="function.mysqlnd-ms-fabric-select-shard"> + <function>mysqlnd_ms_fabric_select_shard</function></link> and + <link linkend="function.mysqlnd-ms-fabric-select-global"> + <function>mysqlnd_ms_fabric_select_global</function></link> 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. + </para> + <para> + The below example assumes that MySQL Fabric has been setup + to shard the table <literal>test.fabrictest</literal> using + the <literal>id</literal> column of the table as a shard key. + </para> + <para> + <example> + <title>Manual partitioning using SQL hints</title> + <programlisting role="php"> +<![CDATA[ +<?php +$mysqli = new mysqli("myapp", "user", "password", "database"); +if (!$mysqli) + /* Of course, your error handling is nicer... */ + die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error())); + +/* Create a global table - a table available on all shards */ +mysqlnd_ms_fabric_select_global($mysqli, "test.fabrictest"); +if (!$mysqli->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)); +?> +]]> + </programlisting> + </example> + </para> + <para> + 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, + <link linkend="function.mysqlnd-ms-fabric-select-global"> + <function>mysqlnd_ms_fabric_select_global</function></link> 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 <link linkend="function.mysqlnd-ms-fabric-select-shard"> + <function>mysqlnd_ms_fabric_select_shard</function></link> switches a + connection to shards handling a certain shard key. + </para> + + + </section> </chapter> <!-- Keep this comment at the end of the file Local variables:

« previous php.doc.cvs (#12190) next »