<!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>Introduction</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="book.mysqlnd-ms.html">mysqlnd_ms</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.quickstart.html">Quickstart and Examples</a></div>
<div class="up"><a href="book.mysqlnd-ms.html">mysqlnd_ms</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="intro.mysqlnd-ms" class="preface">
<h1 class="title">Introduction</h1>
<p class="para">
The mysqlnd replication and load balancing plugin (<em>mysqlnd_ms</em>)
adds easy to use MySQL replication support to all PHP MySQL extensions that use
<a href="book.mysqlnd.html" class="link">mysqlnd</a>.
</p>
<p class="para">
As of version PHP 5.3.3 the MySQL native driver for PHP
(<em>mysqlnd</em>)
features an internal plugin C API. C plugins, such as the replication and
load balancing plugin, can extend the functionality of
<a href="book.mysqlnd.html" class="link">mysqlnd</a>.
</p>
<p class="para">
The MySQL native driver for PHP is a C library that ships together with
PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
MySQL Client Library (libmysqlclient). Using mysqlnd has
several advantages: no extra downloads are required because it's bundled with PHP,
it's under the PHP license, there is lower memory consumption in certain cases, and
it contains new functionality such as asynchronous queries.
</p>
<p class="para">
Mysqlnd plugins like <em>mysqlnd_ms</em> operate, for the most part,
transparently from a user perspective. The replication and load balancing
plugin supports all PHP applications, and all MySQL PHP extensions.
It does not change existing APIs. Therefore, it can easily be used with
existing PHP applications.
</p>
<div class="section" id="mysqlnd-ms.key-features">
<h2 class="title">Key Features</h2>
<p class="para">
The key features of PECL/mysqlnd_ms are as follows.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Transparent and therefore easy to use.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Supports all of the PHP MySQL extensions.
</p>
</li>
<li class="listitem">
<p class="para">
SSL support.
</p>
</li>
<li class="listitem">
<p class="para">
A consistent <acronym title="Application Programming Interface">API</acronym>.
</p>
</li>
<li class="listitem">
<p class="para">
Little to no application changes required, dependent on the required usage scenario.
</p>
</li>
<li class="listitem">
<p class="para">
Lazy connections: connections to master and slave servers are not
opened before a SQL statement is executed.
</p>
</li>
<li class="listitem">
<p class="para">
Optional: automatic use of master after the first write in a web request, to
lower the possible impact of replication lag.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Can be used with any MySQL clustering solution.
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
MySQL Replication: Read-write splitting is done by the plugin.
Primary focus of the plugin.
</p>
</li>
<li class="listitem">
<p class="para">
MySQL Cluster: Read-write splitting can be disabled.
Configuration of multiple masters possible
</p>
</li>
<li class="listitem">
<p class="para">
Third-party solutions: the plugin is optimized for MySQL Replication
but can be used with any other kind of MySQL clustering solution.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Featured read-write split strategies
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Automatic detection of SELECT.
</p>
</li>
<li class="listitem">
<p class="para">
Supports SQL hints to overrule automatism.
</p>
</li>
<li class="listitem">
<p class="para">
User-defined.
</p>
</li>
<li class="listitem">
<p class="para">
Can be disabled for, for example, when using synchronous clusters such as MySQL Cluster.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Featured load balancing strategies
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Round Robin: choose a different slave in round-robin fashion for every slave request.
</p>
</li>
<li class="listitem">
<p class="para">
Random: choose a random slave for every slave request.
</p>
</li>
<li class="listitem">
<p class="para">
Random once (sticky): choose a random slave once to run all slave requests for the duration of a web request.
</p>
</li>
<li class="listitem">
<p class="para">
User-defined. The application can register callbacks with mysqlnd_ms.
</p>
</li>
<li class="listitem">
<p class="para">
PHP 5.4.0 or newer: transaction aware when using API calls only to control transactions.
</p>
</li>
<li class="listitem">
<p class="para">
Weighted load balancing: servers can be assigned different priorities, for example, to
direct more requests to a powerful machine than to another less powerful machine. Or, to
prefer nearby machines to reduce latency.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Global transaction ID
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Client-side emulation. Makes manual master server failover and slave promotion easier
with asynchronous clusters, such as MySQL Replication.
</p>
</li>
<li class="listitem">
<p class="para">
Support for built-in global transaction identifier feature of MySQL 5.6.5 or newer.
</p>
</li>
<li class="listitem">
<p class="para">
Supports using transaction ids to identify up-to-date asynchronous slaves
for reading when session consistency is required.
</p>
</li>
<li class="listitem">
<p class="para">
Throttling: optionally, the plugin can wait for a slave to become "synchronous" before
continuing.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Service and consistency levels
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Applications can request eventual, session and strong consistency
service levels for connections. Appropriate cluster nodes will
be searched automatically.
</p>
</li>
<li class="listitem">
<p class="para">
Eventual consistent MySQL Replication slave accesses can be replaced
with fast local cache accesses transparently to reduce server load.
</p>
</li>
</ul>
</p>
</li>
<li class="listitem">
<p class="para">
Partitioning and sharding
</p>
<p class="para">
<ul class="itemizedlist">
<li class="listitem">
<p class="para">
Servers of a replication cluster can be organized into groups. SQL hints
can be used to manually direct queries to a specific group.
Grouping can be used to partition (shard) the data, or to cure the issue of
hotspots with updates.
</p>
</li>
<li class="listitem">
<p class="para">
MySQL Replication filters are supported through the table filter.
</p>
</li>
</ul>
</p>
</li>
</ul>
</p>
</div>
<div class="section" id="mysqlnd-ms.limitations">
<h2 class="title">Limitations</h2>
<p class="para">
The built-in read-write-split mechanism is very basic. Every
query which starts with <em>SELECT</em>
is considered a read request to be sent to a MySQL slave server.
All other queries (such as <em>SHOW</em> statements)
are considered as write requests that are sent to the MySQL master server.
The build-in behavior can be overruled using
<a href="mysqlnd-ms.constants.html" class="link">SQL hints</a>, or a user-defined
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filter-user" class="link">callback function</a>.
</p>
<p class="para">
The read-write splitter is not aware of multi-statements. Multi-statements
are considered as one statement. The decision of where to run the statement
will be based on the beginning of the statement string. For example, if
using <span class="function"><a href="mysqli.multi-query.html" class="function">mysqli_multi_query()</a></span>
to execute the multi-statement <em>SELECT id FROM test ; INSERT INTO test(id) VALUES (1)</em>,
the statement will be redirected to a slave server because it begins with
<em>SELECT</em>. The <em>INSERT</em> statement, which is
also part of the multi-statement, will not be redirected to a master server.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
Applications must be aware of the consequences of connection switches that are
performed for load balancing purposes. Please check the documentation on
<a href="mysqlnd-ms.pooling.html" class="link">connection pooling and switching</a>,
<a href="mysqlnd-ms.transaction.html" class="link">transaction handling</a>,
<a href="mysqlnd-ms.failover.html" class="link">failover</a>
<a href="mysqlnd-ms.loadbalancing.html" class="link">load balancing</a> and
<a href="mysqlnd-ms.rwsplit.html" class="link">read-write splitting</a>.
</p>
</p></blockquote>
</div>
<div class="section" id="mysqlnd-ms.name">
<h2 class="title">On the name</h2>
<p class="para">
The shortcut <em>mysqlnd_ms</em>
stands for <em>mysqlnd master slave plugin</em>. The name
was chosen for a quick-and-dirty proof-of-concept. In the beginning
the developers did not expect to continue using the code base.
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="book.mysqlnd-ms.html">mysqlnd_ms</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.quickstart.html">Quickstart and Examples</a></div>
<div class="up"><a href="book.mysqlnd-ms.html">mysqlnd_ms</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
