The plugin can be used with any PHP MySQL extension
(mysqli,
mysql, and
PDO_MYSQL) that is
compiled to use the mysqlnd library.
PECL/mysqlnd_ms plugs into the mysqlnd library.
It does not change the API or behavior of those extensions.
Whenever a connection to MySQL is being opened, the plugin compares the host
parameter value of the connect call, with the section names
from the plugin specific configuration file. If, for example, the
plugin specific configuration file has a section myapp then
the section should be referenced by opening a MySQL connection to the
host myapp
Example #1 Plugin specific configuration file (mysqlnd_ms_plugin.ini)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Example #2 Opening a load balanced connection
<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
?>
The connection examples above will be load balanced.
The plugin will send read-only statements to the MySQL slave server with the
IP 192.168.2.27 and will listen on port 3306
for the MySQL client connection. All other statements will be directed to the
MySQL master server running on the host localhost. If on Unix like
operating systems, the master on localhost will be accepting
MySQL client connections on the Unix domain socket /tmp/mysql.sock,
while TCP/IP is the default port on Windows.
The plugin will use the user name username and the password
password to connect to any of the MySQL servers listed in
the section myapp of the plugins configuration file. Upon
connect, the plugin will select database as the current
schemata.
The username, password and schema name are taken from the connect
API calls and used for all servers. In other words: you must use the same
username and password for every MySQL server listed in a plugin configuration
file section. The is not a general limitation. As of PECL/mysqlnd_ms 1.1.0,
it is possible to set the
username and
password for any server in the
plugins configuration file, to be used instead of the credentials passed
to the API call.
The plugin does not change the API for running statements. Read-write splitting works out of the box. The following example assumes that there is no significant replication lag between the master and the slave.
Example #3 Executing statements
<?php
/* Load balanced following "myapp" section rules from the plugins config file */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno()) {
/* Of course, your error handling is nicer... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}
/* Statements will be run on the master */
if (!$mysqli->query("DROP TABLE IF EXISTS test")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("CREATE TABLE test(id INT)")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
}
/* read-only: statement will be run on a slave */
if (!($res = $mysqli->query("SELECT id FROM test"))) {
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
} else {
$row = $res->fetch_assoc();
$res->close();
printf("Slave returns id = '%s'\n", $row['id']);
}
$mysqli->close();
?>
The above example will output something similar to:
Slave returns id = '1'