Table of Contents
Copyright 1997-2014 the PHP Documentation Group.
The mysqlnd multiplexing plugin (mysqlnd_mux)
multiplexes MySQL connections established by all PHP MySQL
extensions that use the MySQL native driver
(mysqlnd) for PHP.
The MySQL native driver for PHP features an internal C API for plugins, such as the connection multiplexing plugin, which can extend the functionality of mysqlnd. See the mysqlnd for additional details about its benefits over the MySQL Client Library libmysqlclient.
Mysqlnd plugins like mysqlnd_mux operate, for the
most part, transparently from a user perspective. The connection
multiplexing plugin supports all PHP applications, and all MySQL PHP
extensions. It does not change existing APIs. Therefore, it can
easily be used with existing PHP applications.
This is a proof-of-concept. All features are at an early stage. Not all kinds of queries are handled by the plugin yet. Thus, it cannot be used in a drop-in fashion at the moment.
Please, do not use this version in production environments.
Copyright 1997-2014 the PHP Documentation Group.
The key features of mysqlnd_mux are as follows:
Transparent and therefore easy to use:
Supports all of the PHP MySQL extensions.
Little to no application changes are required, dependent on the required usage scenario.
Reduces server load and connection establishment latency:
Opens less connections to the MySQL server.
Less connections to MySQL mean less work for the MySQL server. In a client-server environment scaling the server is often more difficult than scaling the client. Multiplexing helps with horizontal scale-out (scale-by-client).
Pooling saves connection time.
Multiplexed connection: multiple user handles share the same network connection. Once opened, a network connection is cached and shared among multiple user handles. There is a 1:n relationship between internal network connection and user connection handles.
Persistent connection: a network connection is kept open at the end of the web request, if the PHP deployment model allows. Thus, subsequently web requests can reuse a previously opened connection. Like other resources, network connections are bound to the scope of a process. Thus, they can be reused for all web requests served by a process.
Copyright 1997-2014 the PHP Documentation Group.
The proof-of-concept does not support unbuffered queries, prepared statements, and asynchronous queries.
The connection pool is using a combination of the transport method and hostname as keys. As a consequence, two connections to the same host using the same transport method (TCP/IP, Unix socket, Windows named pipe) will be linked to the same pooled connection even if username and password differ. Be aware of the possible security implications.
The proof-of-concept is transaction agnostic. It does not know about SQL transactions.
Applications must be aware of the consequences of connection sharing connections.
Copyright 1997-2014 the PHP Documentation Group.
The shortcut mysqlnd_mux stands for
mysqlnd connection multiplexing plugin.
Copyright 1997-2014 the PHP Documentation Group.
This explains the architecture and related concepts for this plugin. Reading and understanding these concepts is required to successfully use this plugin.
Copyright 1997-2014 the PHP Documentation Group.
The mysqlnd connection multiplexing plugin is implemented as a PHP extension. It is written in C and operates under the hood of PHP. During the startup of the PHP interpreter, in the module initialization phase of the PHP engine, it gets registered as a mysqlnd plugin to replace specific mysqlnd C methods.
The mysqlnd library uses PHP streams to communicate with the MySQL server. PHP streams are accessed by the mysqlnd library through its net module. The mysqlnd connection multiplexing plugin proxies methods of the mysqlnd library net module to control opening and closing of network streams.
Upon opening a user connection to MySQL using the appropriate connection functions of either mysqli, PDO_MYSQL or ext/mysql, the plugin will search its connection pool for an open network connection. If the pool contains a network connection to the host specified by the connect function using the transport method requested (TCP/IP, Unix domain socket, Windows named pipe), the pooled connection is linked to the user handle. Otherwise, a new network connection is opened, put into the poolm and associated with the user connection handle. This way, multiple user handles can be linked to the same network connection.
Copyright 1997-2014 the PHP Documentation Group.
The plugins connection pool is created when PHP initializes its
modules (MINIT) and free'd when PHP
shuts down the modules (MSHUTDOWN). This is
the same as for persistent MySQL connections.
Depending on the deployment model, the pool is used for the duration of one or multiple web requests. Network connections are bound to the lifespan of an operating system level process. If the PHP process serves multiple web requests as it is the case for Fast-CGI or threaded web server deployments, then the pooled connections can be reused over multiple connections. Because multiplexing means sharing connections, it can even happen with a threaded deployment that two threads or two distinct web requests are linked to one pooled network connections.
A pooled connection is explicitly closed once the last reference to it is released. An implicit close happens when PHP shuts down its modules.
Copyright 1997-2014 the PHP Documentation Group.
The PHP mysqlnd connection multiplexing plugin changes the relationship between a users connection handle and the underlying MySQL connection. Without the plugin, every MySQL connection belongs to exactly one user connection at a time. The multiplexing plugin changes. A MySQL connection is shared among multiple user handles. There no one-to-one relation if using the plugin.
Sharing pooled connections has an impact on the connection state. State changing operations from multiple user handles pointing to one MySQL connection are not isolated from each other. If, for example, a session variable is set through one user connection handle, the session variable becomes visible to all other user handles that reference the same underlying MySQL connection.
This is similar in concept to connection state related phenomens described for the PHP mysqlnd replication and load balancing plugin. Please, check the PECL/mysqlnd_ms documentation for more details on the state of a connection.
The proof-of-concept takes no measures to isolate multiplexed connections from each other.
Copyright 1997-2014 the PHP Documentation Group.
Copyright 1997-2014 the PHP Documentation Group.
PHP 5.5.0 or newer. Some advanced
functionality requires PHP 5.5.0 or newer.
The mysqlnd_mux replication and load
balancing plugin supports all PHP applications and all available
PHP MySQL extensions
(mysqli,
mysql,
PDO_MYSQL). The PHP
MySQL extension must be configured to use
mysqlnd in order to be
able to use the mysqlnd_mux plugin for
mysqlnd.
Copyright 1997-2014 the PHP Documentation Group.
Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/mysqlnd_mux
Copyright 1997-2014 the PHP Documentation Group.
The behaviour of these functions is affected by settings in php.ini.
Table 10.1 Mysqlnd_mux Configure Options
| Name | Default | Changeable | Changelog |
|---|---|---|---|
| mysqlnd_mux.enable | 0 | PHP_INI_SYSTEM |
Here's a short explanation of the configuration directives.
Copyright 1997-2014 the PHP Documentation Group.
The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
Other
The plugins version number can be obtained using
MYSQLND_MUX_VERSION or
MYSQLND_MUX_VERSION_ID.
MYSQLND_MUX_VERSION is the string
representation of the numerical version number
MYSQLND_MUX_VERSION_ID, which is an integer
such as 10000. Developers can calculate the version number as
follows.
| Version (part) | Example |
|---|---|
| Major*10000 | 1*10000 = 10000 |
| Minor*100 | 0*100 = 0 |
| Patch | 0 = 0 |
| MYSQLND_MUX_VERSION_ID | 10000 |
Copyright 1997-2014 the PHP Documentation Group.
This change history is a high level summary of selected changes that may impact applications and/or break backwards compatibility.
See also the CHANGES file in the source
distribution for a complete list of changes.
Copyright 1997-2014 the PHP Documentation Group.
1.0.0-pre-alpha
Initial check-in. Essentially a demo of the mysqlnd plugin API.
This is the current development series. All features are at an early stage. Changes may happen at any time without prior notice. Please, do not use this version in production environments.
The documentation may not reflect all changes yet.