Configuration

Le plugin est une extension PHP. Veuillez lire les instructions d'installation pour installer l'extension » PECL/mysqlnd_ms.

Configurez une extension PHP pour MySQL (mysqli, PDO_MYSQL, mysql) au choix pour profiter du support de mysqlnd. PECL/mysqlnd_ms est un plugin pour mysqlnd. Pour l'utiliser avec une extension PHP pour MySQL, celle-ci devra faire usage de mysqlnd.

Ensuite, chargez l'extension dans PHP et activez le plugin en utilisant la directive de configuration mysqlnd_ms.enable.

mysqlnd_ms.enable=1
mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini

Le plugin utilise son propre fichier de configuration. Utilisez la directive mysqlnd_ms.config_file pour indiquer le chemin complet vers le fichier de configuration du plugin. Ce fichier doit être accessible en lecture à PHP (e.g. l'utilisateur exécutant le serveur web). Veuillez noter que la directive de configuration mysqlnd_ms.config_file annule et remplace la directive mysqlnd_ms.ini_file depuis la version 1.4.0. C'est une erreur courante que d'utiliser l'ancienne, alors qu'elle n'est plus disponible comme directive de configuration.

Créez un fichier de configuration pour le plugin. Indiquez son chemin complet dans mysqlnd_ms.config_file.

Les fichiers de configuration sont décrits en JSON. Il existe dedans une ou plusieurs sections. Chaque section a un nom, par exemple, myapp. Chaque section comporte ses directives.

Une section doit au minimum indiquer le serveur maitre de réplication MySQL et une liste d'esclaves. Le plugin ne supporte qu'un seul maitre par section. Le multi-maitre n'est pas encore pleinement supporté. Utilisez la directive master pour indiquer l'hote et le port ou le socket du serveur MySQL maitre. Les escalves MySQL sont indiqués via la directive slave.

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost"
            }
        },
        "slave": [

        ]
    }
}

Une liste d'esclaves MySQL est obligatoire, même si celle-ci est vide. Il est recommandé de toujours posséder au moins un esclave.

Les listes de serveurs peuvent utiliser les syntaxes anonyme ou non-anonyme. Les listes non-anonymes incluent un alias pour le nom du serveur, comme master_0 pour un maitre. Le guide de démarrage rapide utilise la syntaxe non-anonyme.

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "192.168.2.27",
                "port": "3306"
            }
        }
    }
}

S'il existe au moins deux serveurs déclarés en configuration, le plugin peut commencer à équilibrer la charge entre les connexions. La bascule entre les connexions n'est pas tout le temps transparente et peut générer des problèmes. Voyez les références sur les pools de connexions et les bascules, la gestion des transactions, la reprise sur incident l'équilibre de la charge et la découpe des lectures-écritures pour les détails. Vous pouvez désormais continuer de lire ce guide de démarrage. Les astuces et problèmes éventuels du plugin vont être détaillées par la suite.

Il est de la responsabilité de l'application de gérer les éventuels problèmes dûs à la bascule entre les connexions. En configurant au moins un maitre et un esclave, vous vous assurez que le plugin basculera les connexions, et vous détecterez les problèmes plus tôt.

Les serveurs maitre et esclave que vous configurez peuvent être la même machine. Cela peut aider à détecter les erreurs dûes à la bascule entre les connexions, mais pas les erreurs dûes à la latence de la réplication.

{
    "myapp": {
        "master": {
            "master_0": {
                "host": "localhost",
                "socket": "\/tmp\/mysql.sock"
            }
        },
        "slave": {
            "slave_0": {
                "host": "127.0.0.1",
                "port": "3306"
            }
        }
    }
}

Le plugin tente de vous notifier des configurations invalides. Depuis la version 1.5.0, il va émettre une alerte lors du démarrage de PHP si le fichier de configuration ne peut être lu, s'il est vide, ou si l'analyse JSON échoue. Suivant votre configuration de PHP, ces erreurs peuvent apparaître seulement dans des fichiers de log. Une autre validation est effectuée lorsqu'une connexion est établie et que le fichier de configuration est analysé pour y rechercher des sections valides. Le fait de définir la directive mysqlnd_ms.force_config_usage peut vous aider à déboguer une configuration erronée. Voir aussi les notes relatives au débogage du fichier de configuration.