<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <title>Runtime Configuration</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd.install.html">Installation</a></div> <div class="next" style="text-align: right; float: right;"><a href="mysqlnd.incompatibilities.html">Incompatibilities</a></div> <div class="up"><a href="book.mysqlnd.html">Mysqlnd</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="mysqlnd.config" class="chapter"> <h1>Runtime Configuration</h1> <p class="simpara"> The behaviour of these functions is affected by settings in <var class="filename">php.ini</var>. </p> <p class="para"> <table class="doctable table"> <caption><strong>MySQL Native Driver Configuration Options</strong></caption> <thead> <tr> <th>Name</th> <th>Default</th> <th>Changeable</th> <th>Changelog</th> </tr> </thead> <tbody class="tbody"> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.collect-statistics" class="link">mysqlnd.collect_statistics</a></td> <td>"1"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.collect-memory-statistics" class="link">mysqlnd.collect_memory_statistics</a></td> <td>"0"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.debug" class="link">mysqlnd.debug</a></td> <td>"0"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.ini.mysqlnd.log-mask" class="link">mysqlnd.log_mask</a></td> <td>0</td> <td>PHP_INI_ALL</td> <td>Available since PHP 5.3.0</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.ini.mysqlnd.mempool-default-size" class="link">mysqlnd.mempool_default_size</a></td> <td>16000</td> <td>PHP_INI_ALL</td> <td>Available since PHP 5.3.3</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.net-read-timeout" class="link">mysqlnd.net_read_timeout</a></td> <td>"31536000"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.net-cmd-buffer-size" class="link">mysqlnd.net_cmd_buffer_size</a></td> <td>5.3.0 - "2048", 5.3.1 - "4096"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.net-read-buffer-size" class="link">mysqlnd.net_read_buffer_size</a></td> <td>"32768"</td> <td>PHP_INI_SYSTEM</td> <td>Available since PHP 5.3.0.</td> </tr> <tr> <td><a href="mysqlnd.config.html#ini.mysqlnd.sha256-server-public-key" class="link">mysqlnd.sha256_server_public_key</a></td> <td>""</td> <td>PHP_INI_PERDIR</td> <td>Available since PHP 5.5.0.</td> </tr> </tbody> </table> For further details and definitions of the PHP_INI_* modes, see the <a href="configuration.changes.modes.html" class="xref">Where a configuration setting may be set</a>. </p> <p class="para">Here's a short explanation of the configuration directives.</p> <p class="para"> <dl> <dt id="ini.mysqlnd.collect-statistics"> <span class="term"> <em><code class="parameter">mysqlnd.collect_statistics</code></em> <span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span> </span> <dd> <p class="para"> Enables the collection of various client statistics which can be accessed through <span class="function"><a href="mysqli.get-client-stats.html" class="function">mysqli_get_client_stats()</a></span>, <span class="function"><a href="mysqli.get-connection-stats.html" class="function">mysqli_get_connection_stats()</a></span>, <span class="function"><a href="function.mysqli-get-cache-stats.html" class="function">mysqli_get_cache_stats()</a></span> and are shown in <em>mysqlnd</em> section of the output of the <span class="function"><a href="function.phpinfo.html" class="function">phpinfo()</a></span> function as well. </p> <p class="para"> This configuration setting enables all <a href="mysqlnd.stats.html" class="link">MySQL Native Driver statistics</a> except those relating to memory management. </p> </dd> </dt> <dt id="ini.mysqlnd.collect-memory-statistics"> <span class="term"> <em><code class="parameter">mysqlnd.collect_memory_statistics</code></em> <span class="type"><a href="language.types.boolean.html" class="type boolean">boolean</a></span> </span> <dd> <p class="para"> Enable the collection of various memory statistics which can be accessed through <span class="function"><a href="mysqli.get-client-stats.html" class="function">mysqli_get_client_stats()</a></span>, <span class="function"><a href="mysqli.get-connection-stats.html" class="function">mysqli_get_connection_stats()</a></span>, <span class="function"><a href="function.mysqli-get-cache-stats.html" class="function">mysqli_get_cache_stats()</a></span> and are shown in <em>mysqlnd</em> section of the output of the <span class="function"><a href="function.phpinfo.html" class="function">phpinfo()</a></span> function as well. </p> <p class="para"> This configuration setting enables the memory management statistics within the overall set of <a href="mysqlnd.stats.html" class="link">MySQL Native Driver statistics</a>. </p> </dd> </dt> <dt id="ini.mysqlnd.debug"> <span class="term"> <em><code class="parameter">mysqlnd.debug</code></em> <span class="type"><a href="language.types.string.html" class="type string">string</a></span> </span> <dd> <p class="para"> Records communication from all extensions using <em>mysqlnd</em> to the specified log file. </p> <p class="para"> The format of the directive is <em>mysqlnd.debug = "option1[,parameter_option1][:option2[,parameter_option2]]"</em>. </p> <p class="para"> The options for the format string are as follows: </p> <ul class="itemizedlist"> <li class="listitem"> <p class="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. </p> </li> <li class="listitem"> <p class="para"> a[,file] - Appends trace output to the specified file. </p> </li> <li class="listitem"> <p class="para"> d - Enables output from DBUG_<N> 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. </p> </li> <li class="listitem"> <p class="para"> f[,functions] - Limits debugger actions to the specified list of functions. An empty list of functions implies that all functions are selected. </p> </li> <li class="listitem"> <p class="para"> F - Marks each debugger output line with the name of the source file containing the macro causing the output. </p> </li> <li class="listitem"> <p class="para"> i - Marks each debugger output line with the PID of the current process. </p> </li> <li class="listitem"> <p class="para"> L - Marks each debugger output line with the name of the source file line number of the macro causing the output. </p> </li> <li class="listitem"> <p class="para"> n - Marks each debugger output line with the current function nesting depth </p> </li> <li class="listitem"> <p class="para"> o[,file] - Similar to a[,file] but overwrites old file, and does not append. </p> </li> <li class="listitem"> <p class="para"> O[,file] - Similar to A[,file] but overwrites old file, and does not append. </p> </li> <li class="listitem"> <p class="para"> t[,N] - Enables function control flow tracing. The maximum nesting depth is specified by N, and defaults to 200. </p> </li> <li class="listitem"> <p class="para"> x - This option activates profiling. </p> </li> </ul> <p class="para"> Example: </p> <div class="example-contents"> <div class="cdata"><pre> d:t:x:O,/tmp/mysqlnd.trace </pre></div> </div> <blockquote class="note"><p><strong class="note">Note</strong>: <p class="para"> This feature is only available with a debug build of PHP. Works on Microsoft Windows if using a debug build of PHP and PHP was built using Microsoft Visual C version 9 and above. </p> </p></blockquote> <p class="para"/> </dd> </dt> <dt id="ini.ini.mysqlnd.log-mask"> <span class="term"> <em><code class="parameter">mysqlnd.log_mask</code></em> <span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span> </span> <dd> <p class="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. </p> <p class="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. </p> </dd> </dt> <dt id="ini.ini.mysqlnd.mempool-default-size"> <span class="term"> <em><code class="parameter">mysqlnd.mempool_default_size</code></em> <span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span> </span> <dd> <p class="para"> Default size of the mysqlnd memory pool, which is used by result sets. </p> </dd> </dt> <dt id="ini.mysqlnd.net-read-timeout"> <span class="term"> <em><code class="parameter">mysqlnd.net_read_timeout</code></em> <span class="type"><a href="language.types.integer.html" class="type integer">integer</a></span> </span> <dd> <p class="para"> <em>mysqlnd</em> and the MySQL Client Library, <em>libmysqlclient</em> use different networking APIs. <em>mysqlnd</em> uses PHP streams, whereas <em>libmysqlclient</em> 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 <var class="filename">php.ini</var>, <em>default_socket_timeout</em>. This default applies to all streams that set no other timeout value. <em>mysqlnd</em> does not set any other value and therefore connections of long running queries can be disconnected after <em>default_socket_timeout</em> seconds resulting in an error message "<span class="quote">2006 - MySQL Server has gone away</span>". The MySQL Client Library sets a default timeout of 365 * 24 * 3600 seconds (1 year) and waits for other timeouts to occur, such as TCP/IP timeouts. <em>mysqlnd</em> now uses the same very long timeout. The value is configurable through a new <var class="filename">php.ini</var> setting: <em>mysqlnd.net_read_timeout</em>. <em>mysqlnd.net_read_timeout</em> gets used by any extension (<em>ext/mysql</em>, <em>ext/mysqli</em>, <em>PDO_MySQL</em>) that uses <em>mysqlnd</em>. <em>mysqlnd</em> tells PHP Streams to use <em>mysqlnd.net_read_timeout</em>. Please note that there may be subtle differences between <em>MYSQL_OPT_READ_TIMEOUT</em> from the MySQL Client Library and PHP Streams, for example <em>MYSQL_OPT_READ_TIMEOUT</em> 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. </p> </dd> </dt> <dt id="ini.mysqlnd.net-cmd-buffer-size"> <span class="term"> <em><code class="parameter">mysqlnd.net_cmd_buffer_size</code></em> <span class="type"><span class="type long">long</span></span> </span> <dd> <p class="para"> <em>mysqlnd</em> allocates an internal command/network buffer of <em>mysqlnd.net_cmd_buffer_size</em> (in <var class="filename">php.ini</var>) bytes for every connection. If a MySQL Client Server protocol command, for example, <em>COM_QUERY</em> ("<span class="quote">normal</span>" query), does not fit into the buffer, <em>mysqlnd</em> will grow the buffer to the size required for sending the command. Whenever the buffer gets extended for one connection, <em>command_buffer_too_small</em> will be incremented by one. </p> <p class="para"> If <em>mysqlnd</em> has to grow the buffer beyond its initial size of <em>mysqlnd.net_cmd_buffer_size</em> bytes for almost every connection, you should consider increasing the default size to avoid re-allocations. </p> <p class="para"> The default buffer size is 2048 bytes in PHP 5.3.0. In later versions the default is 4096 bytes. The default can changed either through the <var class="filename">php.ini</var> setting <em>mysqlnd.net_cmd_buffer_size</em> or using <em>mysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int size)</em>. </p> <p class="para"> It is recommended that the buffer size be set to no less than 4096 bytes because <em>mysqlnd</em> also uses it when reading certain communication packet from MySQL. In PHP 5.3.0, <em>mysqlnd</em> will not grow the buffer if MySQL sends a packet that is larger than the current size of the buffer. As a consequence, <em>mysqlnd</em> is unable to decode the packet and the client application will get an error. There are only two situations when the packet can be larger than the 2048 bytes default of <em>mysqlnd.net_cmd_buffer_size</em> in PHP 5.3.0: the packet transports a very long error message, or the packet holds column meta data from <em>COM_LIST_FIELD</em> (<em>mysql_list_fields()</em> and the meta data come from a string column with a very long default value (>1900 bytes). </p> <p class="para"> As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller than 4096 bytes. </p> <p class="para"> The value can also be set using <em>mysqli_options(link, MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)</em>. </p> </dd> </dt> <dt id="ini.mysqlnd.net-read-buffer-size"> <span class="term"> <em><code class="parameter">mysqlnd.net_read_buffer_size</code></em> <span class="type"><span class="type long">long</span></span> </span> <dd> <p class="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. <em>mysqlnd</em> reads the body in chunks of <em>MIN(header.size, mysqlnd.net_read_buffer_size)</em> bytes. If a packet body is larger than <em>mysqlnd.net_read_buffer_size</em> bytes, <em>mysqlnd</em> has to call <em>read()</em> multiple times. </p> <p class="para"> The value can also be set using <em>mysqli_options(link, MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)</em>. </p> </dd> </dt> <dt id="ini.mysqlnd.sha256-server-public-key"> <span class="term"> <em><code class="parameter">mysqlnd.sha256_server_public_key</code></em> <span class="type"><a href="language.types.string.html" class="type string">string</a></span> </span> <dd> <p class="para"> SHA-256 Authentication Plugin related. File with the MySQL server public RSA key. </p> <p class="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 <span class="function"><a href="mysqli.options.html" class="function">mysqli_options()</a></span>. 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. </p> </dd> </dt> </dl> </p> </div> <hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd.install.html">Installation</a></div> <div class="next" style="text-align: right; float: right;"><a href="mysqlnd.incompatibilities.html">Incompatibilities</a></div> <div class="up"><a href="book.mysqlnd.html">Mysqlnd</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>