<!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>MySQL Fabric</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.quickstart.partitioning.html">Partitioning and Sharding</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="up"><a href="mysqlnd-ms.quickstart.html">Quickstart and Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.quickstart.mysql_fabric" class="section">
<h2 class="title">MySQL Fabric</h2>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>Version requirement and status</strong><br />
<p class="para">
Work on supporting MySQL Fabric started in version 1.6. Please,
consider the support to be of pre-alpha quality. The manual may
not list all features or feature limitations. This is work in progress.
</p>
<p class="para">
Sharding is the only use case supported by the plugin to date.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<strong>MySQL Fabric concepts</strong><br />
<p class="para">
Please, check the MySQL reference manual for more information about MySQL Fabric
and how to set it up. The PHP manual assumes that you are familiar
with the basic concepts and ideas of MySQL Fabric.
</p>
</p></blockquote>
<p class="para">
MySQL Fabric is a system for managing farms of MySQL servers to achive
High Availability and optionally support sharding. Technically, it is a
middleware to manage and monitor MySQL servers.
</p>
<p class="para">
Clients query MySQL Fabric to obtain lists of MySQL servers,
their state and their roles. For example, clients can request a list of
slaves for a MySQL Replication group and whether they are ready to
handle SQL requests. Another example is a cluster of sharded MySQL servers
where the client seeks to know which shard to query for a given
table and shard key. If configured to use Fabric, the plugin uses XML RCP over HTTP
to obtain the list at runtime from a MySQL Fabric host. The XML remote
procedure call itself is done in the background and transparent from a
developers point of view.
</p>
<p class="para">
Instead of listing MySQL servers directly in the plugins configuration file
it contains a list of one or more MySQL Fabric hosts
</p>
<p class="para">
<div class="example" id="example-2262">
<p><strong>Example #1 Plugin config: Fabric hosts instead of MySQL servers</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">{
"myapp": {
"fabric": {
"hosts": [
{
"host" : "127.0.0.1",
"port" : 8080
}
]
}
}
}</pre>
</div>
</div>
</div>
</p>
<p class="para">
Users utilize the new functions
<span class="function"><a href="function.mysqlnd-ms-fabric-select-shard.html" class="function">mysqlnd_ms_fabric_select_shard()</a></span> and
<span class="function"><a href="function.mysqlnd-ms-fabric-select-global.html" class="function">mysqlnd_ms_fabric_select_global()</a></span> to switch to
the set of servers responsible for a given shard key. Then, the
plugin picks an appropriate server for running queries on.
When doing so, the plugin takes care of additional
load balancing rules set.
</p>
<p class="para">
The below example assumes that MySQL Fabric has been setup
to shard the table <em>test.fabrictest</em> using
the <em>id</em> column of the table as a shard key.
</p>
<p class="para">
<div class="example" id="example-2263">
<p><strong>Example #2 Manual partitioning using SQL hints</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$mysqli </span><span style="color: #007700">= new </span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">, </span><span style="color: #DD0000">"user"</span><span style="color: #007700">, </span><span style="color: #DD0000">"password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br />if (!</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">) {<br /> </span><span style="color: #FF8000">/* Of course, your error handling is nicer... */<br /> </span><span style="color: #007700">die(</span><span style="color: #0000BB">sprintf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d] %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">(), </span><span style="color: #0000BB">mysqli_connect_error</span><span style="color: #007700">()));<br />}<br /><br /></span><span style="color: #FF8000">/* Create a global table - a table available on all shards */<br /></span><span style="color: #0000BB">mysqlnd_ms_fabric_select_global</span><span style="color: #007700">(</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">, </span><span style="color: #DD0000">"test.fabrictest"</span><span style="color: #007700">);<br />if (!</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"CREATE TABLE test.fabrictest(id INT NOT NULL PRIMARY KEY)"</span><span style="color: #007700">)) {<br /> die(</span><span style="color: #0000BB">sprintf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d] %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">errno</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">error</span><span style="color: #007700">));<br />}<br /><br /></span><span style="color: #FF8000">/* Switch connection to appropriate shard and insert record */<br /></span><span style="color: #0000BB">mysqlnd_ms_fabric_select_shard</span><span style="color: #007700">(</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">, </span><span style="color: #DD0000">"test.fabrictest"</span><span style="color: #007700">, </span><span style="color: #0000BB">10</span><span style="color: #007700">);<br />if (!(</span><span style="color: #0000BB">$res </span><span style="color: #007700">= </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"INSERT INTO fabrictest(id) VALUES (10)"</span><span style="color: #007700">))) {<br /> die(</span><span style="color: #0000BB">sprintf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d] %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">errno</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">error</span><span style="color: #007700">));<br />}<br /><br /></span><span style="color: #FF8000">/* Try to read newly inserted record */<br /></span><span style="color: #0000BB">mysqlnd_ms_fabric_select_shard</span><span style="color: #007700">(</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">, </span><span style="color: #DD0000">"test.fabrictest"</span><span style="color: #007700">, </span><span style="color: #0000BB">10</span><span style="color: #007700">);<br />if (!(</span><span style="color: #0000BB">$res </span><span style="color: #007700">= </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT id FROM test WHERE id = 10"</span><span style="color: #007700">))) {<br /> die(</span><span style="color: #0000BB">sprintf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d] %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">errno</span><span style="color: #007700">, </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">error</span><span style="color: #007700">));<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
The example creates the sharded table, inserts a record and reads
the record thereafter. All SQL data definition language (DDL)
operations on a sharded table must be applied to the so called global server group.
Prior to creating or altering a sharded table,
<span class="function"><a href="function.mysqlnd-ms-fabric-select-global.html" class="function">mysqlnd_ms_fabric_select_global()</a></span> is called
to switch the given connection to the corresponding servers of the global
group. Data manipulation (DML) SQL statements must be sent to the shards
directly. The <a href="function.mysqlnd-ms-fabric-select-shard.html" class="link">
<span class="function"><a href="function.mysqlnd-ms-fabric-select-shard.html" class="function">mysqlnd_ms_fabric_select_shard()</a></span></a> switches a
connection to shards handling a certain shard key.
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.quickstart.partitioning.html">Partitioning and Sharding</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.concepts.html">Concepts</a></div>
<div class="up"><a href="mysqlnd-ms.quickstart.html">Quickstart and Examples</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
