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

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

<book xml:id="book.mysqlnd-mux" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Mysqlnd connection multiplexing plugin</title>
 <titleabbrev>mysqlnd_mux</titleabbrev>

 <preface xml:id="intro.mysqlnd-mux">
  &reftitle.intro;
  <para>
   The mysqlnd multiplexing plugin (<literal>mysqlnd_mux</literal>)
   multiplexes MySQL connections established by 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
   connection multiplexing 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 (libmysql/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_mux</literal> operate, for the most part,
   transparently from a user perspective. The connection multiplexing
   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>
  <note>
   <para>
     This is a proof-of-concept. All features are at an early stage. Not all
     kinds of queries are handled by the plugin yet. Thus, it cannot be used
     in a drop-in fashion at the moment.
    </para>
    <para>
      Please, do not use this version in production environments.
    </para>
  </note>
  <section xml:id="mysqlnd-mux.key-features">
   <title>Key Features</title>
   <para>
   The key features of PECL/mysqlnd_mux 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>
          Little to no application changes required, dependent on the required usage scenario.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Reduce server load and connection establishment latency
      </para>
      <para>
       <itemizedlist>
        <listitem>
         <para>
           Opens less connections to the MySQL server.
         </para>
        </listitem>
        <listitem>
         <para>
           Less connections to MySQL mean less work for the MySQL server.
           In a client-server environment scaling the server is often more
           difficult than scaling the client. Multiplexing helps with
           horizontal scale-out (scale-by-client).
         </para>
        </listitem>
        <listitem>
         <para>
           Pooling saves connection time.
         </para>
        </listitem>
        <listitem>
         <para>
           Multiplexed connection: multiple user handles share the
           same network connection. Once opened,
           a network connection is cached and shared among
           multiple user handles. There is a 1:n relationship between
           internal network connection and user connection handles.
         </para>
        </listitem>
        <listitem>
         <para>
           Persistent connection: a network connection is kept open
           at the end of the web request, if the PHP deployment model allows.
           Thus, subsequently web requests can reuse a
           previously opened connection. Like other resources, network
           connections are bound to the scope of a proceess. Thus, they can
           be reused for all web requests served by a process.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

    </itemizedlist>
   </para>
  </section>

  <section xml:id="mysqlnd-mux.limitations">
   <title>Limitations</title>
   <para>
    The proof-of-concept does not support unbuffered queries. Prepared
    statements cannot be used. Asynchronous queries are not supported.
   </para>
   <para>
    The connection pool is using a combination of transport method and
    hostname as a key. As a consequence two connections to the same
    host using the same transport method (TCP/IP, Unix socket, Windows named pipe)
    will be linked to the same pooled connection even if username and
    password differ. Please, be aware of the possible security implications.
   </para>
   <para>
    The proof-of-concept is transaction agnostic. It does not about SQL transactions.
   </para>
   <note>
    <para>
     Applications must be aware of the consequences of connection sharing connections.
    </para>
   </note>
  </section>

  <section xml:id="mysqlnd-mux.name">
   <title>On the name</title>
   <para>
    The shortcut <literal>mysqlnd_mux</literal>
    stands for <literal>mysqlnd connection multiplexing plugin</literal>.
   </para>
  </section>
 </preface>

 &reference.mysqlnd-mux.concepts;
 &reference.mysqlnd-mux.setup;
 &reference.mysqlnd-mux.constants;
 &reference.mysqlnd-mux.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
-->