php/archived-doc-en
1
0
Fork 0
mirror of https://github.com/php/doc-en.git synced 2026-03-24 07:42:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

mysqlnd : fix XML by converting para to simpara tags via script

Browse Source
This commit is contained in:
Gina Peter Banyard
2026-01-19 03:13:34 +00:00
parent fa98ad518d
commit 9598935f21
10 changed files with 543 additions and 544 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
reference/mysqlnd/book.xml
View File

@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- Membership: bundled, external -->
<book xml:id="book.mysqlnd" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="book.mysqlnd">
<?phpdoc extension-membership="bundledexternal" ?>
<title>MySQL Native Driver</title>
@@ -12,27 +12,27 @@
<preface xml:id="intro.mysqlnd">
&reftitle.intro;
<para>
<simpara>
MySQL Native Driver is a replacement for the MySQL Client Library
(libmysqlclient). MySQL Native Driver is part of the official PHP sources as
of PHP 5.3.0.
</para>
<para>
</simpara>
<simpara>
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>
</simpara>
<simpara>
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>
</simpara>
<simpara>
MySQL Native Driver is written in C as a PHP extension.
</para>
</simpara>
</preface>
<!-- }}} -->

154
reference/mysqlnd/config.xml
View File

@@ -102,19 +102,19 @@
<type>bool</type>
</term>
<listitem>
<para>
<simpara>
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>
</simpara>
<simpara>
This configuration setting enables all
<link linkend="mysqlnd.stats">MySQL Native Driver
statistics</link> except those relating to memory management.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.collect-memory-statistics">
@@ -123,20 +123,20 @@
<type>bool</type>
</term>
<listitem>
<para>
<simpara>
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>
</simpara>
<simpara>
This configuration setting enables the memory management
statistics within the overall set of
<link linkend="mysqlnd.stats">MySQL Native Driver
statistics</link>.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.debug">
@@ -144,113 +144,113 @@
<parameter>mysqlnd.debug</parameter> <type>string</type>
</term>
<listitem>
<para>
<simpara>
Records communication from all extensions using
<literal>mysqlnd</literal> to the specified log file.
</para>
<para>
</simpara>
<simpara>
The format of the directive is <literal>mysqlnd.debug =
"option1[,parameter_option1][:option2[,parameter_option2]]"</literal>.
</para>
<para>
</simpara>
<simpara>
The options for the format string are as follows:
</para>
</simpara>
<itemizedlist>
<listitem>
<para>
<simpara>
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>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
a[,file] - Appends trace output to the specified file.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
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>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
f[,functions] - Limits debugger actions to the specified list of
functions. An empty list of functions implies that all functions
are selected.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
F - Marks each debugger output line with the name of the source
file containing the macro causing the output.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
i - Marks each debugger output line with the PID of the current
process.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
L - Marks each debugger output line with the name of the source
file line number of the macro causing the output.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
n - Marks each debugger output line with the current function
nesting depth
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
o[,file] - Similar to a[,file] but overwrites old file, and does
not append.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
O[,file] - Similar to A[,file] but overwrites old file, and does
not append.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
t[,N] - Enables function control flow tracing. The maximum
nesting depth is specified by N, and defaults to 200.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
x - This option activates profiling.
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
m - Trace memory allocation and deallocation related calls.
</para>
</simpara>
</listitem>
</itemizedlist>
<para>
<simpara>
Example:
</para>
</simpara>
<programlisting>
<![CDATA[
d:t:x:O,/tmp/mysqlnd.trace
]]>
</programlisting>
<note>
<para>
<simpara>
This feature is only available with a debug build of PHP.
</para>
</simpara>
</note>
<para/>
<simpara/>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.log-mask">
@@ -259,19 +259,19 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
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>
</simpara>
<simpara>
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>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.mempool-default-size">
@@ -280,9 +280,9 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
Default size of the mysqlnd memory pool, which is used by result sets.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.net-read-timeout">
@@ -291,7 +291,7 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
<literal>mysqlnd</literal> and the MySQL Client Library,
<literal>libmysqlclient</literal> use different networking APIs.
<literal>mysqlnd</literal> uses PHP streams, whereas
@@ -323,7 +323,7 @@ d:t:x:O,/tmp/mysqlnd.trace
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>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.net-cmd-buffer-size">
@@ -332,7 +332,7 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
<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
@@ -343,20 +343,20 @@ d:t:x:O,/tmp/mysqlnd.trace
buffer gets extended for one connection,
<literal>command_buffer_too_small</literal> will be incremented by
one.
</para>
<para>
</simpara>
<simpara>
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>
</simpara>
<simpara>
The default buffer size is 4096 bytes, which is the smallest value possible.
</para>
<para>
</simpara>
<simpara>
The value can also be set using <literal>mysqli_options(link,
MYSQLI_OPT_NET_CMD_BUFFER_SIZE, size)</literal>.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.net-read-buffer-size">
@@ -365,7 +365,7 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
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
@@ -376,11 +376,11 @@ d:t:x:O,/tmp/mysqlnd.trace
<literal>mysqlnd.net_read_buffer_size</literal> bytes,
<literal>mysqlnd</literal> has to call <literal>read()</literal>
multiple times.
</para>
<para>
</simpara>
<simpara>
The value can also be set using <literal>mysqli_options(link,
MYSQLI_OPT_NET_READ_BUFFER_SIZE, size)</literal>.
</para>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.sha256-server-public-key">
@@ -389,17 +389,17 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>string</type>
</term>
<listitem>
<para>
<simpara>
SHA-256 Authentication Plugin related. File with the MySQL server
public RSA key.
</para>
<para>
</simpara>
<simpara>
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>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.trace-alloc">
@@ -408,8 +408,8 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>string</type>
</term>
<listitem>
<para>
</para>
<simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd.fetch_data_copy">
@@ -418,24 +418,24 @@ d:t:x:O,/tmp/mysqlnd.trace
<type>int</type>
</term>
<listitem>
<para>
<simpara>
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>
</simpara>
<simpara>
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>
</simpara>
<simpara>
Do not set if using PDO_MySQL. PDO_MySQL has not yet been updated to support
the new fetch mode.
</para>
</simpara>
<note>
<simpara>Removed as of PHP 8.1.0</simpara>
</note>

