From 579ed5184d3c61f2627552dace4206c2933872cd Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Tue, 26 Jun 2012 13:55:07 +0000
Subject: [PATCH] Some updates for 1.4

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@326346 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqlnd_ms/book.xml       |  13 ++++
 reference/mysqlnd_ms/quickstart.xml | 109 ++++++++++++++++++++++++----
 2 files changed, 109 insertions(+), 13 deletions(-)

diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml
index 889e1818bd..f7d43928f5 100755
--- a/reference/mysqlnd_ms/book.xml
+++ b/reference/mysqlnd_ms/book.xml
@@ -172,6 +172,13 @@
           PHP 5.4.0 or newer: transaction aware when using API calls only to control transactions.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Weighted load balancing: servers can be assigned different priorities, for example, to
+          direct more requests to a powerful machine than to another less powerful machine. Or, to
+          prefer nearby machines to reduce latency.
+         </para>
+        </listitem>
        </itemizedlist>
       </para>
      </listitem>
@@ -199,6 +206,12 @@
           for reading when session consistency is required.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Throttling: optionally, the plugin can wait for a slave to become "synchronous" before
+          continuing.
+         </para>
+        </listitem>
        </itemizedlist>
       </para>
      </listitem>
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml
index c2b9dc7e58..161ccbbfc4 100755
--- a/reference/mysqlnd_ms/quickstart.xml
+++ b/reference/mysqlnd_ms/quickstart.xml
@@ -610,16 +610,19 @@ $mysqli->close();
   <title>Transactions</title>
   <para>
    The current version of the plugin is not transaction safe by default,
-   because it is not transaction aware. SQL transactions are
-   units of work to be run on a single server.
-   The plugin does not know when the unit of work starts and when it ends.
-   Therefore, the plugin may decide to switch connections in the middle
-   of a transaction.
+   because it is not aware of running transactions in all cases. SQL transactions are
+   units of work to be run on a single server.  The plugin does not always know
+   when the unit of work starts and when it ends. Therefore, the plugin may
+   decide to switch connections in the middle of a transaction.
+  </para>
+  <para>
+   No kind of MySQL load balancer can detect transaction boundaries without any
+   kind of hint from the application.
   </para>
   <para>
    You can either use SQL hints to work around this limitation. Alternatively,
    you can activate transaction API call monitoring. In the latter case you
-   must use API calls only to control transactins, see below.
+   must use API calls only to control transactions, see below.
   </para>
   <para>
    <example>
@@ -698,7 +701,7 @@ $mysqli->close();
    plugin to monitor the status of the <literal>autocommit</literal> mode, if
    the mode is set by API calls instead of using SQL statements such as
    <literal>SET AUTOCOMMIT=0</literal>. This makes it possible for the plugin to
-   become transaction aware.
+   become transaction aware. In this case, you do not need to use SQL hints.
   </para>
   <para>
     If using PHP 5.4.0 or newer, API calls that enable <literal>autocommit</literal> mode,
@@ -1075,12 +1078,6 @@ PHP Warning:  mysqli::query(): (mysqlnd_ms) No connection selected by the last f
     </screen>
    </example>
   </para>
-  <note>
-   <title>Fail over logic is work in progress</title>
-   <para>
-    The details of the fail over logic may change in future versions.
-   </para>
-  </note>
  </section>
  <section xml:id="mysqlnd-ms.quickstart.gtid">
   <title>Global transaction IDs</title>
@@ -1700,6 +1697,92 @@ var_dump($res->fetch_assoc());
    the cache will not be used and fresh data is read.
   </para>
  </section>
+ <section xml:id="mysqlnd-ms.quickstart.failover">
+  <title>Failover</title>
+  <para>
+   By default, the plugin does not attempt to fail over if connecting to a host
+   fails. This prevents pitfalls related to
+   <link linkend="mysqlnd-ms.quickstart.connectionpooling">connection state</link>.
+   It is recommended to manually handle connection errors in a way similar to a failed
+   transaction. You should catch the error, rebuild the connection state and rerun your
+   query as shown below.
+  </para>
+  <para>
+   If connection state is no issue to you, you can alternatively enable automatic
+   and silent failover. Depending on the configuration, the automatic and silent failover
+   will either attempt to fail over to the master before issuing and error or, try to
+   connect to other slaves, given the query allowes for it, before attempting to connect
+   to a master.
+  </para>
+  <para>
+   <example>
+    <title>Manual failover, automatic optional</title>
+    <programlisting role="ini">
+<![CDATA[
+  {
+    "myapp": {
+        "master": {
+            "master_0": {
+                "host": "localhost",
+                "socket": "\/tmp\/mysql.sock"
+            }
+        },
+        "slave": {
+            "slave_0": {
+                "host": "simulate_slave_failure",
+                "port": "0"
+            },
+            "slave_1": {
+                "host": "127.0.0.1",
+                "port": 3311
+            }
+        },
+       "filters": { "roundrobin": [] }
+    }
+ }
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Manual failover</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$mysqli = new mysqli("myapp", "username", "password", "database");
+if (!$mysqli)
+  /* Of course, your error handling is nicer... */
+  die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
+
+$sql = "SELECT 1 FROM DUAL";
+
+/* error handling as it should be done regardless of the plugin */
+if (!($res = $link->query($sql))) {
+  /* plugin specific: check for connection error */
+  switch ($link->errno) {
+    case 2002:
+    case 2003:
+    case 2005:
+      printf("Connection error - trying next slave!\n");
+      /* load balancer will pick next slave */
+      $res = $link->query($sql);
+      break;
+    default:
+      /* no connecion error, failover is unlikely to help */
+      die(sprintf("SQL error: [%d] %s", $link->errno, $link->error));
+      break;
+  }
+}
+if ($res) {
+  var_dump($res->fetch_assoc());
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </section>
 </chapter>
 <!-- Keep this comment at the end of the file
 Local variables: