php-doc-en/reference/mysqli/mysqlnd.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqli.mysqlnd" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">

  <title>The MySQL Native Driver</title>

  <para>
    This section of the manual provides an overview of the MySQL Native
    Driver.
  </para>

  <para>
    <emphasis role="bold">What is it?</emphasis>
  </para>

  <para>
    MySQL Native Driver is a replacement for the MySQL Client Library
    (libmysql). MySQL Native Driver is part of the official PHP 5.3 and
    PHP 6 branches.
  </para>

  <para>
    The MySQL database extensions MySQL extension,
    <literal>mysqli</literal> and PDO MYSQL all communicate with the
    MySQL server. In the past, this was done by the extension using the
    services provided by the MySQL Client Library. The extensions were
    compiled against the MySQL Client Library in order to use its
    client-server protocol.
  </para>

  <para>
    With MySQL Native Driver there is now an alternative, as the MySQL
    database extensions can be compiled to use MySQL Native Driver
    instead of the MySQL Client Library.
  </para>

  <para>
    MySQL Native Driver is written in C as a PHP extension.
  </para>

  <para>
    <emphasis role="bold">What it is not</emphasis>
  </para>

  <para>
    Although MySQL Native Driver is written as a PHP extension, it is
    important to note that it does not provide a new API to the PHP
    programmer. The programmer APIs for MySQL database connectivity are
    provided by the MySQL extension, <literal>mysqli</literal> and PDO
    MYSQL. These extensions can now use the services of MySQL Native
    Driver to communicate with the MySQL Server. Therefore, you should
    not think of MySQL Native Driver as an API.
  </para>

  <para>
    <emphasis role="bold">Why use it?</emphasis>
  </para>

  <para>
    Using the MySQL Native Driver offers a number of advantages over
    using the MySQL Client Library.
  </para>

  <para>
    The older MySQL Client Library was written by MySQL AB (now Sun
    Microsystems, Inc.) and so was released under the MySQL license.
    This ultimately led to MySQL support being disabled by default in
    PHP. However, the MySQL Native Driver has been developed as part of
    the PHP project, and is therefore released under the PHP license.
    This removes licensing issues that have been problematic in the
    past.
  </para>

  <para>
    Also, in the past, you needed to build the MySQL database extensions
    against a copy of the MySQL Client Library. This typically meant you
    needed to have MySQL installed on a machine where you were building
    the PHP source code. Also, when your PHP application was running,
    the MySQL database extensions would call down to the MySQL Client
    library file at run time, so the file needed to be installed on your
    system. With MySQL Native Driver that is no longer the case as it is
    included as part of the standard distribution. So you do not need
    MySQL installed in order to build PHP or run PHP database
    applications.
  </para>

  <para>
    Because MySQL Native Driver is written as a PHP extension, it is
    tightly coupled to the workings of PHP. This leads to gains in
    efficiency, especially when it comes to memory usage, as the driver
    uses the PHP memory management system. It also supports the PHP
    memory limit. Using MySQL Native Driver leads to comparable or
    better performance than using MySQL Client Library, it always
    ensures the most efficient use of memory. One example of the memory
    efficiency is the fact that when using the MySQL Client Library,
    each row is stored in memory twice, whereas with the MySQL Native
    Driver each row is only stored once in memory.
  </para>

  <para>
    <emphasis role="bold">Special features</emphasis>
  </para>

  <para>
    MySQL Native Driver also provides some special features not
    available when the MySQL database extensions use MySQL Client
    Library. These special features are listed below:
  </para>

  <itemizedlist>

    <listitem>
      <para>
        Improved persistent connections
      </para>
    </listitem>

    <listitem>
      <para>
        The special function <function>mysqli_fetch_all</function>
      </para>
    </listitem>

    <listitem>
      <para>
        Performance statistics calls:
        <function>mysqli_get_cache_stats</function>,
        <function>mysqli_get_client_stats</function>,
        <function>mysqli_get_connection_stats</function>
      </para>
    </listitem>

  </itemizedlist>

  <para>
    The performance statistics facility can prove to be very useful in
    identifying performance bottlenecks.
  </para>

  <para>
    MySQL Native Driver also allows for persistent connections when used
    with the <literal>mysqli</literal> extension.
  </para>

  <para>
    <emphasis role="bold">SSL Support</emphasis>
  </para>

  <para>
    Currently, MySQL Native Driver does not support SSL. This means that
    <function>mysqli_ssl_set</function> will generate an error if called
    while using MySQL Native Driver.
  </para>

  <para>
    <emphasis role="bold">Installation on Unix</emphasis>
  </para>

  <para>
    By default the MySQL database extensions are configured to use MySQL
    Client Library. In order to use the MySQL Native Driver, PHP needs
    to be built specifying that the MySQL database extensions are
    compiled with MySQL Native Driver support. This is done through
    configuration options prior to building the PHP source code.
  </para>

  <para>
    For example, to build the MySQL extension, <literal>mysqli</literal>
    and PDO MYSQL using the MySQL Native Driver, the following command
    would be given:
  </para>

