PHP Manual :: PECL/mysqlnd_ms 1.5 series

This is the current stable series. Use this version in production environments.

The documentation is complete.

1.5.0-alpha

Release date: 03/2013

Motto/theme: Sharding support, improved transaction support

Bug fixes

Fixed #60605 PHP segmentation fault when mysqlnd_ms is enabled.

Setting transaction stickiness disables all load balancing, including
automatic failover, for the duration of a transaction. So far
connection switches could have happened in the middle of a transaction
in multi-master configurations and during automatic failover although
transaction monitoring had detected transaction boundaries properly.

BC break and bug fix. SQL hints enforcing the use of a specific
kind of server (MYSQLND_MS_MASTER_SWITCH,
MYSQLND_MS_SLAVE_SWITCH,
MYSQLND_MS_LAST_USED_SWITCH) are ignored for the
duration of a transaction of transaction stickiness is enabled and
transaction boundaries have been detected properly.

This is a change in behaviour. However, it is also a bug fix and a step
to align behaviour. If, in previous versions, transaction stickiness,
one of the above listed SQL hints and the quality of service filtering
was combined it could happened that the SQL hints got ignored. In some
case the SQL hints did work, in other cases they did not. The new
behaviour is more consistent. SQL hints will always be ignore for
the duration of a transaction, if
transaction stickiness
is enabled.

Please note, transaction boundary detection continues to be based on API
call monitoring. SQL commands controlling transactions are not monitored.

BC break and bug fix. Calls to mysqlnd_ms_set_qos()
will fail when done in the middle of a transaction if
transaction stickiness
is enabled. Connection switches are not allowed for the duration of a
transaction. Changing the quality of service likely results on a different
set of servers qualifying for query execution, possibly making it
necessary to switch connections. Thus, the call is not allowed in
during an active transaction. The quality of server can, however, be
changed in between transactions.

Feature changes

Introduced the node_group filter.
The filter lets you organize servers (master and slaves)
into groups. Queries can be directed to a certain group of servers
by prefixing the query statement with a SQL hint/comment that contains
the groups configured name. Grouping can be used for
partitioning and sharding, and also to optimize for local caching.
In the case of sharding, a group name can be thought of like a shard key.
All queries for a given shard key will be executed on the
configured shard. Note: both the client and server must support sharding
for sharding to function with mysqlnd_ms.

Extended configuration file validation during PHP startup (RINIT).
An E_WARNING level error will be thrown if the configuration
file can not be read (permissions), is empty, or the file (JSON) could not be parsed.
Warnings may appear in log files, which depending on how PHP is configured.

Distributions that aim to provide a pre-configured setup, including a
configuration file stub, are asked to put {} into
the configuration file to prevent this warning about an invalid
configuration file.

Further configuration file validation is done when parsing sections
upon opening a connection. Please, note that there may still be situations
when an invalid plugin configuration file does not lead to proper error messages
but a failure to connect.

As of PHP 5.5.0, improved support for transaction boundaries detection was added for
mysqli. The mysqli extension has been
modified to use the new C API calls of the mysqlnd
library to begin, commit, and rollback a transaction or savepoint.
If trx_stickiness
is used to enable transaction aware load balancing, the mysqli_begin(),
mysqli_commit() and mysqli_rollback() functions
will now be monitered by the plugin, to go along with the mysqli_autocommit()
function that was already supported. All SQL features to control
transactions are also available through the improved mysqli
transaction control related functions. This means that it is not required to
issue SQL statements instead of using API calls. Applications
using the appropriate API calls can be load balanced by PECL/mysqlnd_ms
in a completely transaction-aware way.

Please note, PDO_MySQL has not been updated
yet to utilize the new mysqlnd API calls. Thus, transaction boundary
detection with PDO_MySQL continues to be limited to
the monitoring by passing in PDO::ATTR_AUTOCOMMIT to
PDO::setAttribute().

Introduced trx_stickiness=on. This
trx_stickiness
option differs from trx_stickiness=master as it
tries to execute a read-only transaction on a slave, if
quality of service (consistency level) allows the use of a slave.
Read-only transactions were introduced in MySQL 5.6, and they
offer performance gains.

Query cache support is considered beta if used with the mysqli
API. It should work fine with primary copy based clusters. For all other
APIs, this feature continues to be called experimental.