svn commit - mysqldoc@docsrva: r23385 - trunk/refman-common

[tony.bedford]

Author: tbedford
Date: 2010-10-26 16:32:29 +0200 (Tue, 26 Oct 2010)
New Revision: 23385

Log:
More on load balancing failover (thanks Todd Farmer)

Modified:
   trunk/refman-common/connector-j.xml


Modified: trunk/refman-common/connector-j.xml
===================================================================
--- trunk/refman-common/connector-j.xml	2010-10-26 13:54:25 UTC (rev 23384)
+++ trunk/refman-common/connector-j.xml	2010-10-26 14:32:29 UTC (rev 23385)
Changed blocks: 2, Lines Added: 59, Lines Deleted: 4; 3429 bytes

@@ -4225,10 +4225,9 @@
           </orderedlist>
 
           <para>
-            The third condition is new, and revolves around three new
-            properties introduced with Connector/J 5.1.13. It allows you
-            to control which <literal>SQLException</literal>s trigger
-            failover.
+            The third condition revolves around three new properties
+            introduced with Connector/J 5.1.13. It allows you to control
+            which <literal>SQLException</literal>s trigger failover.
           </para>
 
           <itemizedlist>

@@ -4334,6 +4333,62 @@
 
           </itemizedlist>
 
+          <para>
+            While the three fail-over conditions enumerated earlier suit
+            most situations, if <literal>auto-commit</literal> is
+            enabled, Connector/J never re-balances, and continues using
+            the same physical connection. This can be problematic,
+            particularly when load-balancing is being used to distribute
+            read-only load across multiple slaves. However, Connector/J
+            can be configured to re-balance after a certain number of
+            statements are executed, when <literal>auto-commit</literal>
+            is enabled. This functionality is dependent upon the
+            following properties:
+          </para>
+
+          <itemizedlist>
+
+            <listitem>
+              <para>
+                <literal>loadBalanceAutoCommitStatementThreshold</literal>
+                – defines the number of matching statements which will
+                trigger the driver to potentially swap physical server
+                connections. The default value, 0, retains the behavior
+                that connections with <literal>auto-commit</literal>
+                enabled are never balanced.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                <literal>loadBalanceAutoCommitStatementRegex</literal>
+                – the regular expression against which statements must
+                match. The default value, blank, matches all statements.
+                So, for example, using the following properties will
+                cause Connector/J to re-balance after every third
+                statement that contains the string <quote>test</quote>:
+              </para>
+
+<programlisting>
+loadBalanceAutoCommitStatementThreshold=3
+loadBalanceAutoCommitStatementRegex=.*test.*
+</programlisting>
+
+              <para>
+                <literal>loadBalanceAutoCommitStatementRegex</literal>
+                can prove useful in a number of situations. Your
+                application may use temporary tables, server-side
+                session state variables, or connection state, where
+                letting the driver arbitrarily swap physical connections
+                before processing is complete could cause data loss or
+                other problems. This allows you to identify a trigger
+                statement that is only executed when it is safe to swap
+                physical connections.
+              </para>
+            </listitem>
+
+          </itemizedlist>
+
         </section>
 
       </section>