Fichier de configuration du plugin (<= 1.0.x)

Note:

La description suivante s'applique à PECL/mysqlnd_ms < 1.1.0-beta. Elle n'est pas valide pour les versions supérieures.

Le plugin utilise son propre fichier de configuration. Ce fichier contient les informations sur les serveurs maîtres de réplication MySQL, les serveurs esclaves de réplication MySQL, la politique de sélection de serveur (balance de charge), la stratégie de basculement ainsi que l'utilisation des connexions paresseuses.

La directive de configuration PHP mysqlnd_ms.ini_file est utilisée pou définir le fichier de configuration du plugin.

Le fichier de configuration reprend le standard du format php.ini. Il contient un ou plusieurs sections. Chaque section définit sa propre unité de configuration. Il n'y a pas de section globale pour la configuration par défaut.

Les applications se réfèrent aux sections par leurs noms. Les applications utilisent les noms de section comme paramètre de l'hôte (serveur) dans les différentes méthodes de connexion des extensions comme mysqli, mysql et PDO_MYSQL. Lors de la connexion, le plugin mysqlnd compare le nom de l'hôte avec tous les noms de section depuis le fichier de configuration du plugin. Si le nom d'hôte et le nom de section correspondent, le plugin chargera la configuration depuis cette section.

<?php
/* Toutes les sections suivantes seront soumises à la balance de charge */
$mysqli = new mysqli("myapp", "username", "password", "database");
$pdo = new PDO('mysql:host=myapp;dbname=database', 'username', 'password');
$mysql = mysql_connect("myapp", "username", "password");

$mysqli = new mysqli("localhost", "username", "password", "database");
?>

Les noms de section sont des chaînes de caractères. Il est valide d'utiliser un nom de section comme 192.168.2.1, 127.0.0.1 ou localhost. Si, par exemple, une application se connecte à localhost et une section de configuration du plugin [localhost] existe, la sémantique de l'opération de connexion change. L'application n'utilisera plus seulement le serveur MySQL fonctionnant sur l'hôte localhost, mais le plugin commencera à balancer la charge des requêtes MySQL en suivant les règles depuis la section de configuration [localhost]. De cette façon, vous pouvez effectuer un balance de charge depuis une application sans aucune modification du code source de l'application.

Les directives de configuration master[], slave[] et pick[] utilisent une syntaxe sous forme de liste. Ces directives peuvent apparaître à plusieurs reprises dans une section de configuration. Le plugin maintient l'ordre dans laquelle les entrées apparaîssent au moment de leurs interprétations. Par exemple, l'exemple ci-dessous montre les directives de configuration pour 2 slave[] dans la section de configuration [myapp]. Si vous utilisez la balance de charge round-robin pour les requêtes en lecture seule, le plugin enverra la premère requête en lecture seule au serveur MySQLL mysql_slave_1 parce qu'il est premier dans la liste. La seconde requête en lecture seule sera envoyée au serveur MySQL mysql_slave_2 parce qu'il est second sur la liste. Les directives de configuration supportant la syntaxe sous forme de liste sont ordonnées depuis le haut vers le bas, dans l'ordre de leurs apparissions dans la section de configuration.

[myapp]
master[] = mysql_master_server
slave[] = mysql_slave_1
slave[] = mysql_slave_2

Voici une explication brève sur les directives de configuration pouvant être utilisées.

master[] string

URI d'un serveur de réplication MySQL maitres. L'URI est de la forme hostname[:port|unix_domain_socket].

Le plugin ne supporte que l'utilisation d'un seul maitre à la fois.

Déclarer un maitre est obligatoire. Le plugin renverra une alerte à la connexion si il ne trouve pas de maitre dans la configuration. Ce message d'alerte peut ressembler à (mysqlnd_ms) Cannot find master section in config. Aussi, le plugin renseignera sur un code d'erreur pour la connexion HY000/2000 (CR_UNKNOWN_ERROR). Le message dépend de la langue considérée.

slave[] string

URI d'un ou plusieurs serveurs de réplication MySQL esclaves. L'URI est de la forme hostname[:port|unix_domain_socket].

Le plugin supporte l'utilisation d'un ou plusieurs esclaves.

Déclarer au moins un esclave est obligatoire. Le plugin renverra une alerte à la connexion s'il ne trouve pas au moins un esclave dans la configuration. Ce message d'alerte peut ressembler à (mysqlnd_ms) Cannot find slaves section in config. Aussi, le plugin renseignera sur un code d'erreur pour la connexion HY000/2000 (CR_UNKNOWN_ERROR).Le message dépend de la langue considérée.

pick[] string

Politique de balance de charge (choix du serveur). Sont supportées : random, random_once (defaut), roundrobin, user.

