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

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

<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 the MySQL native driver (<link linkend="book.mysqlnd">mysqlnd</link>)
   for PHP.
  </para>
  <para>
   The MySQL native driver for PHP features an internal C API for plugins,
   such as the connection multiplexing plugin, which can extend the functionality of
   mysqlnd. See the <link linkend="book.mysqlnd">mysqlnd</link> for additional details
   about its benefits over the MySQL Client Library libmysqlclient.
  </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 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 are required, dependent on the required usage scenario.
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>

     <listitem>
      <para>
       Reduces 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 process. 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, and asynchronous queries.
   </para>
   <para>
    The connection pool is using a combination of the transport method and
    hostname as keys. 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. Be aware of the possible security implications.
   </para>
   <para>
    The proof-of-concept is transaction agnostic. It does not know 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>About the name mysqlnd_mux</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
-->