<programlisting role="shell">./configure --with-mysql=mysqlnd \
--with-mysqli=mysqlnd \
--with-pdo-mysql=mysqlnd \
[other options]</programlisting>

  <para>
    <emphasis role="bold">Installation on Windows</emphasis>
  </para>

  <para>
    In the official PHP distributions from 5.3 onwards, MySQL Native
    Driver is enabled by default, so no additional configuration is
    required to use it. All MySQL database extensions will use MySQL
    Native Driver in this case.
  </para>

  <para>
    <emphasis role="bold">Configuration File
    (php.ini) Settings</emphasis>
  </para>

  <para>
    In PHP 5.3 the following <filename>php.ini</filename> settings are
    availble for the MySQL Native Driver:
  </para>

  <para>
    <literal>mysqlnd.collect_statistics</literal>
  </para>

  <para>
    type:boolean, default:"1", changeable:PHP_INI_SYSTEM
  </para>

  <para>
    Available since 5.3.0
  </para>

  <para>
    Enables the collection of various client statistics which can be
    accessed through <literal>mysqli_get_client_stats()</literal>,
    <literal>mysqli_get_connection_stats()</literal>,
    <literal>mysqli_get_cache_stats()</literal> and are shown in
    <literal>mysqlnd</literal> section of the output of the
    <literal>phpinfo()</literal> function as well.
  </para>

  <para>
    When enabled the following statistics will be collected:
  </para>

  <para>
    bytes_sent, bytes_received, packets_sent, packets_received,
    protocol_overhead_in, protocol_overhead_out,
    bytes_received_ok_packet, bytes_received_eof_packet,
    bytes_received_rset_header_packet,
    bytes_received_rset_field_meta_packet,
    bytes_received_rset_row_packet,
    bytes_received_prepare_response_packet,
    bytes_received_change_user_packet, packets_sent_command,
    packets_received_ok, packets_received_eof,
    packets_received_rset_header, packets_received_rset_field_meta,
    packets_received_rset_row, packets_received_prepare_response,
    packets_received_change_user, result_set_queries,
    non_result_set_queries, no_index_used, bad_index_used, slow_queries,
    buffered_sets, unbuffered_sets, ps_buffered_sets,
    ps_unbuffered_sets, flushed_normal_sets, flushed_ps_sets,
    ps_prepared_never_executed, ps_prepared_once_executed,
    rows_fetched_from_server_normal, rows_fetched_from_server_ps,
    rows_buffered_from_client_normal, rows_buffered_from_client_ps,
    rows_fetched_from_client_normal_buffered,
    rows_fetched_from_client_normal_unbuffered,
    rows_fetched_from_client_ps_buffered,
    rows_fetched_from_client_ps_unbuffered,
    rows_fetched_from_client_ps_cursor, rows_skipped_normal,
    rows_skipped_ps, copy_on_write_saved, copy_on_write_performed,
    command_buffer_too_small, connect_success, connect_failure
  </para>

  <para>
    <literal>mysqlnd.collect_memory_statistics</literal>
  </para>

  <para>
    type:boolean, default:"0", changeable:PHP_INI_SYSTEM
  </para>

  <para>
    Available since 5.3.0
  </para>

  <para>
    Enable the collection of various memory statistics which can be
    accessed through <literal>mysqli_get_client_stats()</literal>,
    <literal>mysqli_get_connection_stats()</literal>,
    <literal>mysqli_get_cache_stats()</literal> and are shown in
    <literal>mysqlnd</literal> section of the output of the
    <literal>phpinfo()</literal> function as well.
  </para>

  <para>
    When enabled the following statistics will be collected:
  </para>

  <para>
    <emphasis role="bold">Using Persistent Connections</emphasis>
  </para>

  <para>
    The MySQL database extensions do not support persistent connections
    when used with the MySQL Client Library. However, they do when using
    MySQL Native Driver. When creating a connection the hostname is
    prepended with <quote>p:</quote>. This is demonstrated by the
    following code snippet, which creates a new connection using
    <literal>mysqli</literal>:
  </para>

