Examples
Setup
Setup
Setup
The plugin is implemented as a PHP extension. See
also the installation instructions to install the » PECL/mysqlnd_ms extension.
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.
Example #1 Enabling the plugin (php.ini)
mysqlnd_ms.enable=1 mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
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.
Example #2 Minimal plugin-specific configuration file
(mysqlnd_ms_plugin.ini)
{ "myapp": { "master": { "master_0": { "host": "localhost" } }, "slave": [ ] } }
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.
Example #3 Recommended minimal plugin-specific config
(mysqlnd_ms_plugin.ini)
{ "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "192.168.2.27", "port": "3306" } } } }
If there are at least two servers in total, the
plugin can start to load balance and switch connections. Switching
connections is not always transparent and can cause issues in
certain cases. The reference sections about connection pooling and
switching, transaction handling, fail over load balancing and read-write splitting all
provide more details. And potential pitfalls are described later in
this guide.
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!)
{ "myapp": { "master": { "master_0": { "host": "localhost", "socket": "\/tmp\/mysql.sock" } }, "slave": { "slave_0": { "host": "127.0.0.1", "port": "3306" } } } }
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.