Le plugin peut être utilisé avec n'importe quelle extension PHP pour MySQL (mysqli, mysql et PDO_MYSQL) compilée avec le support mysqlnd. PECL/mysqlnd_ms se branche sur la bibliothèque mysqlnd. Ceci ne change pas les API des extensions de PHP pour MySQL.
Dès lors qu'une connexion à MySQL est ouverte, le plugin compare l'hôte aux sections déclarées dans le fichier de configuration. Par exemple une section myapp sera chargée si une connexion MySQL à l'hôte myapp est effectuée.
Exemple #1 Fichier de configuration du plugin (mysqlnd_ms_plugin.ini)
{
"myapp": {
"master": {
"master_0": {
"host": "localhost",
"socket": "\/tmp\/mysql.sock"
}
},
"slave": {
"slave_0": {
"host": "192.168.2.27",
"port": "3306"
}
}
}
}
Exemple #2 Ouvrir une connexion sujette à équilibrage
<?php
/* La section "myapp" du fichier de configuration du plugin sera chargée */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");
?>
Les connexions ouvertes dans l'exemple ci-dessus seront équilibrées en charge. Le plugin enverra les requêtes en lecture au serveur ayant l'IP 192.168.2.27 sur le port3306. Toutes les autres requêtes seront dirigées vers l'hôte maitre à localhost sur son socket /tmp/mysql.sock. Le plugin utilisera le nom username et le mot de passe password pour se connecter à tout hôte déclaré dans la section myapp. Une fois connecté, le plugin va sélectionner database comme nom de base de données.
Les nom d'utilisateur, mot de passe et nom de base sont issus des appels à l'API pour la connexion et sont utilisés pour tous les serveurs. En d'autres termes, vous devez utiliser les mêmes nom d'utilisateur et mot de passe pour tous les serveurs listés dans une section de configuration. Ce n'est pas une limite globale. Depuis PECL/mysqlnd_ms 1.1.0, il est possible d'utiliser un nom d'utilisateur et un mot de passe pour chaque serveur listé dans le fichier de configuration.
Le plugin ne change pas l'API pour les requêtes en cours. la découpe des lectures-écritures fonctionne par défaut. L'exemple suivant suppose qu'il y a peu de latence entre le maitre et l'esclave.
Exemple #3 Exécuter des requêtes
<?php
/* Equilibré selon la section "myapp" du fichier de configuration du plugin */
$mysqli = new mysqli("myapp", "username", "password", "database");
if (mysqli_connect_errno()) {
/* Evidemment, votre propre gestion des erreurs serait meilleure... */
die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
}
/* Requêtes lancées sur le maitre */
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);
}
/* lecture seule: requêtes lancées sur un esclave */
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();
?>
L'exemple ci-dessus va afficher quelque chose de similaire à :
Slave returns id = '1'