11
reference/mysqlnd/incompatibilities.xml
View File

@@ -1,26 +1,25 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqlnd.incompatibilities" xmlns="http://docbook.org/ns/docbook">
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="mysqlnd.incompatibilities">
<title>Incompatibilities</title>
<para>
<simpara>
MySQL Native Driver is in most cases compatible with MySQL Client Library
(<literal>libmysql</literal>). This section documents incompatibilities
between these libraries.
</para>
</simpara>
<itemizedlist>
<listitem>
<para>
<simpara>
Values of <literal>bit</literal> data type are returned as binary strings
(e.g. "\0" or "\x1F") with <literal>libmysql</literal> and as decimal
strings (e.g. "0" or "31") with <literal>mysqlnd</literal>. If you want the
code to be compatible with both libraries then always return bit fields as
numbers from MySQL with a query like this:
<literal>SELECT bit + 0 FROM table</literal>.
</para>
</simpara>
</listitem>
</itemizedlist>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

32
reference/mysqlnd/install.xml
View File

@@ -4,22 +4,22 @@
<title>Installation</title>
<para>
<simpara>
<emphasis role="bold">Installation on Unix</emphasis>
</para>
</simpara>
<para>
<simpara>
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>
</simpara>
<para>
<simpara>
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>
</simpara>
<programlisting role="shell">
<![CDATA[
@@ -30,26 +30,26 @@
]]>
</programlisting>
<para>
<simpara>
<emphasis role="bold">Installation on Windows</emphasis>
</para>
</simpara>
<para>
<simpara>
In the official PHP Windows distributions, 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>
</simpara>
<para>
<simpara>
<emphasis role="bold">SHA-256 Authentication Plugin support</emphasis>
</para>
</simpara>
<para>
<simpara>
The MySQL Native Driver requires the OpenSSL functionality of PHP to be loaded
and enabled to connect to MySQL through accounts that use the MySQL SHA-256
Authentication Plugin. For example, PHP could be configured using:
</para>
</simpara>
<programlisting role="shell">
<![CDATA[
@@ -61,14 +61,14 @@
]]>
</programlisting>
<para>
<simpara>
In Autotools, the extended SSL support in <literal>mysqlnd</literal> is
enabled implicitly when building together with the <literal>openssl</literal>
extension using the <option role="configure">--with-openssl</option> configure
option. When building without the <literal>openssl</literal> extension, the
<option role="configure">--with-mysqlnd-ssl</option> configure option can be
used to enable extended SSL support explicitly.
</para>
</simpara>
<simplesect role="changelog">
&reftitle.changelog;

