mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Documentation for server-side global transaction ID support available since yesterday
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@323945 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
parent
63849f121a
commit
d5ac5b0152
5 changed files with 240 additions and 12 deletions
|
@ -166,6 +166,11 @@
|
|||
with asynchronous clusters, such as MySQL Replication.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Support for built-in global transaction identifier feature of MySQL 5.6.4-m8 or newer.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Supports using transaction ids to identify up-to-date asynchronous slaves
|
||||
|
@ -189,6 +194,12 @@
|
|||
be searched automatically.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Eventual consistent MySQL Replication slave accesses can be replaced
|
||||
with fast local cache accesses transparently to reduce server load.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
|
@ -78,6 +78,11 @@
|
|||
</itemizedlist>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
Support for built-in global transaction identifier feature of MySQL 5.6.4-m8 or newer.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
|
|
@ -1134,7 +1134,16 @@ version = 5.6.2-m5-log
|
|||
Transaction boundaries are detected by monitoring API calls. This is possible
|
||||
as of PHP 5.4.0. Please, see also <link linkend="mysqlnd-ms.transaction">Transaction handling</link>.
|
||||
</para>
|
||||
<para>
|
||||
As of MySQL 5.6.4-m8 the MySQL server features built-in global transaction identifiers.
|
||||
The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or
|
||||
later. Neither are client-side transaction boundary monitoring nor any setup
|
||||
activities required if using the server feature.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
<emphasis role="bold">Idea and client-side emulation</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
PECL/mysqlnd_ms can do client-side transparent global transaction ID injection.
|
||||
In its most basic form, a global transaction identifier is a counter which is
|
||||
|
@ -1182,6 +1191,11 @@ version = 5.6.2-m5-log
|
|||
Client-side global transaction ID injection has shortcomings. The potential
|
||||
issues are not specific to PECL/mysqlnd_ms but are rather of general nature.
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<simpara>
|
||||
Global transaction ID tables must be deployed on all masters and replicas.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
The GTID can have holes. Only PHP clients using the plugin will
|
||||
|
@ -1202,17 +1216,48 @@ version = 5.6.2-m5-log
|
|||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<note>
|
||||
<title>Server-side global transaction ID support</title>
|
||||
<para>
|
||||
The plugin is prepared to support MySQL servers which implement global
|
||||
transaction ID support and which maintain a global transaction ID themselves.
|
||||
Client-side injection would not be necessary with such servers. However,
|
||||
without any server supporting it yet and, in heterogenous environments with
|
||||
old MySQL servers, client-side injection is a valuable, although not perfect,
|
||||
option.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
<emphasis role="bold">Using server-side global transaction identifier</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Starting with PECL/mysqlnd_ms 1.3.0-alpha the MySQL 5.6.4-m8 or newer built-in global
|
||||
transaction identifier feature is supported. Use of the server feature lifts
|
||||
all of the above listed limitations. Please, see the MySQL Reference Manual
|
||||
for limitations and preconditions for using server built-in global transaction
|
||||
identifiers.
|
||||
</para>
|
||||
<para>
|
||||
Whether to use the client-side emulation or the server built-in
|
||||
functionality is a question not directly related to the plugin, thus it is not
|
||||
discussed in depth. There are no plans to remove the client-side emulation and
|
||||
you can continue to use it, if the server-side solution is no option. This may
|
||||
be the case in heterogenous environments with old MySQL server or, if any of the
|
||||
server-side solution limitations is not acceptable.
|
||||
</para>
|
||||
<para>
|
||||
From an applications perspective there is hardly a difference in using one or the
|
||||
other approach. The following properties differ.
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<simpara>
|
||||
Client-side emulation, as shown in the manual, is using an easy to compare sequence number
|
||||
for global transactions. Multi-master is not handled to keep the manual examples easy.
|
||||
</simpara>
|
||||
<simpara>
|
||||
Server-side built-in feature is using a combination of a server identifier
|
||||
and a sequence number as a global transaction identifier. Comparison cannot
|
||||
use numeric algebra. Instead a SQL function must be used. Please,
|
||||
see the MySQL Reference Manual for details.
|
||||
</simpara>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<simpara>
|
||||
Plugin global transaction ID statistics are only available with client-side
|
||||
emulation because they monitor the emulation.
|
||||
</simpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="mysqlnd-ms.supportedclusters">
|
||||
|
|
|
@ -1098,11 +1098,31 @@ PHP Warning: mysqli::query(): (mysqlnd_ms) No connection selected by the last f
|
|||
<note>
|
||||
<title>Version requirement</title>
|
||||
<para>
|
||||
Global transaction ID injection has been introduced in mysqlnd_ms version 1.2.0-alpha.
|
||||
A client-side global transaction ID injection has been introduced in mysqlnd_ms version 1.2.0-alpha.
|
||||
The feature is not required for synchronous clusters, such as MySQL Cluster.
|
||||
Use it with asynchronous clusters such as classical MySQL replication.
|
||||
</para>
|
||||
<para>
|
||||
As of MySQL 5.6.4-m8 the MySQL server features built-in global transaction identifiers.
|
||||
The MySQL built-in global transaction ID feature is supported by PECL/mysqlnd_ms 1.3.0-alpha or
|
||||
later.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
PECL/mysqlnd_ms can either use its own global transaction ID emulation or the
|
||||
global transaction ID feature built-in to MySQL 5.6.4-m8 or later. From a developer
|
||||
perspective the client-side and server-side approach offer the same features with
|
||||
regards to service levels provided by PECL/mysqlnd_ms. Their differences
|
||||
are discussed in the <link linkend="mysqlnd-ms.gtid">concepts section</link>.
|
||||
</para>
|
||||
<para>
|
||||
The quickstart first demonstrates the use of the client-side global transaction ID emulation
|
||||
built-in to PECL/mysqlnd_ms before its show how to use the server-side counterpart.
|
||||
The order ensures that the underlying idea is discussed first.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="bold">Idea and client-side emulation</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
In its most basic form a global transaction ID (GTID) is a counter in a table on the
|
||||
master. The counter is incremented whenever a transaction is comitted on the master.
|
||||
|
@ -1431,6 +1451,65 @@ var_dump($res->fetch_assoc());
|
|||
expensive procedure. Applications should try to use it sparsely and only
|
||||
if read load on the master becomes to high otherwise.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="bold">Use of the server-side global transaction ID feature</emphasis>
|
||||
</para>
|
||||
<para>
|
||||
Starting with MySQL 5.6.4-m8 the MySQL Replication system features server-side
|
||||
global transaction IDs. Transaction identifiers are automatically generated and
|
||||
maintained by the server. Users do not need to take care of maintaining them.
|
||||
There is no need to setup any tables in advance, or for setting
|
||||
<literal>on_commit</literal>. A client-side emulation is no longer needed.
|
||||
</para>
|
||||
<para>
|
||||
Clients can continue to use global transaction identifier to achieve
|
||||
session consistency when reading from MySQL Replication slaves. The algorithm
|
||||
works as described above. Different SQL statements must be configured for
|
||||
<literal>fetch_last_gtid</literal> and <literal>check_for_gtid</literal>.
|
||||
The statements are given below. Please note, MySQL 5.6.4-m8 is a development
|
||||
version. Details of the server implementation may change in the future and require
|
||||
adoption of the SQL statements shown.
|
||||
</para>
|
||||
<para>
|
||||
Using the following configuration any of the above described functionality can
|
||||
be used together with the server-side global transaction ID feature.
|
||||
<function>mysqlnd_ms_get_last_gtid</function> and <function>mysqlnd_ms_set_qos</function>
|
||||
continue to work as described above. The only difference is that the server
|
||||
does not use a simple sequence number but a string containing of a server identifier
|
||||
and a sequence number. Thus, users cannot easily derive an order from GTIDs returned
|
||||
by <function>mysqlnd_ms_get_last_gtid</function>.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
<title>Plugin config: using MySQL 5.6.4-m8 built-in GTID feature</title>
|
||||
<programlisting role="ini">
|
||||
<![CDATA[
|
||||
{
|
||||
"myapp": {
|
||||
"master": {
|
||||
"master_0": {
|
||||
"host": "localhost",
|
||||
"socket": "\/tmp\/mysql.sock"
|
||||
}
|
||||
},
|
||||
"slave": {
|
||||
"slave_0": {
|
||||
"host": "127.0.0.1",
|
||||
"port": "3306"
|
||||
}
|
||||
},
|
||||
"global_transaction_id_injection":{
|
||||
"fetch_last_gtid" : "SELECT @@GLOBAL.GTID_DONE AS trx_id FROM DUAL",
|
||||
"check_for_gtid" : "SELECT GTID_SUBSET('#GTID', @@GLOBAL.GTID_DONE) AS trx_id FROM DUAL",
|
||||
"report_error":true
|
||||
}
|
||||
}
|
||||
}
|
||||
]]>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
</chapter>
|
||||
<!-- Keep this comment at the end of the file
|
||||
|
|
|
@ -561,6 +561,94 @@ $mysqli = new mysqli("localhost", "username", "password", "database");
|
|||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.gtid">
|
||||
<term>
|
||||
<parameter>global_transaction_id_injection</parameter>
|
||||
<type>array or object</type>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Global transaction identifier configuration related to both
|
||||
the use of the server built-in global transaction ID feature and
|
||||
the client-side emulation.
|
||||
</para>
|
||||
<informaltable>
|
||||
<tgroup cols="3">
|
||||
<colspec colwidth="1*"/>
|
||||
<colspec colwidth="7*"/>
|
||||
<colspec colwidth="2*"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Keyword</entry>
|
||||
<entry>Description</entry>
|
||||
<entry>Version</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>
|
||||
<literal>fetch_last_gtid</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
<para>
|
||||
SQL statement for accessing the latest global transaction identifier.
|
||||
The SQL statement is run if the plugin needs to know the most recent
|
||||
global transaction identifier. This can be the case, for example, when checking
|
||||
MySQL Replication slave status.
|
||||
Also used with <function>mysqlnd_ms_get_last_gtid</function>.
|
||||
</para>
|
||||
</entry>
|
||||
<entry>Since 1.2.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
<literal>check_for_gtid</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
<para>
|
||||
SQL statement for checking if a replica has replicated
|
||||
all transactions up to and including ones searched for. The
|
||||
SQL statement is run when searching for replicas which can offer
|
||||
a higher level of consistency than eventual consistency.
|
||||
The statement must contain a placeholder <literal>#GTID</literal>
|
||||
which is to be replaced with the global transaction identifier searched
|
||||
for by the plugin. Please, check the
|
||||
<link linkend="mysqlnd-ms.quickstart.gtid">quickstart</link> for examples.
|
||||
</para>
|
||||
</entry>
|
||||
<entry>Since 1.2.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
<literal>report_errors</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
<para>
|
||||
Whether to emit an error of type warning if an issue occurs while
|
||||
executing any of the configured SQL statements.
|
||||
</para>
|
||||
</entry>
|
||||
<entry>Since 1.2.0.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>
|
||||
<literal>on_commit</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
<para>
|
||||
Client-side global transaction ID emulation only. SQL statement
|
||||
to run when a transaction finished to update the global transaction
|
||||
identifier sequence number on the master. Please, see the
|
||||
<link linkend="mysqlnd-ms.quickstart.gtid">quickstart</link> for examples.
|
||||
</para>
|
||||
</entry>
|
||||
<entry>Since 1.2.0.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.filters">
|
||||
<term>
|
||||
<parameter>filters</parameter>
|
||||
|
|
Loading…
Reference in a new issue