From 7f83672e7fed7c00fb3803364e9a2ba948c97b1b Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Thu, 28 Jun 2012 09:51:48 +0000 Subject: [PATCH] Additions for 1.4 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@326364 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/changes.xml | 11 +++- reference/mysqlnd_ms/concepts.xml | 93 +++++++++++++++++++++++-------- reference/mysqlnd_ms/setup.xml | 31 +++++++++++ 3 files changed, 110 insertions(+), 25 deletions(-) diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index a40fbb82e8..bc4ca3b564 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -81,8 +81,15 @@ only master stategy existed to failover to a master if a slave connection fails. loop_before_master is similar but tries all other slaves before attempting to connect to the master - if a slave connection fails. The number of attempts can be limited using - the max_retries option. + if a slave connection fails. + + + The number of attempts can be limited using the max_retries option. + Failed hosts can be remembered and skipped in load balancing for the rest of + the web request. max_retries and + remember_failed are considered experimental although + decent stability is given. Syntax and semantics may change in the future + without prior notice. diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 66c3c178b6..1df5a19132 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -392,30 +392,34 @@ unit of work consists of one or more SQL statements. - By default the plugin is not aware of SQL transactions. The plugin may - switch connections for load balancing at any point in time. Connection - switches may happen in the middle of a transaction. This is against the - nature of an SQL transaction. By default, the plugin is not transaction safe. + By default the plugin is not aware of SQL transactions. The plugin may + switch connections for load balancing at any point in time. Connection + switches may happen in the middle of a transaction. This is against the + nature of an SQL transaction. By default, the plugin is not transaction safe. - At the time of writing, applications using SQL transactions together with - the plugin must use SQL hints - to disable connection switches in the middle of a SQL transaction. See also - the examples section. + Any kind of MySQL load balancer must be hinted about the begin and end of a + transaction. Hinting can either be done implicitly by monitoring API calls + or using SQL hints. Both options are supported by the plugin, depending on + your PHP version. API monitoring requires PHP 5.4.0 or newer. The plugin, + like any other MySQL load balancer, cannot detect transaction boundaries based + on the MySQL Client Server Protocol. Thus, entirely transparent transaction + aware load balancing is not possible. The least intrusive option is API + monitoring, which requires little to no application changes, depending + on your application. + + + Please, find examples of using SQL hints or the API monitoring in the + examples section. The + details behind the API monitoring, which makes the plugin transaction + aware, are described below. + + + Beginning with PHP 5.4.0, the mysqlnd + library allows this plugin to subclass the library C API call + set_autocommit(), to detect the status of + autocommit mode. - - - Added features as of PHP 5.4.0 - - The mysqlnd library allows this plugin to - subclass the library C API call set_autocommit(), to - detect the status of autocommit mode. - - - Added support for - trx_stickiness=master - - The PHP MySQL extensions either issue a query (such as SET AUTOCOMMIT=0|1), or use the mysqlnd library call set_autcommit() to control @@ -434,6 +438,12 @@ balancing if autocommit becomes disabled, and directs all statements to the master until autocommit gets enabled. + + An application that does not want to set SQL hints for transactions but wants + to use the transparent API monitoring to avoid application changes must make + sure that the autocommit settings is changed exclusively through the listed + API calls. +
@@ -679,6 +689,17 @@ version = 5.6.2-m5-log using the failover configuration directive. + + Automatic and silent failover can be enabled through the + failover + configuration directive. Automatic failover can either be configured to + try exactly one master after a slave failure or, alternatively, loop + over slaves and masters before returning an error to the user. The number + of connection attempts can be limited and failed hosts can be excluded + from future load balancing attempts. Limiting the number of retries and + remembering failed hosts are considered experimental features, albeit being + resonable stable. Syntax and semantics may change in future versions. + A basic manual failover example is provided within the error handling section. @@ -686,10 +707,10 @@ version = 5.6.2-m5-log Please note, if using a primary copy cluster, such as MySQL Replication, it is difficult to do connection failover in case of a master failure. - At any there there is only one master in the cluster for a given dataset. + At any time there is only one master in the cluster for a given dataset. The master is a single point of failure. If the master fails, clients have no target to fail over write requests. In case of a master outage the database - administrator must take care of the situation and eventually update the client + administrator must take care of the situation and update the client configurations, if need be.
@@ -748,6 +769,14 @@ version = 5.6.2-m5-log and user filters. + + Servers can be prioritized assigning a weight. A server that has been given + a weight of two will get twice as many requests as a server that has been + given the default weight of one. Prioritization can be handy in heterogenous + environments. For example, you may want to assign more requests to + a powerful machine than to a less powerful. Or, you may have configured + servers that are close or far from the client, thus expose different latencies. +
@@ -1160,6 +1189,24 @@ version = 5.6.2-m5-log + + Throttling + + + The quality of service filter can be combied with + Global transaction IDs to + throttle clients. Throttling does reduce the write load on the master + by slowing down clients. If session consistency is requested and + global transactions idenentifier are used to check the status of + a slave, the check can be done in two ways. By default a slave + is checked and skipped immediately if it does not match + the criteria for session consistency. Alternatively, the + plugin can wait for a slave to catch up to the master until + session consistency is possible. To enable the throttling, + you have to set + wait_for_gtid_timeout + configuration option. +
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index 20d3675fc2..f95fc58012 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -644,6 +644,37 @@ $mysqli = new mysqli("localhost", "username", "password", "database"); Since 1.2.0. + + + wait_for_gtid_timeout + + + + Instructs the plugin to wait up to wait_for_gtid_timeout + seconds for a slave to catch up when searching for slaves that can + deliver session consistency. The setting limits the time spend for + polling the slave status. If polling the status takes very long, the total + clock time spend waiting may exceed wait_for_gtid_timeout. + The plugin calls sleep(1) to sleep one second between + each two polls. + + + The setting can be used both with the plugins client-side emulation + and the server-side global transaction identifier feature of MySQL 5.6. + + + Waiting for a slave to replicate a certain GTID needed for session + consistency also means throttling the client. By throttling the + client the write load on the master is reduced indirectly. A + primary copy based replication system, such as MySQL Replication, + is given more time to reach a consistent state. This can be desired, + for example, to increase the number of data copies for + high availability considerations or to prevent the master from being + overloaded. + + + Since 1.4.0. +