70
reference/mysqlnd/memory.xml
View File

@@ -1,25 +1,25 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqlnd.memory" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="mysqlnd.memory">
<title>Memory management</title>
<para>
<simpara>
<emphasis role="bold">Introduction</emphasis>
</para>
<para>
</simpara>
<simpara>
The MySQL Native Driver manages memory different than the MySQL Client Library.
The libraries differ in the way memory is allocated and released,
how memory is allocated in chunks while reading results from MySQL, which debug
and development options exist, and how results read from MySQL are linked to
PHP user variables.
</para>
<para>
</simpara>
<simpara>
The following notes are intended as an introduction and summary to users
interested at understanding the MySQL Native Driver at the C code level.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">Memory management functions used</emphasis>
</para>
<para>
</simpara>
<simpara>
All memory allocation and deallocation is done using the PHP memory management
functions. Therefore, the memory consumption of mysqlnd can be tracked
using PHP API calls, such as <function>memory_get_usage</function>. Because memory is
@@ -30,8 +30,8 @@
and the MySQL Client Library is difficult. The MySQL Client Library
is using the operating system memory management calls directly, hence the effects
can be observed immediately at the operating system level.
</para>
<para>
</simpara>
<simpara>
Any memory limit enforced by PHP also affects the MySQL Native Driver. This
may cause out of memory errors when fetching large result sets that exceed
the size of the remaining memory made available by PHP. Because the MySQL
@@ -41,30 +41,30 @@
beyond the PHP memory limit. But also PHP scripts may be able to process larger
result sets as parts of the memory allocated to hold the result sets are beyond
the control of the PHP engine.
</para>
<para>
</simpara>
<simpara>
PHP memory management functions are invoked by the MySQL Native Driver through
a lightweight wrapper. Among others, the wrapper makes debugging easier.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">Handling of result sets</emphasis>
</para>
<para>
</simpara>
<simpara>
The various MySQL Server and the various client APIs differentiate
between <link linkend="mysqli.quickstart.statements">buffered and unbuffered</link>
result sets. Unbuffered result sets are transferred row-by-row from MySQL to the client
as the client iterates over the results. Buffered results are fetched
in their entirety by the client library before passing them on to the client.
</para>
<para>
</simpara>
<simpara>
The MySQL Native Driver is using PHP Streams for the network communication
with the MySQL Server. Results sent by MySQL are fetched from the PHP Streams
network buffers into the result buffer of mysqlnd. The result buffer is
made of zvals. In a second step the results are made available to the PHP script.
This final transfer from the result buffer into PHP variables impacts the memory
consumption and is mostly noticeable when using buffered result sets.
</para>
<para>
</simpara>
<simpara>
By default the MySQL Native Driver tries to avoid holding
buffered results twice in memory. Results are kept only once in the internal
result buffers and their zvals. When results are fetched into PHP variables
@@ -78,8 +78,8 @@
management list and the use of standard zval reference counters.
Copy-on-write must also be done if the user reads a result set into PHP variables and
frees a result set before the variables are unset.
</para>
<para>
</simpara>
<simpara>
Generally speaking, this pattern works well for scripts that read a
result set once and do not modify variables holding results. Its major drawback
is the memory overhead caused by the additional reference management which
@@ -92,8 +92,8 @@
a script does release result sets explicitly or the driver does implicit
releases and thus memory is used for a time longer than necessary. Statistics
also help to see how many copy-on-write operations happened.
</para>
<para>
</simpara>
<simpara>
A PHP script reading many small rows of a buffered result set using a code snippet
equal or equivalent to <literal>while ($row = $res-&gt;fetch_assoc()) { ... }</literal>
may optimize memory consumption by requesting copies instead of references.
@@ -103,30 +103,30 @@
optimizing peak memory usage may help improving the overall system performance
although for an individual script the copy approach may be slower due to
additional allocations and memory copy operations.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">Monitoring and debugging</emphasis>
</para>
<para>
</simpara>
<simpara>
There are multiple ways of tracking the memory usage of the MySQL Native Driver.
If the goal is to get a quick high level overview or to verify the memory efficiency
of PHP scripts, then check the <link linkend="mysqlnd.stats">statistics</link>
collected by the library. The statistics allow you, for example, to catch
SQL statements which generate more results than are processed by a PHP script.
</para>
<para>
</simpara>
<simpara>
The <link linkend="ini.mysqlnd.debug">debug</link> trace log can be configured to
record memory management calls. This helps to see when memory is allocated
or free'd. However, the size of the requested memory chunks may not be listed.
</para>
<para>
</simpara>
<simpara>
Some, recent versions of the MySQL Native Driver feature the emulation of
random out of memory situations. This feature is meant to be used by the
C developers of the library or mysqlnd <link linkend="mysqlnd.plugin">plugin</link>
authors only. Please, search the source code for corresponding PHP configuration
settings and further details. The feature is considered private and may be
modified at any time without prior notice.
</para>
</simpara>
</chapter>
<!-- Keep this comment at the end of the file

