From 86dd66c7d91f27e6882211f4f90c949cb7102f77 Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Wed, 14 Dec 2011 13:29:18 +0000 Subject: [PATCH] Minimum documentation for mysqlnd_ms_set_qos(). We should have more examples. We should also tell the user which warnings can be thrown to ensure web searches for the warning messages end up in the manual git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321010 c90b9560-bf6c-de11-be94-00142212c4b1 --- .../functions/mysqlnd-ms-set-qos.xml | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml new file mode 100644 index 0000000000..de3b17531c --- /dev/null +++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml @@ -0,0 +1,218 @@ + + + + + + mysqlnd_ms_set_qos + Sets the quality of service needed from the cluster + + + + &reftitle.description; + + bool + mysqlnd_ms_set_qos + mixedconnection + intservice_level + intservice_level_option + mixedoption_value + + + Sets the quality of service needed from the cluster. A database cluster delivers + a certain quality of service to the user depending on its architecture. A major + aspect of the quality of service is the consistency level the cluster can offer. + An asynchronous MySQL replication cluster defaults to eventual consistency for + slave reads: a slave may serve stale data, current data or it may have not the + requested data at all, because it is not synchronous to the master. In a + MySQL replication cluster only master accesses can give strong consistency, which + promises that all clients see each others changes. + + + PECL/mysqlnd_ms hides the complexity of choosing appropriate nodes to achieve + a certain level of service from the cluster. The + quality of service filter implements the necessary logic. The filter can either + be configured in the plugins configuration file or at run time using + mysqlnd_ms_set_qos. + + + Similar results can be achieved with PECL mysqlnd_ms < 1.2.0, if using + SQL hints to force the use of a certain type of node or using the + master_on_write plugin configuration option. The first + requires more code and causes more work on the application side. + The latter is coarser than using the quality of service filter. + Settings made through the function call can be reversed, as shown in the example + below. The example temporarily switches to a higher service level + (session consistency, read your writes) and returns + back to the clusters default after it has performed all operations that require the + better service. This way, read load on the master can be minimized compared to + using master_on_write, which would continue using the master + after the first write. + + + + + &reftitle.parameters; + + + connection + + + A PECL/mysqlnd_ms connection handle to a MySQL server of the type + PDO_MySQL, mysqli or + mysql for which a service level is to be set. + The connection handle is obtained when opening a connection with + a host name that matches a mysqlnd_ms configuration file + entry using any of the three extensions. + + + + + service_level + + + The requested service level: MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL, + MYSQLND_MS_QOS_CONSISTENCY_SESSION or + MYSQLND_MS_QOS_CONSISTENCY_STRONG. + + + + + service_level_option + + + An option to parameterize the requested service level. + The option can either be MYSQLND_MS_QOS_OPTION_GTID + or MYSQLND_MS_QOS_OPTION_AGE. + + + The option MYSQLND_MS_QOS_OPTION_GTID can be used + to refine the service level MYSQLND_MS_QOS_CONSISTENCY_SESSION. + It must be combined with a fourth function parameter, the + option_value. The option_value + shall be a global transaction ID obtained from + mysqlnd_ms_get_last_gtid. If set, the + plugin considers both master servers and asynchronous slaves for session + consistency (read your writes). Otherwise, only masters are + used to achive session consistency. A slave is considered up-to-date and taken + into account if it has already replicated the global transaction ID from + option_value. Please note, searching appropriate slaves + is an expensive and slow operation. Use the feature sparsely, if the + master cannot handle the read load alone. + + + The option MYSQLND_MS_QOS_OPTION_AGE can be used + together with the MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL + service level to filter out asynchronous slaves that lag more seconds behind + the master than option_value. If set, the plugin + will consider only slaves for reading for + which SHOW SLAVE STATUS reports + Slave_IO_Running=Yes, + Slave_SQL_Running=Yes and + Seconds_Behind_Master <option_value. Please note, + searching appropriate slaves is an expensive and slow operation. + Use the feature sparsely in version 1.2.0. Future versions may improve the + algorithm used to identify candidates. Please, see the MySQL reference + manual about the precision, accuracy and limitations of the MySQL administrative + command SHOW SLAVE STATUS. + + + + + option_value + + + Parameter value for the service level option. See also service_level_option. + + + + + + + + &reftitle.returnvalues; + + Returns TRUE if the connections service level + has been switched to the requested. Otherwise, returns FALSE + + + + + &reftitle.notes; + + + mysqlnd_ms_set_qos requires + PHP >= 5.4.0 and PECL mysqlnd_ms >= 1.2.0. Internally, it is using + a mysqlnd library C functionality not available with PHP 5.3. + + + + + + &reftitle.examples; + + + <function>mysqlnd_ms_set_qos</function> example + +errno, $mysqli->error)); + +/* Will use master and return fresh data, client can see his last write */ +if (!$res = $mysqli->query("SELECT item, price FROM orders WHERE order_id = 1")) + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); + +/* Back to default: use of all slaves and masters permitted, stale data can happen */ +if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL)) + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); +?> +]]> + + + + + + + &reftitle.seealso; + + + + mysqlnd_ms_get_last_gtid + + + Filter concept + + + + + + + +