sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 01:18:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation for server-side global transaction ID support available since yesterday

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@323945 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2012-03-06 11:46:10 +00:00
parent 63849f121a
commit d5ac5b0152
5 changed files with 240 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
reference/mysqlnd_ms/book.xml
View file

@ -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>

5
reference/mysqlnd_ms/changes.xml
View file

@ -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>

67
reference/mysqlnd_ms/concepts.xml
View file

@ -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">

81
reference/mysqlnd_ms/quickstart.xml
View file

@ -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

88
reference/mysqlnd_ms/setup.xml
View 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>