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

  &reftitle.runtime;
  &extension.runtime;

  <para>
  <table xml:id="mysqlnd.config.options">
   <title>MySQL Native Driver Configuration Options</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>&Name;</entry>
      <entry>&Default;</entry>
      <entry>&Changeable;</entry>
      <entry>&Changelog;</entry>
     </row>
    </thead>
    <tbody xml:id="mysqlnd.config.options.list">
     <row>
      <entry><link linkend="ini.mysqlnd.collect-statistics">mysqlnd.collect_statistics</link></entry>
      <entry>"1"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.collect-memory-statistics">mysqlnd.collect_memory_statistics</link></entry>
      <entry>"0"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.debug">mysqlnd.debug</link></entry>
      <entry>""</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.log-mask">mysqlnd.log_mask</link></entry>
      <entry>0</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.mempool-default-size">mysqlnd.mempool_default_size</link></entry>
      <entry>16000</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-read-timeout">mysqlnd.net_read_timeout</link></entry>
      <entry>"86400"</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry>
       Before PHP 7.2.0 the default value was "31536000"
       and the changeability was <constant>INI_SYSTEM</constant>
      </entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-cmd-buffer-size">mysqlnd.net_cmd_buffer_size</link></entry>
      <entry>"4096"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.net-read-buffer-size">mysqlnd.net_read_buffer_size</link></entry>
      <entry>"32768"</entry>
      <entry><constant>INI_SYSTEM</constant></entry>
      <entry></entry>
     </row>
     <row>
      <entry><link linkend="ini.mysqlnd.sha256-server-public-key">mysqlnd.sha256_server_public_key</link></entry>
      <entry>""</entry>
      <entry><constant>INI_PERDIR</constant></entry>
      <entry></entry>
     </row>
      <row>
       <entry><link linkend="ini.mysqlnd.trace-alloc">mysqlnd.trace_alloc</link></entry>
       <entry>""</entry>
       <entry><constant>INI_SYSTEM</constant></entry>
       <entry></entry>
      </row>
     <row>
      <entry><link linkend="ini.mysqlnd.fetch_data_copy">mysqlnd.fetch_data_copy</link></entry>
      <entry>0</entry>
      <entry><constant>INI_ALL</constant></entry>
      <entry>Removed as of PHP 8.1.0</entry>
     </row>
    </tbody>
   </tgroup>
  </table>
  &ini.php.constants;
 </para>

  &ini.descriptions.title;

  <para>
  <variablelist>
   <varlistentry xml:id="ini.mysqlnd.collect-statistics">
    <term>
     <parameter>mysqlnd.collect_statistics</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      Enables the collection of various client statistics which can be
      accessed through <function>mysqli_get_client_stats</function>,
      <function>mysqli_get_connection_stats</function>,
      and are shown in
      <literal>mysqlnd</literal> section of the output of the
      <function>phpinfo</function> function as well.
     </para>
     <para>
      This configuration setting enables all
      <link linkend="mysqlnd.stats">MySQL Native Driver
      statistics</link> except those relating to memory management.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.collect-memory-statistics">
    <term>
     <parameter>mysqlnd.collect_memory_statistics</parameter>
     <type>bool</type>
    </term>
    <listitem>
     <para>
      Enable the collection of various memory statistics which can be
      accessed through <function>mysqli_get_client_stats</function>,
      <function>mysqli_get_connection_stats</function>,
      and are shown in
      <literal>mysqlnd</literal> section of the output of the
      <function>phpinfo</function> function as well.
     </para>
     <para>
      This configuration setting enables the memory management
      statistics within the overall set of
      <link linkend="mysqlnd.stats">MySQL Native Driver
      statistics</link>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.debug">
    <term>
     <parameter>mysqlnd.debug</parameter> <type>string</type>
    </term>
    <listitem>
     <para>
      Records communication from all extensions using
      <literal>mysqlnd</literal> to the specified log file.
     </para>
     <para>
      The format of the directive is <literal>mysqlnd.debug =
      "option1[,parameter_option1][:option2[,parameter_option2]]"</literal>.
     </para>
     <para>
      The options for the format string are as follows:
     </para>
     <itemizedlist>
      <listitem>
       <para>
        A[,file] - Appends trace output to specified file. Also ensures
        that data is written after each write. This is done by closing
        and reopening the trace file (this is slow). It helps ensure a
        complete log file should the application crash.
       </para>
      </listitem>
      <listitem>
       <para>
        a[,file] - Appends trace output to the specified file.
       </para>
      </listitem>
      <listitem>
       <para>
        d - Enables output from DBUG_&lt;N&gt; macros for the current
        state. May be followed by a list of keywords which selects
        output only for the DBUG macros with that keyword. An empty list
        of keywords implies output for all macros.
       </para>
      </listitem>
      <listitem>
       <para>
        f[,functions] - Limits debugger actions to the specified list of
        functions. An empty list of functions implies that all functions
        are selected.
       </para>
      </listitem>
      <listitem>
       <para>
        F - Marks each debugger output line with the name of the source
        file containing the macro causing the output.
       </para>
      </listitem>
      <listitem>
       <para>
        i - Marks each debugger output line with the PID of the current
        process.
       </para>
      </listitem>
      <listitem>
       <para>
        L - Marks each debugger output line with the name of the source
        file line number of the macro causing the output.
       </para>
      </listitem>
      <listitem>
       <para>
        n - Marks each debugger output line with the current function
        nesting depth
       </para>
      </listitem>
      <listitem>
       <para>
        o[,file] - Similar to a[,file] but overwrites old file, and does
        not append.
       </para>
      </listitem>
      <listitem>
       <para>
        O[,file] - Similar to A[,file] but overwrites old file, and does
        not append.
       </para>
      </listitem>
      <listitem>
       <para>
        t[,N] - Enables function control flow tracing. The maximum
        nesting depth is specified by N, and defaults to 200.
       </para>
      </listitem>
      <listitem>
       <para>
        x - This option activates profiling.
       </para>
      </listitem>
       <listitem>
       <para>
        m - Trace memory allocation and deallocation related calls.
       </para>
      </listitem>
     </itemizedlist>
     <para>
      Example:
     </para>