16
reference/mysqlnd/notes.xml
View File

@@ -1,17 +1,17 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqlnd.notes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="mysqlnd.notes">
<title>Notes</title>
<para>
<simpara>
This section provides a collection of miscellaneous notes on MySQL
Native Driver usage.
</para>
</simpara>
<itemizedlist>
<listitem><para>Using <literal>mysqlnd</literal> means using PHP streams
for underlying connectivity. For <literal>mysqlnd</literal>, the PHP
streams documentation (<xref linkend="book.stream"/>) should be consulted
on such details as timeout settings, not the documentation for the MySQL
Client Library.</para></listitem>
<listitem><simpara>Using <literal>mysqlnd</literal> means using PHP streams
for underlying connectivity. For <literal>mysqlnd</literal>, the PHP
streams documentation (<xref linkend="book.stream"/>) should be consulted
on such details as timeout settings, not the documentation for the MySQL
Client Library.</simpara></listitem>
</itemizedlist>
</chapter>
<!-- Keep this comment at the end of the file

92
reference/mysqlnd/overview.xml
View File

@@ -1,11 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqlnd.overview" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="mysqlnd.overview">
<title>Overview</title>
<para>
<simpara>
<emphasis role="bold">What it is not</emphasis>
</para>
<para>
</simpara>
<simpara>
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
@@ -13,23 +13,23 @@
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>
</simpara>
<simpara>
<emphasis role="bold">Why use it?</emphasis>
</para>
<para>
</simpara>
<simpara>
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 Oracle
</simpara>
<simpara>
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>
</simpara>
<simpara>
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
@@ -39,8 +39,8 @@
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>
</simpara>
<simpara>
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
@@ -51,72 +51,72 @@
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>
</simpara>
<note>
<title>Reporting memory usage</title>
<para>
<simpara>
Because MySQL Native Driver uses the PHP memory management system, its
memory usage can be tracked with <function>memory_get_usage</function>.
This is not possible with libmysqlclient because it uses the C function malloc()
instead.
</para>
</simpara>
</note>
<para>
<simpara>
<emphasis role="bold">Special features</emphasis>
</para>
<para>
</simpara>
<simpara>
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>
</simpara>
<itemizedlist>
<listitem>
<para>
<simpara>
Improved persistent connections
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
The special function <function>mysqli_fetch_all</function>
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
Performance statistics calls:
<function>mysqli_get_client_stats</function>,
<function>mysqli_get_connection_stats</function>
</para>
</simpara>
</listitem>
</itemizedlist>
<para>
<simpara>
The performance statistics facility can prove to be very useful in
identifying performance bottlenecks.
</para>
<para>
</simpara>
<simpara>
MySQL Native Driver also allows for persistent connections when used
with the <literal>mysqli</literal> extension.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">SSL Support</emphasis>
</para>
<para>
</simpara>
<simpara>
MySQL Native Driver supports SSL.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">Compressed Protocol Support</emphasis>
</para>
<para>
</simpara>
<simpara>
MySQL Native Driver supports the compressed client
server protocol. Extension <literal>ext/mysqli</literal>, if configured to use MySQL Native Driver,
can also take advantage of this feature. Note that <literal>PDO_MYSQL</literal>
server protocol. Extension <literal>ext/mysqli</literal>, if configured to use MySQL Native Driver,
can also take advantage of this feature. Note that <literal>PDO_MYSQL</literal>
does <emphasis>NOT</emphasis> support compression when used together with mysqlnd.
</para>
<para>
</simpara>
<simpara>
<emphasis role="bold">Named Pipes Support</emphasis>
</para>
<para>
</simpara>
<simpara>
Named pipes can be used to connect on Windows environments.
</para>
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:

