Sets the quality of service needed from the cluster
bool mysqlnd_ms_set_qos(mixed connection,
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 runtime using
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
configuration option. The first requires more code and causes
more work on the application side. The latter is less refined
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.
Since 1.5.0 calls will fail when done in the middle of a transaction if transaction stickiness is enabled and transaction boundaries have been detected. properly.
A PECL/mysqlnd_ms connection handle to a MySQL server of the type PDO_MYSQL, mysqli or ext/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 above three MySQL driver extensions.
The requested service level:
An option to parameterize the requested service level. The
option can either be
can be used to refine the service level
It must be combined with a fourth function parameter, the
option_value shall be a global
transaction ID obtained from
If set, the plugin considers both master servers and
asynchronous slaves for session consistency (read your
writes). Otherwise, only masters are used to achieve
session consistency. A slave is considered up-to-date and
checked if it has already replicated the global
transaction ID from
Please note, searching appropriate slaves is an expensive
and slow operation. Use the feature sparsely, if the
master cannot handle the read load alone.
can be combined with the
service level, to filter out asynchronous slaves that lag
more seconds behind the master than
option_value. If set, the plugin
will only consider slaves for reading if
SLAVE STATUS reports
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.
Parameter value for the service level option. See also the
TRUE if the connections service
level has been switched to the requested. Otherwise, returns
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.
Please note, all MySQL 5.6 production versions do not provide clients with enough information to use GTIDs for enforcing session consistency. In the worst case, the plugin will choose the master only.
<?php /* Open mysqlnd_ms connection using mysqli, PDO_MySQL or mysql extension */ $mysqli = new mysqli("myapp", "username", "password", "database"); if (!$mysqli) /* Of course, your error handling is nicer... */ die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error())); /* Session consistency: read your writes */ $ret = mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_SESSION); if (!$ret) die(sprintf("[%d] %s\n", $mysqli->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)); ?>
|Service level and consistency concept|