diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml index f5e63d0d55..d134330286 100755 --- a/reference/mysqlnd_ms/book.xml +++ b/reference/mysqlnd_ms/book.xml @@ -1,5 +1,5 @@ - + Mysqlnd replication and load balancing plugin @@ -13,7 +13,7 @@ mysqlnd. - As of version PHP 5.3.3 the MySQL native driver for PHP + As of version PHP 5.3.3 the MySQL native driver for PHP (mysqlnd) features an internal plugin C API. C plugins, such as the replication and load balancing plugin, can extend the functionality of @@ -159,7 +159,7 @@ is considered a read request to be sent to a MySQL slave server. All other queries, including, for example, SHOW statements, are considered as write requests to be sent to the MySQL master server. - The build-in behaviour can be overruled using + The build-in behaviour can be overruled using SQL hints or an user-defined callback function. @@ -181,20 +181,20 @@ Application must be aware of the consequences of connection switches performed - for load balancing purpose. Please check the documentation on + for load balancing purpose. Please check the documentation on connection pooling and switching, transaction handling, - failover - load balancing and + failover + load balancing and read-write splitting carefully. - +
On the name - The shortcut mysqlnd_ms + The shortcut mysqlnd_ms stands for mysqlnd master slave plugin. The name was chosen for a quick-and-dirty proof-of-concept. In the beginning the developers did not expect to continue using the code base. @@ -205,9 +205,9 @@ &reference.mysqlnd-ms.quickstart; &reference.mysqlnd-ms.concepts; &reference.mysqlnd-ms.setup; - &reference.mysqlnd-ms.constants; + &reference.mysqlnd-ms.constants; &reference.mysqlnd-ms.reference; - &reference.mysqlnd-ms.changes; + &reference.mysqlnd-ms.changes; diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index 9bbd5bea80..dd83e6d139 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -1,8 +1,8 @@ - + - Change History + Change History The Change History lists major changes users need to be aware if upgrading from one version to another. It is a high level summary of selected changes diff --git a/reference/mysqlnd_ms/configure.xml b/reference/mysqlnd_ms/configure.xml index d0f57a073b..38dcb297da 100755 --- a/reference/mysqlnd_ms/configure.xml +++ b/reference/mysqlnd_ms/configure.xml @@ -1,5 +1,5 @@ - +
&reftitle.install; @@ -10,7 +10,7 @@ It is not feature complete. - + &pecl.moved; diff --git a/reference/mysqlnd_ms/constants.xml b/reference/mysqlnd_ms/constants.xml index 8dcf669935..ffb43cae91 100755 --- a/reference/mysqlnd_ms/constants.xml +++ b/reference/mysqlnd_ms/constants.xml @@ -1,5 +1,5 @@ - + &reftitle.constants; @@ -159,7 +159,7 @@ slave_query = /*ms=slave*/SHOW TABLES The plugins version number can be obtained using MYSQLND_MS_VERSION or - MYSQLND_MS_VERSION_ID. + MYSQLND_MS_VERSION_ID. MYSQLND_MS_VERSION is the string representation of the numerical version number MYSQLND_MS_VERSION_ID, which is an integer such as 10000. diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml index 81c80e557e..4a6210c4b2 100755 --- a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml +++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml @@ -1,5 +1,5 @@ - + @@ -15,7 +15,7 @@ - Returns an array of statistics collected by the replication + Returns an array of statistics collected by the replication and load balancing plugin. @@ -23,7 +23,7 @@ mysqlnd_ms.collect_statistics controls the collection of statistics. The collection of statistics is disabled by default for performance reasons. - + The scope of the statistics is the PHP process. @@ -48,8 +48,8 @@ &reftitle.returnvalues; - Returns NULL if - the PHP configuration directive + Returns NULL if + the PHP configuration directive mysqlnd_ms.enable has disabled the plugin. Otherwise, returns array of statistics. @@ -82,7 +82,7 @@ Number of statements considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of slave nor statements directed to a slave by an user-defined - callback are included. The total number of statements sent to the slaves is + callback are included. The total number of statements sent to the slaves is use_slave + use_slave_sql_hint + use_slave_callback. @@ -94,7 +94,7 @@ followed by other filters causing another change in the meaning of the statistic. If, in the future, a load balancing filter is followed by another filter it is no longer guaranteed that the satement, whichs - increments use_slave, will be executed on the slaves. + increments use_slave, will be executed on the slaves. The meaning for version 1.1.0 is as follows. Number of statements @@ -118,7 +118,7 @@ Number of statements not considered as read-only by the built-in query analyzer. Neither statements which begin with a SQL hint to force use of master nor statements directed to a master by an user-defined - callback are included. The total number of statements sent to the master is + callback are included. The total number of statements sent to the master is use_master + use_master_sql_hint + use_master_callback. @@ -228,10 +228,10 @@ Number of successfully opened slave connections from - configurations not using + configurations not using lazy connections. The total number of successfully opened slave connections - is non_lazy_connections_slave_success + + is non_lazy_connections_slave_success + lazy_connections_slave_success Since 1.0.0. @@ -242,7 +242,7 @@ Number of failed slave connection attempts from - configurations not using + configurations not using lazy connections. The total number of failed slave connection attempts is non_lazy_connections_slave_failure + @@ -256,10 +256,10 @@ Number of successfully opened master connections from - configurations not using + configurations not using lazy connections. The total number of successfully opened master connections - is non_lazy_connections_master_success + + is non_lazy_connections_master_success + lazy_connections_master_success Since 1.0.0. @@ -270,7 +270,7 @@ Number of failed master connection attempts from - configurations not using + configurations not using lazy connections. The total number of failed master connection attempts is non_lazy_connections_master_failure + @@ -284,7 +284,7 @@ Number of successfully opened slave connections from - configurations using + configurations using lazy connections. Since 1.0.0. @@ -306,7 +306,7 @@ Number of successfully opened master connections from - configurations using + configurations using lazy connections. Since 1.0.0. @@ -331,11 +331,11 @@ This figure may be used to monitor activity related to the plugin configuration setting trx_stickiness. - If, for example, you want to know if a certain API call invokes the + If, for example, you want to know if a certain API call invokes the mysqlnd library function trx_autocommit(), - which is a requirement for + which is a requirement for trx_stickiness, - you may call the user API function in question and check if the + you may call the user API function in question and check if the statistic has changed. The statistic is modified only by the plugins internal subclassed trx_autocommit() method. @@ -356,7 +356,7 @@ trx_master_forced - Number of statemens redirected to the master while + Number of statemens redirected to the master while trx_stickiness=master and autocommit mode is disabled. @@ -366,7 +366,7 @@ - + &reftitle.examples; diff --git a/reference/mysqlnd_ms/ini.xml b/reference/mysqlnd_ms/ini.xml index 94fa4e880f..3af1b3c450 100755 --- a/reference/mysqlnd_ms/ini.xml +++ b/reference/mysqlnd_ms/ini.xml @@ -1,5 +1,5 @@ - +
&reftitle.runtime; @@ -101,7 +101,7 @@ - Enables or disables the collection of statistics. The collection of + Enables or disables the collection of statistics. The collection of statistics is disabled by default for performance reasons. Statistics are returned by the function mysqlnd_ms_get_stats. @@ -116,8 +116,11 @@ Enables or disables support of MySQL multi master replication setups. + + This feature is experimental. It will not be documented before - reasonable stability has been achieved. + reasonable stability has been achieved. It is meant for development + only. diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index f0fb0e9c4e..f5c9553f02 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -1,11 +1,11 @@ - + Quickstart and Examples The mysqlnd replication load balancing plugin is easy to use. The quickstart will demo typical use-cases and give practical advice on getting - started. + started. It is strongly recommended to read the reference sections in addition to the @@ -13,19 +13,19 @@ and limitations. Instead, it will link to the reference sections. It is safe to begin with the quickstart. However, before using the plugin in mission critical environments we urge you to read additionally the background information from the - reference sections. + reference sections.
Setup - The plugin is implemented as a PHP extension. - Please, follow the + The plugin is implemented as a PHP extension. + Please, follow the installation instructions to - install the + 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. + mysqlnd_ms.enable. The plugin is using its own configuration file. Use the PHP @@ -47,14 +47,14 @@ 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 + 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. + makes its own set of configuration settings. A section must at least list the MySQL replication master server. @@ -80,9 +80,9 @@ master[]=localhost:/tmp/mysql.sock 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 + A configuration section may contain no, one or multiple slave[] directives to set no, one or multiple - MySQL slaves. + MySQL slaves. @@ -100,28 +100,28 @@ 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 + issues in certain cases. The reference section on connection pooling and switching, transaction handling, - fail over - load balancing and + fail over + load balancing and read-write splitting gives details. - For now you can continue reading the quickstart. Potential pitfalls + 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 + 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 + 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 + 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. + caused by replication lag. @@ -135,23 +135,23 @@ slave[]=127.0.0.1:3306 - +
- +
Running statements - The plugin can be used with any PHP MySQL extension + The plugin can be used with any PHP MySQL extension (mysqli, mysql, - PDO_MYSQL) + PDO_MYSQL) compiled to use the mysqlnd library. PECL/mysqlnd_ms plugs into the mysqlnd library. - It does not change the PHP MySQL extensions and their API. + It does not change the PHP MySQL extensions and their API. Whenever a connection to MySQL is being opened, the plugin compares the host - parameter value of the connect call with the section names + parameter value of the connect call with the section names from the plugin specific configuration file. If, for example, the plugin specific configuration file has a section myapp the section should be referenced by opening a MySQL connection to the @@ -189,21 +189,21 @@ $mysql = mysql_connect("myapp", "username", "password"); The plugin will send read-only statements to the MySQL slave server with the IP 192.168.2.27 and listening on port 3306 for MySQL client connection. All other statements will be directed to the - MySQL master server running on the host localhost accepting + MySQL master server running on the host localhost accepting MySQL client connection on the Unix domain socket /tmp/mysql.sock. The plugin will use the user name username and the password password to connect to any of the MySQL servers listed in the section myapp of the plugins configuration file. Upon - connect, the plugin will select database as the current + connect, the plugin will select database as the current schemata. The username, password and schema name are taken from the connect - API calls and used for all servers. In other words: you must use the same - username and password for every MySQL server listed in a plugin configuration + API calls and used for all servers. In other words: you must use the same + username and password for every MySQL server listed in a plugin configuration file section. - The plugin does not change the API for running statements. + The plugin does not change the API for running statements. Read-write splitting - works out of the box. The following example assumes that there is no + works out of the box. The following example assumes that there is no significant replication lag between the master and the slave. @@ -233,7 +233,7 @@ if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { if (!($res = $mysqli->query("SELECT id FROM test")) { printf("[%d] %s\n", $mysqli->errno, $mysqli->error); } else { - $row = $res->fetch_assoc(); + $row = $res->fetch_assoc(); $res->close(); printf("Slave returns id = '%s'\n", $row['id']; } @@ -248,30 +248,30 @@ Slave returns id = '1' ]]> - + The plugin does not support native prepared statements. Prepared - statements are not load balanced. Most users of + statements are not load balanced. Most users of PDO_MYSQL will be unaffected by this restriction because - PDO_MYSQL is using a + PDO_MYSQL is using a client-side prepared statement emulation by default.
- +
Connection state - The plugin changes the semantics of a PHP MySQL connection handle. + The plugin changes the semantics of a PHP MySQL connection handle. A connection handle does no longer represent a single MySQL client-server network connection but a connection pool. The connection pool consists of a master connection and none, one or multiple slave connections. Every connection from the connection pool has its own state. For example, - SQL user variables, temporary tables and transactions are part of the state. + SQL user variables, temporary tables and transactions are part of the state. Please, find a complete list of what belongs to the state of a connection at the concepts page on connection pooling and switching. @@ -328,7 +328,7 @@ $mysqli->close(); - The example opens a load balanced connection and executes two statements. + The example opens a load balanced connection and executes two statements. The first statement SET @myrole='master' does not begin with the string SELECT. Therefore the plugin does not recognize it as a read-only query which shall be run on a slave. The @@ -337,8 +337,8 @@ $mysqli->close(); state of the master connection has been changed. - The next statement is SELECT @myrole AS _role. - The plugin does recognize it as a read-only query and sends it to + The next statement is SELECT @myrole AS _role. + The plugin does recognize it as a read-only query and sends it to the slave. The statement is run on a connection to the slave. This second connection does not have any SQL user variables bound to it. It has a different state than the first connection to the master. @@ -347,7 +347,7 @@ $mysqli->close(); It is the responsibility of the application developer to take care - of the connection state. The plugin does not monitor all + of the connection state. The plugin does not monitor all connection state changing activities. Monitoring all possible cases would be a very CPU intensive task, if it could be done at all. @@ -355,7 +355,7 @@ $mysqli->close(); The pitfalls can easily be worked around using SQL hints.
- +
SQL Hints @@ -370,14 +370,14 @@ $mysqli->close(); or a firewall. - Three SQL hints are supported by the plugin: + Three SQL hints are supported by the plugin: MYSQLND_MS_MASTER_SWITCH, MYSQLND_MS_SLAVE_SWITCH and - MYSQLND_MS_LAST_USED_SWITCH. + MYSQLND_MS_LAST_USED_SWITCH. MYSQLND_MS_MASTER_SWITCH makes the plugin run a statement on the master, MYSQLND_MS_SLAVE_SWITCH enforces the use - of the slave and MYSQLND_MS_MASTER_SWITCH will run a - statement on the same server that has been used for running the previous + of the slave and MYSQLND_MS_MASTER_SWITCH will run a + statement on the same server that has been used for running the previous statement. @@ -434,8 +434,8 @@ $mysqli->close(); - In the example the session variables issue from the previous page is solved - using MYSQLND_MS_LAST_USED_SWITCH to prevent switching + In the example the session variables issue from the previous page is solved + using MYSQLND_MS_LAST_USED_SWITCH to prevent switching from the master to a slave when running the SELECT statement. @@ -460,14 +460,14 @@ if (!$mysqli->query(sprintf("/*%s*/SELECT critical_data FROM important_table", M } ?> ]]> - + use case may include the creation of tables on a slave. If no SQL hint is given, the plugin will send CREATE and INSERT statements to the master. Use the - SQL hint MYSQLND_MS_SLAVE_SWITCH if you want to + SQL hint MYSQLND_MS_SLAVE_SWITCH if you want to run any such statement on a slave, for example, to build temporary reporting tables. @@ -501,23 +501,23 @@ if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM slave_repo $mysqli->close(); ?> ]]> - + The SQL hint MYSQLND_MS_LAST_USED forbids switching - connection and forces the use of the previously used connection. + connection and forces the use of the previously used connection.
- +
Transactions The current version of the plugin is not transaction safe, - because it is not transaction aware. SQL transactions are - units of work to be run on a single server. + because it is not transaction aware. SQL transactions are + units of work to be run on a single server. The plugin does not know when the unit of work starts and when it ends. - Therefore, the plugin may decide to switch connections in the middle + Therefore, the plugin may decide to switch connections in the middle of a transaction. @@ -545,7 +545,7 @@ $mysqli = new mysqli("myapp", "username", "password", "database"); if (!$mysqli) /* Of course, your error handling is nicer... */ die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error())); - + /* Not a SELECT, will use master */ if (!$mysqli->query("START TRANSACTION")) { /* Please use better error handling in your code */ @@ -553,9 +553,9 @@ if (!$mysqli->query("START TRANSACTION")) { } /* Prevent connection switch! */ -if (!$mysqli->query(sprintf("/*%s*/INSERT INTO test(id) VALUES (1)", MYSQLND_MS_LAST_USED_SWITCH)))) { +if (!$mysqli->query(sprintf("/*%s*/INSERT INTO test(id) VALUES (1)", MYSQLND_MS_LAST_USED_SWITCH)))) { /* Please do proper ROLLBACK in your code, don't just die */ - die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM test", MYSQLND_MS_LAST_USED_SWITCH)))) { $row = $res->fetch_assoc(); @@ -564,7 +564,7 @@ if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM test", MYS if (!$mysqli->query(sprintf("/*%s*/INSERT INTO events(task) VALUES ('cleanup')", MYSQLND_MS_LAST_USED_SWITCH)))) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } - } + } } else { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } @@ -590,14 +590,14 @@ $mysqli->close(); If using PHP 5.4.0 or newer, API calls to set the autocommit mode - and setting the experimental plugin configuration option + and setting the experimental plugin configuration option trx_stickiness=master the plugin can automatically disable load balancing and connection switches for SQL transactions. In this configuration the plugin stops load balancing, if autocommit is disabled and directs all statements to the master. This is done to prevent connection switches in the middle of a transaction. Once autocommit gets enabled again, the plugin - starts to load balance statements again. + starts to load balance statements again. @@ -620,7 +620,7 @@ trx_stickiness=master autocommit(FALSE); -if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { +if (!$mysqli->query("INSERT INTO test(id) VALUES (1)")) { /* Please do proper ROLLBACK in your code, don't just die */ - die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); + die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) { $row = $res->fetch_assoc(); @@ -640,7 +640,7 @@ if ($res = $mysqli->query("SELECT COUNT(*) AS _num FROM test")) { if (!$mysqli->query("INSERT INTO events(task) VALUES ('cleanup')")) { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } - } + } } else { die(sprintf("[%d] %s\n", $mysqli->errno, $mysqli->error)); } diff --git a/reference/mysqlnd_ms/reference.xml b/reference/mysqlnd_ms/reference.xml index 089407eab1..3b444a72c4 100755 --- a/reference/mysqlnd_ms/reference.xml +++ b/reference/mysqlnd_ms/reference.xml @@ -1,5 +1,5 @@ - + Mysqlnd_ms &Functions; diff --git a/reference/mysqlnd_ms/versions.xml b/reference/mysqlnd_ms/versions.xml index b130dcd970..1e3f14e79f 100755 --- a/reference/mysqlnd_ms/versions.xml +++ b/reference/mysqlnd_ms/versions.xml @@ -1,5 +1,5 @@ - +