From d5ac5b0152d590e2305e4dde23d92c96268065ef Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Tue, 6 Mar 2012 11:46:10 +0000 Subject: [PATCH] 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 --- reference/mysqlnd_ms/book.xml | 11 ++++ reference/mysqlnd_ms/changes.xml | 5 ++ reference/mysqlnd_ms/concepts.xml | 67 ++++++++++++++++++---- reference/mysqlnd_ms/quickstart.xml | 81 +++++++++++++++++++++++++- reference/mysqlnd_ms/setup.xml | 88 +++++++++++++++++++++++++++++ 5 files changed, 240 insertions(+), 12 deletions(-) diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml index 1b68196e40..2fc40a979d 100755 --- a/reference/mysqlnd_ms/book.xml +++ b/reference/mysqlnd_ms/book.xml @@ -166,6 +166,11 @@ with asynchronous clusters, such as MySQL Replication. + + + Support for built-in global transaction identifier feature of MySQL 5.6.4-m8 or newer. + + Supports using transaction ids to identify up-to-date asynchronous slaves @@ -189,6 +194,12 @@ be searched automatically. + + + Eventual consistent MySQL Replication slave accesses can be replaced + with fast local cache accesses transparently to reduce server load. + + diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index 5bdd86c6ee..cb71e9ac3b 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -78,6 +78,11 @@ + + + Support for built-in global transaction identifier feature of MySQL 5.6.4-m8 or newer. + + diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 929d4670e3..918af4f6a9 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -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 Transaction handling. + + 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. + + + Idea and client-side emulation + 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. + + + Global transaction ID tables must be deployed on all masters and replicas. + + The GTID can have holes. Only PHP clients using the plugin will @@ -1202,17 +1216,48 @@ version = 5.6.2-m5-log - - Server-side global transaction ID support - - 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. - - + + Using server-side global transaction identifier + + + 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. + + + 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. + + + From an applications perspective there is hardly a difference in using one or the + other approach. The following properties differ. + + + + 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. + + + 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. + + + + + Plugin global transaction ID statistics are only available with client-side + emulation because they monitor the emulation. + + + +
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index 1162b10aa2..1a2430f00e 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -1098,11 +1098,31 @@ PHP Warning: mysqli::query(): (mysqlnd_ms) No connection selected by the last f Version requirement - 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. + + 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. + + + 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 concepts section. + + + 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. + + + Idea and client-side emulation + 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. + + Use of the server-side global transaction ID feature + + + 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 + on_commit. A client-side emulation is no longer needed. + + + 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 + fetch_last_gtid and check_for_gtid. + 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. + + + Using the following configuration any of the above described functionality can + be used together with the server-side global transaction ID feature. + mysqlnd_ms_get_last_gtid and mysqlnd_ms_set_qos + 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 mysqlnd_ms_get_last_gtid. + + + + Plugin config: using MySQL 5.6.4-m8 built-in GTID feature + + + + + +