sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

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

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@321010 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2011-12-14 13:29:18 +00:00
parent ccdc549169
commit 86dd66c7d9
1 changed files with 218 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

218
reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml Normal file
View file

@ -0,0 +1,218 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 317397 $ -->
<refentry xml:id="function.mysqlnd-ms-set-qos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_ms_set_qos</refname>
<refpurpose>Sets the quality of service needed from the cluster</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_ms_set_qos</methodname>
<methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
<methodparam><type>int</type><parameter>service_level</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>service_level_option</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>option_value</parameter></methodparam>
</methodsynopsis>
<para>
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.
</para>
<para>
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
<function>mysqlnd_ms_set_qos</function>.
</para>
<para>
Similar results can be achieved with PECL mysqlnd_ms &lt; 1.2.0, if using
SQL hints to force the use of a certain type of node or using the
<literal>master_on_write</literal> 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 <literal>master_on_write</literal>, which would continue using the master
after the first write.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
A PECL/mysqlnd_ms connection handle to a MySQL server of the type
<literal>PDO_MySQL</literal>, <literal>mysqli</literal> or
<literal>mysql</literal> 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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>service_level</parameter></term>
<listitem>
<para>
The requested service level: <constant>MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL</constant>,
<constant>MYSQLND_MS_QOS_CONSISTENCY_SESSION</constant> or
<constant>MYSQLND_MS_QOS_CONSISTENCY_STRONG</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>service_level_option</parameter></term>
<listitem>
<para>
An option to parameterize the requested service level.
The option can either be <constant>MYSQLND_MS_QOS_OPTION_GTID</constant>
or <constant>MYSQLND_MS_QOS_OPTION_AGE</constant>.
</para>
<para>
The option <constant>MYSQLND_MS_QOS_OPTION_GTID</constant> can be used
to refine the service level <constant>MYSQLND_MS_QOS_CONSISTENCY_SESSION</constant>.
It must be combined with a fourth function parameter, the
<literal>option_value</literal>. The <literal>option_value</literal>
shall be a global transaction ID obtained from
<function>mysqlnd_ms_get_last_gtid</function>. 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
<literal>option_value</literal>. Please note, searching appropriate slaves
is an expensive and slow operation. Use the feature sparsely, if the
master cannot handle the read load alone.
</para>
<para>
The option <constant>MYSQLND_MS_QOS_OPTION_AGE</constant> can be used
together with the <constant>MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL</constant>
service level to filter out asynchronous slaves that lag more seconds behind
the master than <literal>option_value</literal>. If set, the plugin
will consider only slaves for reading for
which <literal>SHOW SLAVE STATUS</literal> reports
<literal>Slave_IO_Running=Yes</literal>,
<literal>Slave_SQL_Running=Yes</literal> and
<literal>Seconds_Behind_Master &lt;option_value</literal>. 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 <literal>SHOW SLAVE STATUS</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>option_value</parameter></term>
<listitem>
<para>
Parameter value for the service level option. See also <literal>service_level_option</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns <literal>TRUE</literal> if the connections service level
has been switched to the requested. Otherwise, returns <literal>FALSE</literal>
</para>
</refsect1>
<refsect1>
&reftitle.notes;
<note>
<para>
<function>mysqlnd_ms_set_qos</function> requires
PHP &gt;= 5.4.0 and PECL mysqlnd_ms &gt;= 1.2.0. Internally, it is using
a <literal>mysqlnd</literal> library C functionality not available with PHP 5.3.
</para>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysqlnd_ms_set_qos</function> example</title>
<programlisting role="php">
<![CDATA[
<?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));
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<function>mysqlnd_ms_get_last_gtid</function>
</member>
<member>
<link linkend="mysqlnd-ms.filter">Filter concept</link>
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->