<programlisting role="php">$host="p:localhost";
$port=3306;
$socket="/tmp/mysql.sock";
$user="root";
$password="password";
$dbname="test";

$conn = new mysqli($host, $user, $password, $dbname, $port, $socket)
   or die ('Could not connect to the database server' . mysqli_connect_error());</programlisting>

  <para>
    <emphasis role="bold">Using
    <function>mysqli_fetch_all</function></emphasis>
  </para>

  <para>
    If you are using <literal>mysqli</literal> with the MySQL Native
    Driver, you have access to the new API call
    <function>mysqli_fetch_all</function>.
  </para>

  <para>
    As <function>mysqli_fetch_all</function> returns all the rows as an
    array in a single step, it may consume more memory than some similar
    functions such as <function>mysqli_fetch_array</function>, which
    only returns one row at a time from the result set. Further, if you
    need to iterate over the result set, you will need a looping
    construct that will further impact performance. For these reasons
    <function>mysqli_fetch_all</function> should only be used in those
    situations where the fetched result set will be sent to another
    layer for processing.
  </para>

  <para>
    <emphasis role="bold">Using Statistical Data</emphasis>
  </para>

  <para>
    MySQL Native Driver contains support for gathering statistics on the
    communication between the client and the server. The statistics
    gathered are of three main types:
  </para>

  <itemizedlist>

    <listitem>
      <para>
        Client statistics
      </para>
    </listitem>

    <listitem>
      <para>
        Connection statistics
      </para>
    </listitem>

    <listitem>
      <para>
        Zval cache statistics
      </para>
    </listitem>

  </itemizedlist>

  <para>
    If you are using the <literal>mysqli</literal> extension, these
    statistics can be obtained through three API calls:
  </para>

  <itemizedlist>

    <listitem>
      <para>
        <function>mysqli_get_client_stats</function>
      </para>
    </listitem>

    <listitem>
      <para>
        <function>mysqli_get_connection_stats</function>
      </para>
    </listitem>

    <listitem>
      <para>
        <function>mysqli_get_cache_stats</function>
      </para>
    </listitem>

  </itemizedlist>

  <note>
    <para>
      Statistics are aggregated among all extensions that use MySQL
      Native Driver. For example, when compiling both
      <literal>ext/mysql</literal> and <literal>ext/mysqli</literal>
      against MySQL Native Driver, both function calls of
      <literal>ext/mysql</literal> and <literal>ext/mysqli</literal>
      will change the statistics. There is no way to find out to find
      out how much a certain API call of any extension that has been
      compiled against MySQL Native Driver has impacted a certain
      statistic. You can configure the PDO MySQL Driver,
      <literal>ext/mysql</literal> and <literal>ext/mysqli</literal> to
      optionally use the MySQL Native Driver. When doing so, all three
      extensions will change the statistics.
    </para>
  </note>

  <para>
    <emphasis role="bold">Accessing Client Statistics</emphasis>
  </para>

  <para>
    To access client statistics, you need to call
    <function>mysqli_get_client_stats</function>. The function call does
    not require any parameters.
  </para>

  <para>
    The function returns an associative array that contains the name of
    the statistic as the key and the statistical data as the value.
  </para>

  <para>
    Client statistics can also be accessed by calling the
    <function>phpinfo</function> function.
  </para>

  <para>
    <emphasis role="bold">Accessing Connection Statistics</emphasis>
  </para>

  <para>
    To access connection statistics call
    <function>mysqli_get_connection_stats</function>. This takes the
    database connection handle as the parameter.
  </para>

  <para>
    The function returns an associative array that contains the name of
    the statistic as the key and the statistical data as the value.
  </para>

  <para>
    <emphasis role="bold">Accessing Zval Cache Statistics</emphasis>
  </para>

  <para>
    The MySQL Native Driver also collects statistics from its internal
    Zval cache. These statistics can be accessed by calling
    <function>mysqli_get_cache_stats</function>.
  </para>

  <para>
    The Zval cache statistics obtained may lead to a tweaking of
    <filename>php.ini</filename> settings related to the Zval cache,
    resulting in better performance.
  </para>

  <para>
    <emphasis role="bold">Statistics returned by MySQL Native
    Driver</emphasis>
  </para>

  <para>
    The following table shows a list of statistics returned by the
    <function>mysqli_get_client_stats</function>,
    <function>mysqli_get_connections_stats</function> and
    <function>mysqli_get_cache_stats</function> functions.
  </para>

  <informaltable>
    <tgroup cols="1">
      <colspec colwidth="30*"/>
      <tbody>
        <row>
          <entry><emphasis role="bold">Statistic</emphasis></entry>
        </row>
        <row>
          <entry>bytes_sent</entry>
        </row>
        <row>
          <entry>bytes_received</entry>
        </row>
        <row>
          <entry>packets_sent</entry>
        </row>
        <row>
          <entry>packets_received</entry>
        </row>
        <row>
          <entry>protocol_overhead_in</entry>
        </row>
        <row>
          <entry>protocol_overhead_out</entry>
        </row>
        <row>
          <entry>bytes_received_ok_packet</entry>
        </row>
        <row>
          <entry>bytes_received_eof_packet</entry>
        </row>
        <row>
          <entry>bytes_received_rset_header_packet</entry>
        </row>
        <row>
          <entry>bytes_received_rset_field_meta_packet</entry>
        </row>
        <row>
          <entry>bytes_received_rset_row_packet</entry>
        </row>
        <row>
          <entry>bytes_received_prepare_response_packet</entry>
        </row>
        <row>
          <entry>bytes_received_change_user_packet</entry>
        </row>
        <row>
          <entry>packets_sent_command</entry>
        </row>
        <row>
          <entry>packets_received_ok</entry>
        </row>
        <row>
          <entry>packets_received_eof</entry>
        </row>
        <row>
          <entry>packets_received_rset_header</entry>
        </row>
        <row>
          <entry>packets_received_rset_field_meta</entry>
        </row>
        <row>
          <entry>packets_received_rset_row</entry>
        </row>
        <row>
          <entry>packets_received_prepare_response</entry>
        </row>
        <row>
          <entry>packets_received_change_user</entry>
        </row>
        <row>
          <entry>result_set_queries</entry>
        </row>
        <row>
          <entry>non_result_set_queries</entry>
        </row>
        <row>
          <entry>no_index_used</entry>
        </row>
        <row>
          <entry>bad_index_used</entry>
        </row>
        <row>
          <entry>slow_queries</entry>
        </row>
        <row>
          <entry>buffered_sets</entry>
        </row>
        <row>
          <entry>unbuffered_sets</entry>
        </row>
        <row>
          <entry>ps_buffered_sets</entry>
        </row>
        <row>
          <entry>ps_unbuffered_sets</entry>
        </row>
        <row>
          <entry>flushed_normal_sets</entry>
        </row>
        <row>
          <entry>flushed_ps_sets</entry>
        </row>
        <row>
          <entry>ps_prepared_never_executed</entry>
        </row>
        <row>
          <entry>ps_prepared_once_executed</entry>
        </row>
        <row>
          <entry>rows_fetched_from_server_normal</entry>
        </row>
        <row>
          <entry>rows_fetched_from_server_ps</entry>
        </row>
        <row>
          <entry>rows_buffered_from_client_normal</entry>
        </row>
        <row>
          <entry>rows_buffered_from_client_ps</entry>
        </row>
        <row>
          <entry>rows_fetched_from_client_normal_buffered</entry>
        </row>
        <row>
          <entry>rows_fetched_from_client_normal_unbuffered</entry>
        </row>
        <row>
          <entry>rows_fetched_from_client_ps_buffered</entry>
        </row>
        <row>
          <entry>rows_fetched_from_client_ps_unbuffered</entry>
        </row>
        <row>
          <entry>rows_fetched_from_client_ps_cursor</entry>
        </row>
        <row>
          <entry>rows_skipped_normal</entry>
        </row>
        <row>
          <entry>rows_skipped_ps</entry>
        </row>
        <row>
          <entry>copy_on_write_saved</entry>
        </row>
        <row>
          <entry>copy_on_write_performed</entry>
        </row>
        <row>
          <entry>command_buffer_too_small</entry>
        </row>
        <row>
          <entry>connect_success</entry>
        </row>
        <row>
          <entry>connect_failure</entry>
        </row>
        <row>
          <entry>connection_reused</entry>
        </row>
        <row>
          <entry>reconnect</entry>
        </row>
        <row>
          <entry>pconnect_success</entry>
        </row>
        <row>
          <entry>active_connections</entry>
        </row>
        <row>
          <entry>active_persistent_connections</entry>
        </row>
        <row>
          <entry>explicit_close</entry>
        </row>
        <row>
          <entry>implicit_close</entry>
        </row>
        <row>
          <entry>disconnect_close</entry>
        </row>
        <row>
          <entry>in_middle_of_command_close</entry>
        </row>
        <row>
          <entry>explicit_free_result</entry>
        </row>
        <row>
          <entry>implicit_free_result</entry>
        </row>
        <row>
          <entry>explicit_stmt_close</entry>
        </row>
        <row>
          <entry>implicit_stmt_close</entry>
        </row>
        <row>
          <entry>mem_emalloc_count</entry>
        </row>
        <row>
          <entry>mem_emalloc_ammount</entry>
        </row>
        <row>
          <entry>mem_ecalloc_count</entry>
        </row>
        <row>
          <entry>mem_ecalloc_ammount</entry>
        </row>
        <row>
          <entry>mem_erealloc_count</entry>
        </row>
        <row>
          <entry>mem_erealloc_ammount</entry>
        </row>
        <row>
          <entry>mem_efree_count</entry>
        </row>
        <row>
          <entry>mem_malloc_count</entry>
        </row>
        <row>
          <entry>mem_malloc_ammount</entry>
        </row>
        <row>
          <entry>mem_calloc_count</entry>
        </row>
        <row>
          <entry>mem_calloc_ammount</entry>
        </row>
        <row>
          <entry>mem_realloc_count</entry>
        </row>
        <row>
          <entry>mem_realloc_ammount</entry>
        </row>
        <row>
          <entry>mem_free_count</entry>
        </row>
        <row>
          <entry>proto_text_fetched_null</entry>
        </row>
        <row>
          <entry>proto_text_fetched_bit</entry>
        </row>
        <row>
          <entry>proto_text_fetched_tinyint</entry>
        </row>
        <row>
          <entry>proto_text_fetched_short</entry>
        </row>
        <row>
          <entry>proto_text_fetched_int24</entry>
        </row>
        <row>
          <entry>proto_text_fetched_int</entry>
        </row>
        <row>
          <entry>proto_text_fetched_bigint</entry>
        </row>
        <row>
          <entry>proto_text_fetched_decimal</entry>
        </row>
        <row>
          <entry>proto_text_fetched_float</entry>
        </row>
        <row>
          <entry>proto_text_fetched_double</entry>
        </row>
        <row>
          <entry>proto_text_fetched_date</entry>
        </row>
        <row>
          <entry>proto_text_fetched_year</entry>
        </row>
        <row>
          <entry>proto_text_fetched_time</entry>
        </row>
        <row>
          <entry>proto_text_fetched_datetime</entry>
        </row>
        <row>
          <entry>proto_text_fetched_timestamp</entry>
        </row>
        <row>
          <entry>proto_text_fetched_string</entry>
        </row>
        <row>
          <entry>proto_text_fetched_blob</entry>
        </row>
        <row>
          <entry>proto_text_fetched_enum</entry>
        </row>
        <row>
          <entry>proto_text_fetched_set</entry>
        </row>
        <row>
          <entry>proto_text_fetched_geometry</entry>
        </row>
        <row>
          <entry>proto_text_fetched_other</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_null</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_bit</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_tinyint</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_short</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_int24</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_int</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_bigint</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_decimal</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_float</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_double</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_date</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_year</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_time</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_datetime</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_timestamp</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_string</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_blob</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_enum</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_set</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_geometry</entry>
        </row>
        <row>
          <entry>proto_binary_fetched_other</entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>

</chapter>
<!-- 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
-->