Some docs for the experimental setting trx_stickiness=master implemented today

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

reference/mysqlnd_ms/concepts.xml

@@ -180,8 +180,23 @@
     of a SQL transaction. Please, find details in the examples section.
   </para>
   <para>
-    Future versions of the plugin might offer special settings to make
-    plugin transaction safe.
+    The latest version of the <literal>mysqlnd</literal> library, as found in
+    PHP 5.3.99, allows the plugin to subclass the library C API call 
+    <literal>trx_autocommit()</literal> to 
+    detect the status of the <literal>autocommit</literal> mode. The PHP MySQL
+    extensions either issue a query such as <literal>SET AUTOCOMMIT=0|1</literal>
+    or use the mysqlnd library call <literal>trx_autcommit()</literal> to control
+    the <literal>autocommit</literal> setting. If an extension makes use of
+    <literal>trx_autocommit()</literal>, the plugin can be made transaction aware.
+    Transaction awareness cannot be achieved, if using SQL to set the autocommit
+    mode. 
+  </para>
+  <para>
+    The experimental pluging configuration option 
+    <literal>trx_stickiness=master</literal> can be used to make the plugin 
+    transaction aware if using PHP 5.3.99. In this mode the plugin stops load
+    balancing if autocommit gets disabled and directs all statements to the
+    master until autocommit gets enabled.
   </para>
  </section>
  

reference/mysqlnd_ms/quickstart.xml

@@ -582,11 +582,90 @@ $mysqli->close();
    </example>
   </para>
   <para>
-    Future versions of the plugin may be made aware of transactions started, 
-    rolled back and committed using API calls. Therefore, whenever possible
-    you should start using API calls to control transactions unlike using
-    SQL statements, as shown in the above example.
-  </para> 
+   Starting with PHP 5.3.99 the <literal>mysqlnd</literal> library allows the
+   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.
+  </para>
+  <para>
+    If using PHP 5.3.99, API calls to set the <literal>autocommit</literal> mode
+    and setting the experimental plugin configuration option 
+    <link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness=master</literal></link>
+    the plugin can automatically disable load balancing and connection switches
+    for SQL transactions. In this configuration the plugin stops load balancing,
+    if <literal>autocommit</literal> is disabled and directs all statements to
+    the master. This is done to prevent connection switches in the middle of
+    a transaction. Once <literal>autocommit</literal> gets enabled again, the plugin
+    starts to load balance statements again. 
+  </para>
+  <para>
+   <example>
+    <title>Experimental trx_stickiness setting</title>
+    <programlisting role="ini">
+<![CDATA[
+[myapp]
+master[]=localhost:/tmp/mysql.sock
+slave[]=192.168.2.27:3306
+trx_stickiness=master
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Outlook: transaction aware</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+if (version_compare(PHP_VERSION, "5.3.99", "<"))
+  die("This feature requires PHP 5.3.99, you are using " . PHP_VERSION);
+  
+$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()));
+
+/* Disable autocommit, plugin will run all statements on the master */
+$mysqli->autocommit(FALSE);
+
+if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { 
+ /* Please do proper ROLLBACK in your code, don't just die */
+ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); 
+}
+if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) {
+  $row = $res->fetch_assoc();
+  $res->close();
+  if ($row['_num'] > 1000) {
+   if (!$mysqli->query("INSERT INTO events(task) VALUES ('cleanup')")) {
+     die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
+   }
+  }  
+} else {
+ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
+}
+if (!$mysqli->query("UPDATE log SET last_update = NOW()")) {
+ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
+}
+if (!$mysqli->commit()) {
+ die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error));
+}
+
+/* Plugin assumes that the transaction has ended and starts load balancing again */
+$mysqli->autocommit(TRUE);
+$mysqli->close();
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <note>
+   <para>
+    The plugin configuration option
+    <link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness=master</literal></link>
+    is an experimental feature. It requires PHP 5.3.99.
+   </para>
+  </note>
  </section>
 </chapter>
 <!-- Keep this comment at the end of the file

reference/mysqlnd_ms/setup.xml

@@ -301,6 +301,56 @@ slave[] = mysql_slave_2
       </para>
      </listitem>
     </varlistentry>
+    <varlistentry xml:id="ini.mysqlnd-ms-plugin-config.trx_stickiness">
+     <term>
+      <parameter>trx_stickiness</parameter>
+      <type>string</type>
+     </term>
+     <listitem>
+      <para>
+       Transaction stickiness policy. Supported policies:
+       <literal>disabled</literal> (default), <literal>master</literal>.
+      </para>
+      <para>
+       Experimental feature.
+      </para>
+      <para>
+       The setting requires 5.3.99 or newer. If used with PHP older than 5.3.99,
+       the plugin will emit a warning like 
+       <literal>(mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99</literal>.
+      </para>
+      <para>
+       If no transaction stickiness policy is set or, 
+       if setting <literal>trx_stickiness=disabled</literal>, 
+       the plugin is not transaction aware. Thus, the plugin may load balance
+       connections and switch connections in the middle of a transaction.
+       The plugin is not transaction safe. SQL hints must be used 
+       avoid connection switches during a transaction.
+      </para>
+      <para>
+       As of PHP 5.3.99 the mysqlnd library allows the plugin to monitor 
+       the <literal>autocommit</literal> mode set by calls to the 
+       libraries <literal>trx_autocommit()</literal> function. 
+       If setting <literal>trx_stickiness=master</literal> and 
+       <literal>autocommit</literal> gets disabled by a PHP MySQL extension
+       invoking the <literal>mysqlnd</literal> library internal
+       function call <literal>trx_autocommit()</literal>, the plugin is made
+       aware of the begin of a transaction. Then, the plugin stops load balancing
+       and directs all statements to the master server until 
+       <literal>autocommit</literal> is enabled. Thus, no SQL hints are required.
+      </para>
+      <para>
+       An example of a PHP MySQL API function calling the <literal>mysqlnd</literal> 
+       library internal function call <literal>trx_autocommit()</literal> is 
+       <function>mysqli_autocommit</function>.
+      </para>
+      <para>
+       Although setting <literal>trx_stickiness=master</literal>, the plugin
+       cannot be made aware of <literal>autocommit</literal> mode changes caused
+       by SQL statements such as <literal>SET AUTOCOMMIT=0</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </section>