From 4511dd704dc4452967c605bcd93744ce70762ef2 Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Wed, 14 Dec 2011 17:11:20 +0000 Subject: [PATCH] Assorted updates and some more additional notes in the service level concepts section. Service level concepts should get more hints on SHOW SLAVE STATUS, maybe. We have them elsewhere already. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321019 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/concepts.xml | 60 +++++++++++++++++++++++++++++ reference/mysqlnd_ms/quickstart.xml | 28 ++++++++------ 2 files changed, 76 insertions(+), 12 deletions(-) diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 9b5bcd1857..e8d1f19d0f 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -987,6 +987,16 @@ version = 5.6.2-m5-log + + Depending how a cluster is used it may be possible to achieve higher service + levels than the default one. For example, a read from an asynchronous + MySQL replication slave is eventual consistent. Thus, one may say the default + consistency level of a MySQL replication cluster is eventual consistency. + However, if the master only is used by a client for reading and writing during a + session, session consistency (read your writes) is given. PECL mysqlnd 1.2.0 + abstracts the details of choosing an appropriate node for any of the above + service levels from the user. + Service levels can be set through the qualify-of-service filter in the plugins configuration file @@ -1039,6 +1049,56 @@ version = 5.6.2-m5-log The latter requires the use of client-side global transaction id injection. + + Advantages of the new approach + + + The new approach supersedes the use of SQL hints and the configuration option + master_on_write in some respects. If an application + running on top of an asynchonous MySQL replication cluster cannot accept stale + data for certain reads, it is easier to tell the plugin to choose appropriate + nodes than prefixing all read statements in question with the SQL hint + to enforce the use of the master. Furthermore, the plugin may be able to + use selected slaves for reading. + + + The master_on_write configuration option makes the plugin + use the master after the first write (session consistency, read your writes). + In some cases, session consistency may not be needed for the rest of the session + but only for some, few read operations. Thus, master_on_write + may result in more read load on the master than necessary. In those cases it + is better to request a higher than default service level only for those reads + that actually need it. Once the reads are done, the application can return to + default service level. Switching between service levels is only possible + using mysqlnd_ms_set_qos. + + + Performance considerations + + + A MySQL replication cluster cannot tell clients which slaves are capable + of delivering which level of service. Thus, in some cases, + clients need to query the slaves to check their status. + PECL mysqlnd_ms transparently runs the necessary SQL in the + background. However, this is an expensive and slow operation. SQL statements + are run if eventual consistency is combined with an age (slave lag) limit and + if session consistency is combined with a global transaction ID. + + + If no parameters and options are set, no SQL is needed. In that case, + the plugin consider all nodes of the type shown below. + + + eventual consistency, no further options set: all masters, all slaves + + + session consistency, no further options set: all masters + + + strong consistency (no options allowed): all masters + + +
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index 5c6e21b2a3..9242781b27 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -740,7 +740,7 @@ $mysqli->close(); - Outlook: transaction aware + Transaction aware First, create a counter table on your master server and insert a record into it. The plugin does not assist creating the table. - Database administrators must make sure it exists. Depending on the error + Database administrators must make sure it exists. Depending on the error reporting mode, the plugin will silently ignore the lack of the table or bail out. @@ -1144,7 +1144,7 @@ INSERT INTO `trx`(`trx_id`) VALUES (1); section. Make sure the table name used for the UPDATE statement is fully qualified. In the example, test.trx is used to refer to table trx - in the schema test. Use the table that was created in + in the schema (database) test. Use the table that was created in the previous step. It is important to set the fully qualified table name because the connection on which the injection is done may use a different default database. Make sure the user that opens the connection @@ -1229,8 +1229,8 @@ array(1) { The example runs three statements in auto commit mode on the master, causing three transactions on the master. For every such statement, the plugin will inject the configured UPDATE transparently before executing - the users SQL statement. After the example script has finished the global - transaciton ID counter on the master has been incremented by three. + the users SQL statement. When the script ends the global + transaction ID counter on the master has been incremented by three. The fourth SQL statement executed in the example, a SELECT, @@ -1311,13 +1311,17 @@ GTID after transaction 8 - Applications can ask mysqlnd_ms for a global transaction ID which - belongs to the last write transactions. The function mysqlnd_ms_get_last_gtid() - may be called after the GTID has been incremented. The - function returns the GTID obtained when executing the SQL statement from + Applications can ask PECL mysqlnd_ms for a global transaction ID which + belongs to the last write operation performed by the application. + The function mysqlnd_ms_get_last_gtid returns the + GTID obtained when executing the SQL statement from the fetch_last_gtid entry of the global_transaction_id_injection section from - the plugins configuration file. Applications are advices not to run the SQL + the plugins configuration file. The function may be called + after the GTID has been incremented. + + + Applications are adviced not to run the SQL statement themselves as this bares the risk of accidently causing an implicit GTID increment. Also, if the function is used, it is easy to migrate an application from one SQL statement for fetching a transaction ID to another, @@ -1398,7 +1402,7 @@ var_dump($res->fetch_assoc()); - A GTID returned from mysqlnd_ms_get_last_gtid() + A GTID returned from mysqlnd_ms_get_last_gtid can be used as an option for the session consistency service level. Session consistency delivers read your writes. Session consistency can be requested by calling @@ -1408,7 +1412,7 @@ var_dump($res->fetch_assoc()); the previous INSERT already. - PECL/mysqlnd_ms will transparently check every configured slave if + PECL mysqlnd_ms will transparently check every configured slave if it has replicated the INSERT by checking the slaves GTID table. The check is done running the SQL set with the check_for_gtid option from the