Setup

Compile or configure the PHP MySQL extension (API) (mysqli,
PDO_MYSQL,
mysql) that you plan to use with support
for the mysqlnd library. PECL/mysqlnd_ms
is a plugin for the mysqlnd library. To use the plugin with any of the PHP
MySQL extensions, the extension has to use the mysqlnd library.

Then, load the extension into PHP and activate the plugin in the PHP configuration
file using the PHP configuration directive named
mysqlnd_ms.enable.

The plugin uses its own configuration file. Use the PHP
configuration directive
mysqlnd_ms.config_file
to set the full file path to the plugin-specific configuration file.
This file must be readable by PHP (e.g., the web server user).
Please note, the configuration directive mysqlnd_ms.config_file
superseeds mysqlnd_ms.ini_file
since 1.4.0. It is a common pitfall to use the old, no longer available
configuration directive.

Create a plugin-specific configuration file. Save the file to the path
set by the PHP configuration directive
mysqlnd_ms.config_file.

The plugins configuration file
is JSON based. It is divided into one or more sections.
Each section has a name, for example, myapp. Every section
makes its own set of configuration settings.

A section must, at a minimum, list the MySQL replication master server, and set
a list of slaves. The plugin supports using only one master server per section.
Multi-master MySQL replication setups are not yet fully supported.
Use the configuration setting
master
to set the hostname, and the port or socket of the MySQL master server.
MySQL slave servers are configured using the
slave
keyword.

Configuring a MySQL slave server list is required, although it may
contain an empty list. It is recommended to always configure at
least one slave server.

Server lists can use
anonymous or non-anonymous syntax. Non-anonymous
lists include alias names for the servers, such as master_0
for the master in the above example. The quickstart uses the
more verbose non-anonymous syntax.

It is the responsibility of the application to handle potential issues caused
by connection switches, by configuring a master with at least one slave
server, which allows switching to work therefore related problems can be found.

The MySQL master and MySQL slave servers, which you configure, do not need to
be part of MySQL replication setup. For testing purpose you can use single
MySQL server and make it known to the plugin as a master and slave server
as shown below. This could help you to detect many potential issues with
connection switches. However, such a setup will not be prone to the issues
caused by replication lag.

Example #4 Using one server as a master and as a slave (testing only!)

The plugin attempts to notify you of invalid configurations. Since 1.5.0 it
will throw a warning during PHP startup if the configuration file cannot be read,
is empty or parsing the JSON failed. Depending on your PHP settings those
errors may appear in some log files only. Further validation is done when a connection
is to be established and the configuration file is searched for valid sections.
Setting mysqlnd_ms.force_config_usage
may help debugging a faulty setup. Please, see also
configuration file debugging notes.