From 3bb8c62d1a64baa464978c2cb1c2def6d0d7adb4 Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Wed, 14 Dec 2011 16:14:59 +0000 Subject: [PATCH] Stop calling trx_stickiness experimental. It is tested, we have heard no complains. Assorted other minor changes git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321015 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/quickstart.xml | 62 +++++++++++++++++++---------- reference/mysqlnd_ms/setup.xml | 7 +--- 2 files changed, 43 insertions(+), 26 deletions(-) diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index db6031cd11..5c6e21b2a3 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -15,6 +15,12 @@ environments we urge you to read additionally the background information from the reference sections. + + The focus is on using PECL mysqlnd_ms for work with an asynchronous MySQL cluster, + namelys MySQL replication. Generally speaking an asynchronous cluster is more + difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster + will find more information than needed. + The documentation has been updated to show the syntax used as of version @@ -526,7 +532,13 @@ $mysqli->close(); SQL hints can also be used to run SELECT statements on the MySQL master server. This may be desired if the MySQL slave servers - are typically behind the master, but you need current data from the database. + are typically behind the master, but you need current data from the cluster. + + + In version 1.2.0 the concept of a service level has been introduced to address + cases when current data is required. Using a service level requires less attention + and removes the need of using SQL hints for this use case. Please, find more + information below in the service level and consistency section. @@ -598,7 +610,7 @@ $mysqli->close();
Transactions - The current version of the plugin is not transaction safe, + The current version of the plugin is not transaction safe by default, because it is not transaction aware. SQL transactions are units of work to be run on a single server. The plugin does not know when the unit of work starts and when it ends. @@ -606,7 +618,9 @@ $mysqli->close(); of a transaction. - You must use SQL hints to work around this limitation. + You can either use SQL hints to work around this limitation. Alternatively, + you can activate transaction API call monitoring. In the latter case you + must use API calls only to control transactins, see below. @@ -689,7 +703,7 @@ $mysqli->close(); If using PHP 5.4.0 or newer, API calls that enable autocommit mode, - and when setting the experimental plugin configuration option + and when setting the plugin configuration option trx_stickiness=master, the plugin can automatically disable load balancing and connection switches for SQL transactions. In this configuration, the plugin stops load balancing @@ -700,7 +714,7 @@ $mysqli->close(); - Experimental trx_stickiness setting + Transaction aware load balancing: trx_stickiness setting close(); - Experimental PHP 5.4.0+ feature + Version requirement The plugin configuration option trx_stickiness=master - is an experimental feature, and requires PHP 5.4.0 or newer. + requires PHP 5.4.0 or newer.
@@ -782,7 +796,7 @@ $mysqli->close(); Version requirement - Service levels have been introduced in mysqlnd_ms version 1.2.0-alpha. + Service levels have been introduced in PECL mysqlnd_ms version 1.2.0-alpha. mysqlnd_ms_set_qos is available with PHP 5.4.0 or newer. @@ -792,7 +806,7 @@ $mysqli->close(); data consistency levels to their users. An asynchronous MySQL replication cluster offers eventual consistency by default. A read executed on an asynchronous slave may return current, stale or no data at all, depending on whether the slave - has replayed all master changes or not. + has replayed all changesets from the master or not. Applications using an MySQL replication cluster need to be designed to work @@ -801,8 +815,8 @@ $mysqli->close(); allowed to achieve the required quality of service from the cluster. - As of PECL/mysqlnd_ms 1.2.0 the plugin is capable of selecting automatically - MySQL replication nodes that can deliver session consistency or + As of PECL mysqlnd_ms 1.2.0 the plugin is capable of selecting + MySQL replication nodes automatically that deliver session consistency or strong consistency. Session consistency means that one client can read its writes. Other clients may or may not see the clients' write. Strong consistency means that all clients will see all writes from the client. @@ -881,11 +895,17 @@ if (!$res = $mysqli->query("SELECT item, price FROM specials")) Read-write splitting logic has been adapted to fulfill the service level. - After the application has read its changes from the orders table - it returns to the default service level, which is eventual consistency. Eventual - consistency puts no restrictions on choosing a node for statement execution. - Thus, the SELECT statement on the specials - table is executed on a slave. + After the application has read its changes from the orders table + it returns to the default service level, which is eventual consistency. Eventual + consistency puts no restrictions on choosing a node for statement execution. + Thus, the SELECT statement on the specials + table is executed on a slave. + + + The new functionality supersedes the use of SQL hints and the + master_on_write configuration option. In many cases + mysqlnd_ms_set_qos is easier to use, more powerful + improves portability. @@ -970,7 +990,7 @@ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) Checking SHOW SLAVE STATUS for all slaves adds overhead to the application. It is an expensive and slow background operation. Try to minimize the use of it. Unfortunately, a MySQL replication cluster - does not give clients the possibility to request a list of candidates + does not give clients the possibility to request a list of candidates from a central instance. Thus, a more efficient way of checking the slaves lag is not available. @@ -981,10 +1001,10 @@ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) To prevent mysqlnd_ms from emitting a warning if no slaves can be found - that lag no more than four seconds behind the master, it is necessary to - enable master fail over in the plugins configuration file. If no slaves - can be found and fail over is turned on, the plugin picks a master for - executing the statement. + that lag no more than the defined number of seconds behind the master, + it is necessary to enable master fail over in the plugins configuration file. + If no slaves can be found and fail over is turned on, the plugin + picks a master for executing the statement. If no slave can be found and fail over is turned off, the plugin emits diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index bb0dc1572e..c7f71de676 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -47,7 +47,7 @@ Using and parsing JSON is efficient, and using JSON - makes it easier to express hierarchical data structures than the standard + makes it easier to express hierarchical data structures than the standard php.ini format. @@ -198,7 +198,7 @@ $mysqli = new mysqli("localhost", "username", "password", "database"); Each configuration section contains, at a minimum, a list of master servers and a list of slave servers. The master list is configured with the keyword - master, while the slave list is configured with the + master, while the slave list is configured with the slave keyword. Failing to provide a slave list will result in a fatal E_WRROR level error, although a slave list may be empty. @@ -1271,9 +1271,6 @@ User has connected to 'myapp'... Transaction stickiness policy. Supported policies: disabled (default), master. - - Experimental feature. - The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, the plugin will emit a warning like