Document GTID feature limitation

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@332856 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mysqlnd_ms/changes.xml

@@ -42,9 +42,17 @@
   <para>
    Bug fixes
    <itemizedlist>
-    <listitem>
+     <listitem>
      <para>
-      No new bugs reported
+      Won't fix: #66616 R/W split fails: QOS with mysqlnd_get_last_gtid with built-in MySQL GTID
+     </para>
+     <para>
+      This is not a bug in the plugins implementation but a server side feature
+      limitation not considered and documented before. MySQL 5.6 built-in GTIDs cannot be
+      used to ensure session consistency when reading from slaves in all cases.
+      In the worst case the plugin will not consider using the slaves and
+      fallback to using the master. There will be no wrong results but no benefit
+      from doing GTID checks either.
      </para>
     </listitem>
    </itemizedlist>

reference/mysqlnd_ms/concepts.xml

@@ -1437,6 +1437,11 @@ Transient error retries before error: 2
     later. Neither are client-side transaction boundary monitoring nor any setup
     activities required if using the server feature.
    </para>
+   <para>
+     Please note, all MySQL 5.6 production versions do not provide
+     clients with enough information to use GTIDs for enforcing session consistency.
+     In the worst case, the plugin will choose the master only.
+   </para>
   </note>
   <para>
    <emphasis role="bold">Idea and client-side emulation</emphasis>
@@ -1546,6 +1551,28 @@ Transient error retries before error: 2
       use numeric algebra. Instead a SQL function must be used. Please,
       see the MySQL Reference Manual for details.
      </simpara>
+     <simpara>
+      Server-side built-in feature of MySQL 5.6 cannot be used to ensure session consistency
+      under all circumstances. Do not use it for the quality-of-service feature. Here is a simple
+      example why it will not give reliable results. There are more edge cases that cannot
+      be covered with limited functionality exported by the server. Currently, clients can
+      ask a MySQL replication master for a list of all executed global transaction IDs only.
+      If a slave is configured not to replicate all transactions, for example, because replication
+      filters are set, then the slave will never show the same set of executed global transaction
+      IDs. Albeit the slave may have replicated a clients writes and it may be a candidate
+      for a consistent read, it will never be considered by the plugin. Upon write the plugin
+      learns from the master that the servers complete transaction history consists of GTID=1..3.
+      There is no way for the plugin to ask for the GTID of the write transaction itself, say GTID=3.
+      Assume that a slave does not replicate the transactions GTID=1..2 but only GTID=3 because of
+      a replication feature. Then, the slaves transaction history is GTID=3. However, the plugin tries
+      to find a node which has a transaction history of GITD=1...3. Albeit the slave has replicated
+      the clients write and session consistency may be achieved when reading from the slave, it
+      will not be considered by the plugin. This is not a fault of the plugin implementation but
+      a feature gap on the server side. Please note, this is a trivial case to illustrate the
+      issue there are other issues. In sum you are asked not to attempt  using MySQL 5.6 built-in GTIDs
+      for enforcing session consistency. Sooner or later the load balancing will stop working properly
+      and the plugin will direct all session consistency requests to the master.
+     </simpara>
     </listitem>
     <listitem>
      <simpara>

reference/mysqlnd_ms/functions/mysqlnd-ms-get-last-gtid.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ --> 
+<!-- $Revision$ -->
 
 <refentry xml:id="function.mysqlnd-ms-get-last-gtid" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -67,6 +67,11 @@
     PHP &gt;= 5.4.0 and PECL mysqlnd_ms &gt;= 1.2.0. Internally, it is using
     a <literal>mysqlnd</literal> library C functionality not available with PHP 5.3.
    </para>
+   <para>
+     Please note, all MySQL 5.6 production versions do not provide
+     clients with enough information to use GTIDs for enforcing session consistency.
+     In the worst case, the plugin will choose the master only.
+   </para>
   </note>
  </refsect1>
 

reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml

@@ -151,6 +151,11 @@
     PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using
     a <literal>mysqlnd</literal> library C functionality not available with PHP 5.3.
    </para>
+   <para>
+Please note, all MySQL 5.6 production versions do not provide
+     clients with enough information to use GTIDs for enforcing session consistency.
+     In the worst case, the plugin will choose the master only.
+   </para>
   </note>
  </refsect1>
 

reference/mysqlnd_ms/quickstart.xml

@@ -1115,9 +1115,11 @@ PHP Warning:  mysqli::query(): (mysqlnd_ms) No connection selected by the last f
     Use it with asynchronous clusters such as classical MySQL replication.
    </para>
    <para>
-    As of MySQL 5.6.5-m8 the MySQL server features built-in global transaction identifiers.
+    As of MySQL 5.6.5-m8 release candidate the MySQL server features built-in global transaction identifiers.
     The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or
-    later.
+    later. However, the final feature set found in MySQL 5.6 production releases to date is not
+    sufficient to support the ideas discussed below in all cases. Please, see also the
+    <link linkend="mysqlnd-ms.gtid">concepts section</link>.
    </para>
   </note>
   <para>
@@ -1466,6 +1468,16 @@ var_dump($res->fetch_assoc());
   <para>
    <emphasis role="bold">Use of the server-side global transaction ID feature</emphasis>
   </para>
+  <note>
+   <title>Insufficient server support in MySQL 5.6</title>
+   <para>
+    The plugin has been developed against a pre-production version of MySQL 5.6.
+    It turns out that all released production versions of MySQL 5.6 do not provide
+    clients with enough information to enforce session consistency based on GTIDs.
+    Please, read the <link linkend="mysqlnd-ms.gtid">concepts section</link>
+    for details.
+   </para>
+  </note>
   <para>
    Starting with MySQL 5.6.5-m8 the MySQL Replication system features server-side
    global transaction IDs. Transaction identifiers are automatically generated and
@@ -1475,8 +1487,8 @@ var_dump($res->fetch_assoc());
   </para>
   <para>
     Clients can continue to use global transaction identifier to achieve
-    session consistency when reading from MySQL Replication slaves. The algorithm
-    works as described above. Different SQL statements must be configured for
+    session consistency when reading from MySQL Replication slaves in some cases but not all!
+    The algorithm  works as described above. Different SQL statements must be configured for
     <literal>fetch_last_gtid</literal> and <literal>check_for_gtid</literal>.
     The statements are given below. Please note, MySQL 5.6.5-m8 is a development
     version. Details of the server implementation may change in the future and require