php-doc-en/reference/mysqlnd_ms/book.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<book xml:id="book.mysqlnd-ms" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Mysqlnd replication and load balancing plugin</title>
 <titleabbrev>mysqlnd_ms</titleabbrev>

 <preface xml:id="intro.mysqlnd-ms">
  &reftitle.intro;
  <para>
   The mysqlnd replication and load balancing plugin (<literal>mysqlnd_ms</literal>)
   adds easy to use MySQL replication support to all PHP MySQL extensions that use
   <link linkend="book.mysqlnd">mysqlnd</link>.
  </para>
  <para>
   As of version PHP 5.3.3 the MySQL native driver for PHP
   (<literal>mysqlnd</literal>)
   features an internal plugin C API. C plugins, such as the replication and
   load balancing plugin, can extend the functionality of
   <link linkend="book.mysqlnd">mysqlnd</link>.
  </para>
  <para>
   The MySQL native driver for PHP is a C library that ships together with
   PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
   MySQL Client Library (libmysqlclient). Using mysqlnd has
   several advantages: no extra downloads are required because it's bundled with PHP,
   it's under the PHP license, there is lower memory consumption in certain cases, and
   it contains new functionality such as asynchronous queries.
  </para>
  <para>
   Mysqlnd plugins like <literal>mysqlnd_ms</literal> operate, for the most part,
   transparently from a user perspective. The replication and load balancing
   plugin supports all PHP applications, and all MySQL PHP extensions.
   It does not change existing APIs. Therefore, it can easily be used with
   existing PHP applications.
  </para>
  <section xml:id="mysqlnd-ms.key-features">
   <title>Key Features</title>
   <para>
   The key features of PECL/mysqlnd_ms are as follows.
   </para>
   <para>
    <itemizedlist>
     <listitem>
      <para>
       Transparent and therefore easy to use.
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Supports all of the PHP MySQL extensions.
         </para>
        </listitem>
        <listitem>
         <para>
          SSL support.
         </para>
        </listitem>
        <listitem>
         <para>
          A consistent <acronym>API</acronym>.
         </para>
        </listitem>
        <listitem>
         <para>
          Little to no application changes required, dependent on the required usage scenario.
         </para>
        </listitem>
        <listitem>
         <para>
          Lazy connections: connections to master and slave servers are not
          opened before a SQL statement is executed.
         </para>
        </listitem>
        <listitem>
         <para>
          Optional: automatic use of master after the first write in a web request, to
          lower the possible impact of replication lag.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Can be used with any MySQL clustering solution.
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          MySQL Replication: Read-write splitting is done by the plugin.
          Primary focus of the plugin.
         </para>
        </listitem>
        <listitem>
         <para>
          MySQL Cluster: Read-write splitting can be disabled.
          Configuration of multiple masters possible
         </para>
        </listitem>
        <listitem>
         <para>
          Third-party solutions: the plugin is optimized for MySQL Replication
          but can be used with any other kind of MySQL clustering solution.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Featured read-write split strategies
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Automatic detection of SELECT.
         </para>
        </listitem>
        <listitem>
         <para>
          Supports SQL hints to overrule automatism.
         </para>
        </listitem>
        <listitem>
         <para>
          User-defined.
         </para>
        </listitem>
        <listitem>
         <para>
          Can be disabled for, for example, when using synchronous clusters such as MySQL Cluster.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Featured load balancing strategies
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Round Robin: choose a different slave in round-robin fashion for every slave request.
         </para>
        </listitem>
        <listitem>
         <para>
          Random: choose a random slave for every slave request.
         </para>
        </listitem>
        <listitem>
         <para>
          Random once (sticky): choose a random slave once to run all slave requests for the duration of a web request.
         </para>
        </listitem>
        <listitem>
         <para>
          User-defined. The application can register callbacks with mysqlnd_ms.
         </para>
        </listitem>
        <listitem>
         <para>
          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>

     <listitem>
      <para>
       Global transaction ID
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Client-side emulation. Makes manual master server failover and slave promotion easier
          with asynchronous clusters, such as MySQL Replication.
         </para>
        </listitem>
        <listitem>
         <para>
          Support for built-in global transaction identifier feature of MySQL 5.6.5 or newer.
         </para>
        </listitem>
        <listitem>
         <para>
          Supports using transaction ids to identify up-to-date asynchronous slaves
          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>

     <listitem>
      <para>
       Service and consistency levels
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Applications can request eventual, session and strong consistency
          service levels for connections. Appropriate cluster nodes will
          be searched automatically.
         </para>
        </listitem>
        <listitem>
         <para>
          Eventual consistent MySQL Replication slave accesses can be replaced
          with fast local cache accesses transparently to reduce server load.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Partitioning and sharding
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
          Servers of a replication cluster can be organized into groups. SQL hints
          can be used to manually direct queries to a specific group.
          Grouping can be used to partition (shard) the data, or to cure the issue of
          hotspots with updates.
         </para>
        </listitem>
        <listitem>
         <para>
          MySQL Replication filters are supported through the table filter.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </itemizedlist>
   </para>
  </section>

  <section xml:id="mysqlnd-ms.limitations">
   <title>Limitations</title>
   <para>
    The built-in read-write-split mechanism is very basic. Every
    query which starts with <literal>SELECT</literal>
    is considered a read request to be sent to a MySQL slave server.
    All other queries (such as <literal>SHOW</literal> statements)
    are considered as write requests that are sent to the MySQL master server.
    The build-in behavior can be overruled using
    <link linkend="mysqlnd-ms.constants">SQL hints</link>, or a user-defined
    <link linkend="ini.mysqlnd-ms-plugin-config-v2.filter-user">callback function</link>.
   </para>
   <para>
    The read-write splitter is not aware of multi-statements. Multi-statements
    are considered as one statement. The decision of where to run the statement
    will be based on the beginning of the statement string. For example, if
    using <function>mysqli_multi_query</function>
    to execute the multi-statement <literal>SELECT id FROM test ; INSERT INTO test(id) VALUES (1)</literal>,
    the statement will be redirected to a slave server because it begins with
    <literal>SELECT</literal>. The <literal>INSERT</literal> statement, which is
    also part of the multi-statement, will not be redirected to a master server.
   </para>
   <note>
    <para>
     Applications must be aware of the consequences of connection switches that are
     performed for load balancing purposes. Please check the documentation on
     <link linkend="mysqlnd-ms.pooling">connection pooling and switching</link>,
     <link linkend="mysqlnd-ms.transaction">transaction handling</link>,
     <link linkend="mysqlnd-ms.failover">failover</link>
     <link linkend="mysqlnd-ms.loadbalancing">load balancing</link>&listendand;
     <link linkend="mysqlnd-ms.rwsplit">read-write splitting</link>.
    </para>
   </note>
  </section>

  <section xml:id="mysqlnd-ms.name">
   <title>On the name</title>
   <para>
    The shortcut <literal>mysqlnd_ms</literal>
    stands for <literal>mysqlnd master slave plugin</literal>. The name
    was chosen for a quick-and-dirty proof-of-concept. In the beginning
    the developers did not expect to continue using the code base.
   </para>
  </section>
 </preface>

 &reference.mysqlnd-ms.quickstart;
 &reference.mysqlnd-ms.concepts;
 &reference.mysqlnd-ms.setup;
 &reference.mysqlnd-ms.constants;
 &reference.mysqlnd-ms.reference;
 &reference.mysqlnd-ms.changes;

</book>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->