Si aucune politique n'est précisée, random_once sera utilisée. La politique random_once choisit un serveur esclave au hasard lors de la première requête en lecture. Le serveur esclave sera alors utilisé pour toutes les requêtes en lecture jusqu'à l'extinction de PHP.

La politique random choisira un serveur esclave au hasard pour chaque requête de lecture.

Avec roundrobin le plugin parcourt la liste des esclaves déclarés et les choisit un-à-un pour chaque requête. Si le plugin atteint la fin de la liste, il prendra le premier serveur esclave configuré.

Utiliser plus d'une politique d'équilibrage par section de configuration n'est effectif qu'avec la politique user et avec mysqlnd_ms_set_user_pick_server(). Si la fonction utilisateur échoue à la selection d'un serveur, le plugin se rabat sur le second choix de politique d'équilibrage.

failover string

Politique de gestion des incidents (failover). Sont supportées : disabled (défaut), master.

Si aucune politique de gestion d'incident (failover) n'est utilisée, le plugin n'effectuera aucun failover automatique (failover=disabled). Dès lors que le plugin échoue à la connexion sur un serveur, il émet un warning et change le code d'erreur et le message d'erreur de la connexion. Après, c'est à l'application de gérer l'erreur et d'éventuellement relancer la requête pour déclencher la selection d'un autre serveur.

Si vous utilisez failover=master, le plugin changera vers un esclave automatiquement en failover, si possible. Veuillez lire la documentation dans le cas de l'utilisation de failover=master, cela comporte des risques à connaitre.

lazy_connections bool

Utilise ou non des connexions paresseuses. Ce sont des connexions qui ne sont pas établies tant que le client n'envoie pas d'informations vers celle-ci.

Il est fortement recommandé d'utiliser les connexions paresseuses, car elles aident à réduire le nombre de connexions simultanées ouvertes. Si vous les désactivez, et que par exemple, vous configurez un maitre de réplication et deux esclaves, le plugin ouvrira alors 3 connexions dès le premier appel alors que l'application pourrait ne vouloir utiliser que le maitre.

Les connexions parresseuses représentent par contre un problème si vous changez souvent le statut de vos connexions. En effet, le plugin ne fait suivre les ordres de changement de statut qu'aux connexions effectivement déja ouvertes, et non à celles qui sont configurées, mais pas encore ouvertes. Par exemple, si le jeu de caractères devait être changé en utilisant un appel PHP vers l'API MySQL, le plugin ne changera que pour les connexions ouvertes. Il ne se souviendra pas du jeu de caractères à appliquer aux futures connexions à établir, elles supporteront alors un autre jeu de caractères, ce qui n'est pas très intelligent, étant donné que les jeux de caractères sont utilisés dans l'échappement.

master_on_write bool

Si utilisé, le plugin utilisera le maitre immédiatement après le premier appel à celui-ci. Les applications pourront toujours utiliser les astuces SQL pour discuter avec les esclaves.

Ce paramètre peut aider à réduire la latence de la réplication. Si une application lance un INSERT le plugin selectionnera par défaut le maitre pour toutes les requêtes futures, y compris les SELECT. Ceci aide à éviter les problèmes de lectures sur des esclaves qui n'ont pas encore répliqué le INSERT précédent.

trx_stickiness string

Politique d'accrochage des transactions. Sont supportées : disabled (défaut), master.

Fonctionnalité expérimentale.

Cette fonctionnalité requiert 5.4.0 ou plus récent. Si vous utilisez PHP avant 5.4.0, le plugin va emettre un warning comme (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99.

Si aucune politique d'accrochage des transactions n'est utilisée ou si trx_stickiness=disabled, le plugin n'est pas relatif aux transactions. Ainsi, le plugin pourrait équilibrer les connexions et basculer d'une à l'autre en plein milieu d'une transaction. Le plugin n'est pas sûr pour les transactions. Des astuces SQL devraient être utilisées pour éviter de tels cas.

Depuis PHP 5.4.0, la bibliothèque mysqlnd permet au plugin de surveiller le mode autocommit en appelant la fonction trx_autocommit(). Si trx_stickiness=master et autocommit que les transactions sont désactivées suite à un appel de mysqlnd à trx_autocommit(), le plugin devient sensible au début de la transaction. Il arrête alors l'équilibrage de charge automatique et dirige les requêtes vers le maitre jusqu'à ce que autocommit soit activé. Ainsi, aucune astuce SQL n'est requise.

Un exemple d'une fonction PHP déclenchant un appel de mysqlnd à trx_autocommit() est mysqli_autocommit().

Même si trx_stickiness=master, le plugin ne peut être mis au courant des changements du mode autocommit causés par des requêtes SQL comme SET AUTOCOMMIT=0.