26
reference/mysqlnd/persist.xml
View File

@@ -1,37 +1,37 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<chapter xml:id="mysqlnd.persist" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="mysqlnd.persist">
<title>Persistent Connections</title>
<para>
<simpara>
<emphasis role="bold">Using Persistent Connections</emphasis>
</para>
<para>
</simpara>
<simpara>
If <literal>mysqli</literal> is used with <literal>mysqlnd</literal>,
when a persistent connection is created it generates a
<literal>COM_CHANGE_USER</literal>
(<literal>mysql_change_user()</literal>) call on the server. This
ensures that re-authentication of the connection takes place.
</para>
<para>
</simpara>
<simpara>
As there is some overhead associated with the
<literal>COM_CHANGE_USER</literal> call, it is possible to switch this
off at compile time. Reusing a persistent connection will then
generate a <literal>COM_PING</literal> (<literal>mysql_ping</literal>)
call to simply test the connection is reusable.
</para>
<para>
</simpara>
<simpara>
Generation of <literal>COM_CHANGE_USER</literal> can be switched off
with the compile flag
<literal>MYSQLI_NO_CHANGE_USER_ON_PCONNECT</literal>. For example:
</para>
</simpara>
<programlisting>
<![CDATA[
shell# CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT" ./configure --with-mysql=/usr/local/mysql/ --with-mysqli=/usr/local/mysql/bin/mysql_config --with-pdo-mysql=/usr/local/mysql/bin/mysql_config --enable-debug && make clean && make -j6
]]>
</programlisting>
<para>
<simpara>
Or alternatively:
</para>
</simpara>
<programlisting>
<![CDATA[
shell# export CFLAGS="-DMYSQLI_NO_CHANGE_USER_ON_PCONNECT"
@@ -40,12 +40,12 @@ shell# make clean
shell# make
]]>
</programlisting>
<para>
<simpara>
Note that only <literal>mysqli</literal> on <literal>mysqlnd</literal>
uses <literal>COM_CHANGE_USER</literal>. Other extension-driver
combinations use <literal>COM_PING</literal> on initial use of a
persistent connection.
</para>
</simpara>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:

650
reference/mysqlnd/plugin.xml
View File

File diff suppressed because it is too large Load Diff

18
reference/mysqlnd/stats.xml
View File

@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter xml:id="mysqlnd.stats" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="mysqlnd.stats">
<title>Statistics</title>
<para>
@@ -1509,30 +1509,30 @@ $link->real_connect(/* ... */);
<title>Usage examples</title>
<itemizedlist>
<listitem>
<para>
<simpara>
Check if PHP sends certain commands to MySQL, for example,
check if a client sends <literal>COM_PROCESS_KILL</literal>
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
Calculate the average number of prepared statement executions
by comparing <literal>COM_EXECUTE</literal> with
<literal>COM_PREPARE</literal>
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
Check if PHP has run any non-prepared SQL statements by
checking if <literal>COM_QUERY</literal> is zero
</para>
</simpara>
</listitem>
<listitem>
<para>
<simpara>
Identify PHP scripts that run an excessive number of SQL
statements by checking <literal>COM_QUERY</literal> and
<literal>COM_EXECUTE</literal>
</para>
</simpara>
</listitem>
</itemizedlist>
</example>