<!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>Read-write splitting</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.loadbalancing.html">Load balancing</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.filter.html">Filter</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.rwsplit" class="section">
<h2 class="title">Read-write splitting</h2>
<p class="para">
The plugin executes read-only statements on the configured MySQL slaves, and
all other queries on the MySQL master. Statements are
considered read-only if they either start with <em>SELECT</em>,
the SQL hint <em>/*ms=slave*/</em>, or if a slave had been chosen for
running the previous query and the query starts with the SQL hint
<em>/*ms=last_used*/</em>. In all other cases, the query will
be sent to the MySQL replication master server. It is recommended to
use the constants <strong><code>MYSQLND_MS_SLAVE_SWITCH</code></strong>,
<strong><code>MYSQLND_MS_MASTER_SWITCH</code></strong> and <strong><code>MYSQLND_MS_LAST_USED_SWITCH</code></strong>
instead of <em>/*ms=slave*/</em>. See also the
<a href="mysqlnd-ms.constants.html" class="link">list of mysqlnd_ms constants</a>.
</p>
<p class="para">
SQL hints are a special kind of standard compliant SQL comments. The plugin
does check every statement for certain SQL hints. The SQL hints are described
within the <a href="mysqlnd-ms.constants.html" class="link">mysqlnd_ms constants</a>
documentation, constants that are exported by the extension. Other systems
involved with the statement processing, such as the MySQL server, SQL firewalls,
and SQL proxies, are unaffected by the SQL hints, because those systems are
designed to ignore SQL comments.
</p>
<p class="para">
The built-in read-write splitter can be replaced by a user-defined filter, see also the
<a href="mysqlnd-ms.plugin-ini-json.html#ini.mysqlnd-ms-plugin-config-v2.filter-user" class="link">user filter</a>
documentation.
</p>
<p class="para">
A user-defined read-write splitter can request the built-in logic to
send a statement to a specific location, by invoking
<span class="function"><strong>mysqlnd_ms_is_select()</strong></span>.
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
The built-in read-write splitter is not aware of multi-statements.
Multi-statements are seen as one statement. The splitter will check the
beginning of the statement to decide where to run the statement. If, for example,
a multi-statement begins with
<em>SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ...</em>
the plugin will run it on a slave although the statement is not read-only.
</p>
</p></blockquote>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.loadbalancing.html">Load balancing</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.filter.html">Filter</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>