<programlisting>
<![CDATA[
d:t:x:O,/tmp/mysqlnd.trace
]]>
</programlisting>
     <note>
      <para>
       This feature is only available with a debug build of PHP.
      </para>
     </note>
     <para></para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.log-mask">
    <term>
     <parameter>mysqlnd.log_mask</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Defines which queries will be logged. The default 0, which disables logging.
      Define using an integer, and not with PHP constants. For example, a value of
      48 (16 + 32) will log slow queries which either use 'no good index'
      (SERVER_QUERY_NO_GOOD_INDEX_USED = 16) or no index at all (SERVER_QUERY_NO_INDEX_USED = 32).
      A value of 2043 (1 + 2 + 8 + ... + 1024) will log all slow query types.
     </para>
     <para>
      The types are as follows: SERVER_STATUS_IN_TRANS=1, SERVER_STATUS_AUTOCOMMIT=2,
      SERVER_MORE_RESULTS_EXISTS=8, SERVER_QUERY_NO_GOOD_INDEX_USED=16, SERVER_QUERY_NO_INDEX_USED=32,
      SERVER_STATUS_CURSOR_EXISTS=64, SERVER_STATUS_LAST_ROW_SENT=128, SERVER_STATUS_DB_DROPPED=256,
      SERVER_STATUS_NO_BACKSLASH_ESCAPES=512, and SERVER_QUERY_WAS_SLOW=1024.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.mempool-default-size">
    <term>
     <parameter>mysqlnd.mempool_default_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Default size of the mysqlnd memory pool, which is used by result sets.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-read-timeout">
    <term>
     <parameter>mysqlnd.net_read_timeout</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      <literal>mysqlnd</literal> and the MySQL Client Library,
      <literal>libmysqlclient</literal> use different networking APIs.
      <literal>mysqlnd</literal> uses PHP streams, whereas
      <literal>libmysqlclient</literal> uses its own wrapper around the
      operating level network calls. PHP, by default, sets a read
      timeout of 60s for streams. This is set via
      <filename>php.ini</filename>,
      <literal>default_socket_timeout</literal>. This default applies to
      all streams that set no other timeout value.
      <literal>mysqlnd</literal> does not set any other value and
      therefore connections of long running queries can be disconnected
      after <literal>default_socket_timeout</literal> seconds resulting
      in an error message <quote>2006 - MySQL Server has gone
      away</quote>. The MySQL Client Library sets a default timeout of
      24 * 3600 seconds (1 day) and waits for other timeouts to
      occur, such as TCP/IP timeouts. <literal>mysqlnd</literal> now
      uses the same very long timeout. The value is configurable through
      a new <filename>php.ini</filename> setting:
      <literal>mysqlnd.net_read_timeout</literal>.
      <literal>mysqlnd.net_read_timeout</literal> gets used by any
      extension (<literal>ext/mysql</literal>,
      <literal>ext/mysqli</literal>, <literal>PDO_MySQL</literal>) that
      uses <literal>mysqlnd</literal>. <literal>mysqlnd</literal> tells
      PHP Streams to use <literal>mysqlnd.net_read_timeout</literal>.
      Please note that there may be subtle differences between
      <literal>MYSQL_OPT_READ_TIMEOUT</literal> from the MySQL Client
      Library and PHP Streams, for example
      <literal>MYSQL_OPT_READ_TIMEOUT</literal> is documented to work
      only for TCP/IP connections and, prior to MySQL 5.1.2, only for
      Windows. PHP streams may not have this limitation. Please check
      the streams documentation, if in doubt.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-cmd-buffer-size">
    <term>
     <parameter>mysqlnd.net_cmd_buffer_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      <literal>mysqlnd</literal> allocates an internal command/network
      buffer of <literal>mysqlnd.net_cmd_buffer_size</literal> (in
      <filename>php.ini</filename>) bytes for every connection. If a
      MySQL Client Server protocol command, for example,
      <literal>COM_QUERY</literal> (<quote>normal</quote> query), does
      not fit into the buffer, <literal>mysqlnd</literal> will grow the
      buffer to the size required for sending the command. Whenever the
      buffer gets extended for one connection,
      <literal>command_buffer_too_small</literal> will be incremented by
      one.
     </para>
     <para>
      If <literal>mysqlnd</literal> has to grow the buffer beyond its
      initial size of <literal>mysqlnd.net_cmd_buffer_size</literal>
      bytes for almost every connection, you should consider increasing
      the default size to avoid re-allocations.
     </para>
     <para>
      The default buffer size is 4096 bytes, which is the smallest value possible.
     </para>
     <para>
      The value can also be set using <literal>mysqli_options(link,
      MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)</literal>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.net-read-buffer-size">
    <term>
     <parameter>mysqlnd.net_read_buffer_size</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Maximum read chunk size in bytes when reading the body of a MySQL
      command packet. The MySQL client server protocol encapsulates all
      its commands in packets. The packets consist of a small header and
      a body with the actual payload. The size of the body is encoded in
      the header. <literal>mysqlnd</literal> reads the body in chunks of
      <literal>MIN(header.size, mysqlnd.net_read_buffer_size)</literal>
      bytes. If a packet body is larger than
      <literal>mysqlnd.net_read_buffer_size</literal> bytes,
      <literal>mysqlnd</literal> has to call <literal>read()</literal>
      multiple times.
     </para>
     <para>
      The value can also be set using <literal>mysqli_options(link,
      MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)</literal>.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.sha256-server-public-key">
    <term>
     <parameter>mysqlnd.sha256_server_public_key</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
      SHA-256 Authentication Plugin related. File with the MySQL server
      public RSA key.
     </para>
     <para>
      Clients can either omit setting a public RSA key, specify the key through
      this PHP configuration setting or set the key at runtime using
      <function>mysqli_options</function>. If not public RSA key file is
      given by the client, then the key will be exchanged as part of the
      standard SHA-256 Authentication Plugin authentication procedure.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.trace-alloc">
    <term>
     <parameter>mysqlnd.trace_alloc</parameter>
     <type>string</type>
    </term>
    <listitem>
     <para>
     </para>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="ini.mysqlnd.fetch_data_copy">
    <term>
     <parameter>mysqlnd.fetch_data_copy</parameter>
     <type>int</type>
    </term>
    <listitem>
     <para>
      Enforce copying result sets from the internal
      result set buffers into PHP variables instead of using the default
      reference and copy-on-write logic. Please, see the
      <link linkend="mysqlnd.memory">memory management implementation notes</link>
      for further details.
     </para>
     <para>
      Copying result sets instead of having PHP variables reference
      them allows releasing the memory occupied for the PHP variables earlier.
      Depending on the user API code, the actual database quries and the
      size of their result sets this may reduce the memory footprint
      of mysqlnd.
     </para>
     <para>
       Do not set if using PDO_MySQL. PDO_MySQL has not yet been updated to support
       the new fetch mode.
     </para>
    <note>
     <simpara>Removed as of PHP 8.1.0</simpara>
    </note>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</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
-->