<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Filter</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.rwsplit.html">Read-write splitting</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.qos-consistency.html">Service level and consistency</a></div>
<div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.filter" class="section">
<h2 class="title">Filter</h2>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Version requirement</strong><br />
<p class="para">
Filters exist as of mysqlnd_ms version 1.1.0-beta.
</p>
</p></blockquote>
<p class="para">
<a href="mysqlnd-ms.plugin-ini-json.html" class="link">filters</a>.
PHP applications that implement a MySQL replication cluster must first identify
a group of servers in the cluster which could execute a statement before
the statement is executed by one of the candidates. In other words: a defined
list of servers must be filtered until only one server is available.
</p>
<p class="para">
The process of filtering may include using one or more filters, and filters can be
chained. And they are executed in the order they are defined in the plugins
configuration file.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Explanation: comparing filter chaining to pipes</strong><br />
<p class="para">
The concept of chained filters can be compared to using pipes to connect
command line utilities on an operating system command shell. For example,
an input stream is passed to a processor, filtered, and then transferred
to be output. Then, the output is passed as input to the next command,
which is connected to the previous using the pipe operator.
</p>
</p></blockquote>
<p class="para">
Available filters:
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Load balancing filters:
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">random</a> and
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">roundrobin</a>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Selection filter:
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">user</a>,
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">user_multi</a>,
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filters" class="link">quality_of_service</a>.
</span>
</li>
</ul>
</p>
<p class="para">
The <em>random</em> filter implements the 'random' and 'random once'
load balancing policies. The 'round robin' load balancing can be configured
through the <em>roundrobin</em> filter. Setting a 'user defined
callback' for server selection is possible with the <em>user</em>
filter. The <em>quality_of_service</em> filter finds cluster
nodes capable of delivering a certain service, for example, read-your-writes or,
not lagging more seconds behind the master than allowed.
</p>
<p class="para">
Filters can accept parameters to change their behaviour.
The <em>random</em> filter accepts an optional
<em>sticky</em> parameter. If set to true, the filter changes
load balancing from random to random once. Random picks a random server
every time a statement is to be executed. Random once picks a random
server when the first statement is to be executed and uses the same
server for the rest of the PHP request.
</p>
<p class="para">
One of the biggest strength of the filter concept is the possibility to
chain filters. This strength does not become immediately visible because
tje <em>random</em>, <em>roundrobin</em> and
<em>user</em> filters are supposed to output no more than one server.
If a filter reduces the list of candidates for running a statement to
only one server, it makes little sense to use that one server as
input for another filter for further reduction of the list of candidates.
</p>
<p class="para">
An example filter sequence that will fail:
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Statement to be executed: <em>SELECT 1 FROM DUAL</em>. Passed to all filters.
</span>
</li>
<li class="listitem">
<span class="simpara">
All configured nodes are passed as input to the first filter.
Master nodes: <em>master_0</em>.
Slave nodes:<em>slave_0</em>, <em>slave_1</em>
</span>
</li>
<li class="listitem">
<span class="simpara">
Filter: <em>random</em>, argument <em>sticky=1</em>.
Picks a random slave once to be used for the rest of the PHP request.
Output: <em>slave_0</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Output of <em>slave_0</em> and the statement to be executed
is passed as input to the next filter. Here: <em>roundrobin</em>,
server list passed to filter is: <em>slave_0</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Filter: <em>roundrobin</em>. Server list consists of
one server only, round robin will always return the same server.
</span>
</li>
</ul>
If trying to use such a filter sequence,
the plugin may emit a warning like <em>(mysqlnd_ms) Error while creating
filter '%s' . Non-multi filter '%s' already created. Stopping in %s on
line %d</em>. Furthermore, an appropriate error on the connection handle
may be set.
</p>
<p class="para">
A second type of filter exists: multi filter. A multi filter emits zero, one or multiple
servers after processing. The <em>quality_of_service</em> filter
is an example. If the service quality requested sets an upper limit for the slave
lag and more than one slave is lagging behind less than the allowed number of seconds,
the filter returns more than one cluster node. A multi filter must be followed by other
to further reduce the list of candidates for statement execution until a candidate
is found.
</p>
<p class="para">
A filter sequence with the <em>quality_of_service</em>
multi filter followed by a load balancing filter.
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Statement to be executed: <em>SELECT sum(price) FROM orders WHERE order_id = 1</em>.
Passed to all filters.
</span>
</li>
<li class="listitem">
<span class="simpara">
All configured nodes are passed as input to the first filter.
Master nodes: <em>master_0</em>.
Slave nodes: <em>slave_0</em>, <em>slave_1</em>,
<em>slave_2</em>, <em>slave_3</em>
</span>
</li>
<li class="listitem">
<span class="simpara">
Filter: <em>quality_of_service</em>, rule set: session_consistency (read-your-writes)
Output: <em>master_0</em>
</span>
</li>
<li class="listitem">
<span class="simpara">
Output of <em>master_0</em>
and the statement to be executed
is passed as input to the next filter, which is <em>roundrobin</em>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Filter: <em>roundrobin</em>. Server list consists of
one server. Round robin selects <em>master_0</em>.
</span>
</li>
</ul>
</p>
<p class="para">
A filter sequence must not end with a multi filter. If trying to use
a filter sequence which ends with a multi filter the plugin may emit a
warning like <em>(mysqlnd_ms) Error in configuration. Last filter is multi
filter. Needs to be non-multi one. Stopping in %s on line %d</em>.
Furthermore, an appropriate error on the connection handle
may be set.
</p>
<p class="para">
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Speculation towards the future: MySQL replication filtering</strong><br />
<p class="para">
In future versions, there may be additional multi filters.
For example, there may be a <em>table</em>
filter to support MySQL replication filtering. This would allow
you to define rules for which database or table is to be replicated to which
node of a replication cluster. Assume your replication cluster
consists of four slaves (<em>slave_0</em>, <em>slave_1</em>,
<em>slave_2</em>, <em>slave_3</em>) two of which replicate a database named
<em>sales</em> (<em>slave_0</em>, <em>slave_1</em>).
If the application queries the database <em>slaves</em>, the
hypothetical <em>table</em> filter reduces the list of possible
servers to <em>slave_0</em> and <em>slave_1</em>. Because
the output and list of candidates consists of more than one server, it is
necessary and possible to add additional filters to the candidate list, for example, using
a load balancing filter to identify a server for statement execution.
</p>
</p></blockquote>
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.rwsplit.html">Read-write splitting</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.qos-consistency.html">Service level and consistency</a></div>
<div class="up"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
