Setup

The plugin is implemented as a PHP extension. Please, follow the installation instructions to install the » PECL/mysqlnd_ms extension. 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 is using its own configuration file. Use the PHP configuration directive mysqlnd_ms.ini_file to set the full path to the plugin-specific configuration file. This file must be readable by PHP.

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

Create a plugin-specific configuration file. Save the file to the path set by the PHP configuration directive mysqlnd_ms.ini_file. The plugin-specific file must be readable by PHP.

The plugins configuration file 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 least list the MySQL replication master server. The plugin supports using only one master server per section. Multi-master MySQL replication setups are not supported. Use the configuration directive master[] to set the hostname and the port or socket of the MySQL master server.

[myapp]
master[]=localhost:/tmp/mysql.sock

It is allowed to set no MySQL slave server but it is not recommended to do. You should always configure at least one slave server as well. Slave servers are set using the configuration directive slave[]. A configuration section may contain no, one or multiple slave[] directives to set no, one or multiple MySQL slaves.

[myapp]
master[]=localhost:/tmp/mysql.sock
slave[]=192.168.2.27: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 section on connection pooling and switching, transaction handling, fail over load balancing and read-write splitting gives details. For now you can continue reading the quickstart. Potential pitfalls will be described later in the quickstart guide.

It is responsibility of the application to handle potential issues caused by connection switches. By always configuring a master and at lease one slave server you can be sure to detect issues early because switches become possible.

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.

[myapp]
master[]=localhost:/tmp/mysql.sock
slave[]=127.0.0.1:3306