mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Added details of mysqlnd plugin API. Updates/additions.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@304187 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Anthony Bedford
parent
b8cb804607
commit
a6a644ebe2
4 changed files with 1649 additions and 96 deletions
|
|
@ -26,6 +26,7 @@
|
|||
&reference.mysqlnd.persist;
|
||||
&reference.mysqlnd.stats;
|
||||
&reference.mysqlnd.notes;
|
||||
&reference.mysqlnd.plugin;
|
||||
|
||||
</book>
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
|
|
|||
|
|
@ -31,11 +31,29 @@
|
|||
<entry>Available since PHP 5.3.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><link linkend="mysqlnd.log_mask">mysqlnd.log_mask</link></entry>
|
||||
<entry><link linkend="mysqlnd.debug">mysqlnd.debug</link></entry>
|
||||
<entry>"0"</entry>
|
||||
<entry>PHP_INI_SYSTEM</entry>
|
||||
<entry>Available since PHP 5.3.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><link linkend="mysqlnd.net_read_timeout">mysqlnd.net_read_timeout</link></entry>
|
||||
<entry>"31536000"</entry>
|
||||
<entry>PHP_INI_SYSTEM</entry>
|
||||
<entry>Available since PHP 5.3.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><link linkend="mysqlnd.net_cmd_buffer_size">mysqlnd.net_cmd_buffer_size</link></entry>
|
||||
<entry>5.3.0 - "2048", 5.3.1 - "4096"</entry>
|
||||
<entry>PHP_INI_SYSTEM</entry>
|
||||
<entry>Available since PHP 5.3.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><link linkend="mysqlnd.net_read_buffer_size">mysqlnd.net_read_buffer_size</link></entry>
|
||||
<entry>"32768"</entry>
|
||||
<entry>PHP_INI_SYSTEM</entry>
|
||||
<entry>Available since PHP 5.3.0.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
|
@ -89,79 +107,138 @@
|
|||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="mysqlnd.log_mask">
|
||||
<varlistentry xml:id="mysqlnd.debug">
|
||||
<term>
|
||||
<parameter>mysqlnd.log_mask</parameter> <type>integer</type>
|
||||
<parameter>mysqlnd.debug</parameter> <type>boolean</type>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The PHP configuration setting <literal>mysqlnd.log_mask</literal>
|
||||
defines which queries will be logged. The default is
|
||||
mysqlnd.log_mask = "0", which disables logging.
|
||||
Records everything from all extensions using
|
||||
<literal>mysqlnd</literal>. Only available with a debug build of
|
||||
PHP.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="mysqlnd.net_read_timeout">
|
||||
<term>
|
||||
<parameter>mysqlnd.net_read_timeout</parameter>
|
||||
<type>integer</type>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
<literal>mysqlnd</literal> and the MySQL Client Library,
|
||||
<literal>libmysql</literal> use different networking APIs.
|
||||
<literal>mysqlnd</literal> uses PHP streams, whereas
|
||||
<literal>libmysql</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
|
||||
365 * 24 * 3600 seconds (1 year) 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="mysqlnd.net_cmd_buffer_size">
|
||||
<term>
|
||||
<parameter>mysqlnd.net_cmd_buffer_size</parameter>
|
||||
<type>long</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>
|
||||
This setting can have values assigned according to the following
|
||||
table:
|
||||
</para>
|
||||
<informaltable>
|
||||
<tgroup cols="2">
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_IN_TRANS</entry>
|
||||
<entry>1</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_AUTOCOMMIT</entry>
|
||||
<entry>2</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_MORE_RESULTS_EXISTS</entry>
|
||||
<entry>8</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_QUERY_NO_GOOD_INDEX_USED</entry>
|
||||
<entry>16</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_QUERY_NO_INDEX_USED</entry>
|
||||
<entry>32</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_CURSOR_EXISTS</entry>
|
||||
<entry>64</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_LAST_ROW_SENT</entry>
|
||||
<entry>128</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_DB_DROPPED</entry>
|
||||
<entry>256</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_STATUS_NO_BACKSLASH_ESCAPES</entry>
|
||||
<entry>512</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SERVER_QUERY_WAS_SLOW</entry>
|
||||
<entry>1024</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
<para>
|
||||
It is possible to add the values together, to log multiple query
|
||||
types. For example, you can set it to 16 + 32 = 48 to 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).
|
||||
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>
|
||||
Note, the SERVER_* constants are MySQL internal (C-level)
|
||||
constants, not exported to the PHP userland. There are no
|
||||
corresponding PHP constants. However, you can look up the values
|
||||
in the table which has been created by inspecting the MySQL Native
|
||||
Driver source.
|
||||
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 <filename>php.ini</filename> setting
|
||||
<literal>mysqlnd.net_cmd_buffer_size</literal> or using
|
||||
<literal>mysqli_options(MYSQLI_OPT_NET_CMD_BUFFER_SIZE, int
|
||||
size)</literal>.
|
||||
</para>
|
||||
<para>
|
||||
It is recommended that the buffer size be set to no less than 4096
|
||||
bytes because <literal>mysqlnd</literal> also uses it when reading
|
||||
certain communication packet from MySQL. In PHP 5.3.0,
|
||||
<literal>mysqlnd</literal> will not grow the buffer if MySQL sends
|
||||
a packet that is larger than the current size of the buffer. As a
|
||||
consequence, <literal>mysqlnd</literal> 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 <literal>mysqlnd.net_cmd_buffer_size</literal> in
|
||||
PHP 5.3.0: the packet transports a very long error message, or the
|
||||
packet holds column meta data from
|
||||
<literal>COM_LIST_FIELD</literal>
|
||||
(<literal>mysql_list_fields()</literal> and the meta data come
|
||||
from a string column with a very long default value (>1900 bytes).
|
||||
</para>
|
||||
<para>
|
||||
As of PHP 5.3.2 mysqlnd does not allow setting buffers smaller
|
||||
than 4096 bytes.
|
||||
</para>
|
||||
<para>
|
||||
The value can also be set using <literal>mysqli_option(link,
|
||||
MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="mysqlnd.net_read_buffer_size">
|
||||
<term>
|
||||
<parameter>mysqlnd.net_read_buffer_size</parameter>
|
||||
<type>long</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>
|
||||
|
|
|
|||
|
|
@ -43,16 +43,12 @@
|
|||
the MySQL Client Library.
|
||||
</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.
|
||||
The older MySQL Client Library was written by MySQL AB (now Oracle
|
||||
Corporation) 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
|
||||
|
|
@ -66,18 +62,16 @@
|
|||
installed in order to build PHP or run PHP database applications.
|
||||
</para>
|
||||
<para>
|
||||
With MySQL Native Driver it is also possible to write plugins. These
|
||||
are PHP extensions written to use the MySQL Native Driver Plugin API,
|
||||
and they can extend the functionality of the driver without requiring
|
||||
changes to application level code.
|
||||
</para>
|
||||
<para>
|
||||
The older MySQL Client Library was written by MySQL AB (now Oracle
|
||||
Corporation) 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.
|
||||
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>
|
||||
|
|
@ -106,13 +100,6 @@
|
|||
<function>mysqli_get_connection_stats</function>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Asynchronous queries:
|
||||
<function>mysqli_poll</function>,
|
||||
<function>mysqli_reap_async_query</function>
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>
|
||||
The performance statistics facility can prove to be very useful in
|
||||
|
|
@ -126,7 +113,7 @@
|
|||
<emphasis role="bold">SSL Support</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
MySQL Native Driver supports SSL from PHP version 5.3.3.
|
||||
MySQL Native Driver has supported SSL since PHP version 5.3.3
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="bold">Compressed Protocol Support</emphasis>
|
||||
|
|
@ -139,6 +126,12 @@
|
|||
configured to use MySQL Native Driver, can also take advantage of this
|
||||
feature.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="bold">Named Pipes Support</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Named pipes support for Windows was added in PHP version 5.3.4.
|
||||
</para>
|
||||
</chapter>
|
||||
<!-- Keep this comment at the end of the file
|
||||
Local variables:
|
||||
|
|
|
|||
1482
reference/mysqlnd/plugin.xml
Normal file
1482
reference/mysqlnd/plugin.xml
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Reference in a new issue