<!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>Supported clusters</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.concept_cache.html">Cache integration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.setup.html">Installing/Configuring</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.supportedclusters" class="section">
<h2 class="title">Supported clusters</h2>
<p class="para">
Any application using any kind of MySQL cluster is faced with the same tasks:
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Identify nodes capable of executing a given statement with
the required service level
</span>
</li>
<li class="listitem">
<span class="simpara">
Load balance requests within the list of candidates
</span>
</li>
<li class="listitem">
<span class="simpara">
Automatic fail over within candidates, if needed
</span>
</li>
</ul>
</p>
<p class="para">
The plugin is optimized for fulfilling these tasks in the context of a classical
asynchronous MySQL replication cluster consisting of a single master and
many slaves (primary copy). When using classical, asynchronous MySQL replication
all of the above listed tasks need to be mastered at the client side.
</p>
<p class="para">
Other types of MySQL cluster may have lower requirements on the application side.
For example, if all nodes in the cluster can answer read and write requests, no
read-write splitting needs to be done (multi-master, update-all).
If all nodes in the cluster are synchronous, they automatically provide the
highest possible quality of service which makes choosing a node easier.
In this case, the plugin may serve the application after some reconfiguration
to disable certain features, such as built-in read-write splitting.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Documentation focus</strong><br />
<p class="para">
The documentation focusses describing the use of the plugin with classical
asynchronous MySQL replication clusters (primary copy). Support for this
kind of cluster has been the original development goal. Use of other
clusters is briefly described below. Please note, that
this is still work in progress.
</p>
</p></blockquote>
<p class="para">
<em class="emphasis">Primary copy (MySQL Replication)</em>
</p>
<p class="para">
This is the primary use case of the plugin. Follow the hints given in the descriptions of each feature.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Configure one master and one or more slaves.
<a href="mysqlnd-ms.plugin-ini-json.html#mysqlnd-ms.plugin-ini-json.server-list-syntax" class="link">Server configuration details</a>
are given in the setup section.
</span>
</li>
<li class="listitem">
<span class="simpara">
Use random load balancing policy together with the
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filter-random" class="link">sticky</a> flag.
</span>
</li>
<li class="listitem">
<span class="simpara">
If you do not plan to use the
<a href="mysqlnd-ms.quickstart.qos-consistency.html" class="link">service level</a> API calls,
add the <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.master-on-write" class="link">master on write</a>
flag.
</span>
</li>
<li class="listitem">
<span class="simpara">
Please, make yourself aware of the properties of automatic failover before
adding a <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.failover" class="link">failover</a> directive.
</span>
</li>
<li class="listitem">
<span class="simpara">
Consider the use of <a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.trx-stickiness" class="link">trx_stickiness</a>
to execute transactions on the primary only. Please, read carefully how it works
before you rely on it.
</span>
</li>
</ul>
</p>
<p class="para">
<div class="example" id="example-1798">
<p><strong>Example #1 Enabling the plugin (php.ini)</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini</pre>
</div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-1799">
<p><strong>Example #2 Basic plugin configuration (mysqlnd_ms_plugin.ini) for MySQL Replication</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">{
"myapp": {
"master": {
"master_1": {
"host": "localhost",
"socket": "\/tmp\/mysql57.sock"
}
},
"slave": {
"slave_0": {
"host": "127.0.0.1",
"port": 3308
},
"slave_1": {
"host": "192.168.2.28",
"port": 3306
}
},
"filters": {
"random": {
"sticky": "1"
}
}
}
}</pre>
</div>
</div>
</div>
</p>
<p class="para">
<em class="emphasis">Primary copy with multi primaries (MMM - MySQL Multi Master)</em>
</p>
<p class="para">
MySQL Replication allows you to create cluster topologies with multiple masters (primaries).
Write-write conflicts are not handled by the replication system. This is no update anywhere setup.
Thus, data must be partitioned manually and clients must redirected in accordance
to the partitioning rules. The recommended setup is equal to the sharding setup below.
</p>
<p class="para">
<em class="emphasis">Manual sharding, possibly combined with primary copy and multiple primaries</em>
</p>
<p class="para">
Use SQL hints and the node group filter for clusters that use data partitioning
but leave query redirection to the client. The example configuration shows a multi master
setup with two shards.
</p>
<p class="para">
<div class="example" id="example-1800">
<p><strong>Example #3 Multiple primaries - multi master (php.ini)</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
mysqlnd_ms.multi_master=1</pre>
</div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-1801">
<p><strong>Example #4 Primary copy with multiple primaries and paritioning</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">{
"myapp": {
"master": {
"master_1": {
"host": "localhost",
"socket": "\/tmp\/mysql57.sock"
}
"master_2": {
"host": "192.168.2.27",
"socket": "3306"
}
},
"slave": {
"slave_1": {
"host": "127.0.0.1",
"port": 3308
},
"slave_2": {
"host": "192.168.2.28",
"port": 3306
}
},
"filters": {
"node_groups": {
"Partition_A" : {
"master": ["master_1"],
"slave": ["slave_1"]
},
"Partition_B" : {
"master": ["master_2"],
"slave": ["slave_2"]
}
},
"roundrobin": []
}
}
}</pre>
</div>
</div>
</div>
</p>
<p class="para">
The plugin can also be used with a loose collection of unrelated shards. For
such a cluster, configure masters only and disable read write splitting. The nodes of
such a cluster are called masters in the plugin configuration as they accept
both reads and writes for their partition.
</p>
<p class="para">
<em class="emphasis">Using synchronous update everywhere clusters such as MySQL Cluster</em>
</p>
<p class="para">
MySQL Cluster is a synchronous cluster solution. All cluster nodes accept
read and write requests. In the context of the plugin, all nodes shall
be considered as masters.
</p>
<p class="para">
Use the load balancing and fail over features only.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Disable the plugins <a href="mysqlnd-ms.rwsplit.html" class="link">built-in read-write splitting</a>.
</span>
</li>
<li class="listitem">
<span class="simpara">
Configure masters only.
</span>
</li>
<li class="listitem">
<span class="simpara">
Consider random once load balancing strategy, which is the plugins default.
If random once is used, only masters are configured and no SQL hints are used
to force using a certain node, no connection switches will happen for the
duration of a web request. Thus, no special handling is required
for transactions. The plugin will pick one master at the beginning of the
PHP script and use it until the script terminates.
</span>
</li>
<li class="listitem">
<span class="simpara">
Do not set the quality of service. All nodes have all the data. This
automatically gives you the highest possible service quality (strong consistency).
</span>
</li>
<li class="listitem">
<span class="simpara">
Do not enable client-side global transaction injection. It is neither
required to help with server-side fail over nor to assist the quality of service
filter choosing an appropriate node.
</span>
</li>
</ul>
</p>
<p class="para">
Disabling built-in read-write splitting.
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Set
<a href="mysqlnd-ms.configuration.html" class="link"><em>mysqlnd_ms.disable_rw_split=1</em></a>
</span>
</li>
<li class="listitem">
<span class="simpara">
Do not use <a href="mysqlnd-ms.rwsplit.html" class="link">SQL hints</a>
to enforce the use of slaves
</span>
</li>
</ul>
</p>
<p class="para">
Configure masters only.
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Set
<a href="mysqlnd-ms.configuration.html" class="link"><em>mysqlnd_ms.multi_master=1</em>.</a>
</span>
</li>
<li class="listitem">
<span class="simpara">Do not configure any slaves.</span>
</li>
<li class="listitem">
<span class="simpara">
Set
<em><a href="mysqlnd-ms.plugin-ini-json.html" class="link">failover=loop_before_master</a></em>
in the plugins configuration file to avoid warnings about the empty slave list
and to make the failover logic loop over all configured masters before emitting an error.
</span>
<span class="simpara">
Please, note the warnings about automatic failover given in the previous sections.
</span>
</li>
</ul>
</p>
<p class="para">
<div class="example" id="example-1802">
<p><strong>Example #5 Multiple primaries - multi master (php.ini)</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
mysqlnd_ms.multi_master=1
mysqlnd_ms.disable_rw_split=1</pre>
</div>
</div>
</div>
</p>
<p class="para">
<div class="example" id="example-1803">
<p><strong>Example #6 Synchronous update anywhere cluster</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">"myapp": {
"master": {
"master_1": {
"host": "localhost",
"socket": "\/tmp\/mysql57.sock"
},
"master_2": {
"host": "192.168.2.28",
"port": 3306
}
},
"slave": {
},
"filters": {
"roundrobin": {
}
},
"failover": {
"strategy": "loop_before_master",
"remember_failed": true
}
}
}</pre>
</div>
</div>
</div>
</p>
<p class="para">
If running an update everywhere cluster that has no built-in partitioning to
avoid hot spots and high collision rates, consider using the node groups filter
to keep updates on a frequently accessed table on one of the nodes. This may
help to reduce collision rates and thus improve performance.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.concept_cache.html">Cache integration</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.setup.html">Installing/Configuring</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>
