svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ book.xml changes.xml quickstart.xml
| From: | Ulf Wendel | 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: