diff --git a/reference/mysqlnd_ms/book.xml b/reference/mysqlnd_ms/book.xml index b014569f91..889e1818bd 100755 --- a/reference/mysqlnd_ms/book.xml +++ b/reference/mysqlnd_ms/book.xml @@ -34,12 +34,6 @@ It does not change existing APIs. Therefore, it can easily be used with existing PHP applications. - - - The mysqlnd replication and load balancing plugin is a beta plugin, and - is not feature complete. - -
Key Features @@ -89,6 +83,34 @@ + + + Can be used with any MySQL clustering solution. + + + + + + MySQL Replication: Read-write splitting is done by the plugin. + Primary focus of the plugin. + + + + + MySQL Cluster: Read-write splitting can be disabled. + Configuration of multiple masters possilbe + + + + + Third-party solutions: the plugin is optimized for MySQL Replication + but can be used with any other kind of MySQL clustering solution. + + + + + + Featured read-write split strategies @@ -210,14 +232,7 @@
Limitations - The plugin does not support MySQL replication setups with more - than one master server. The experimental configuration setting - mysqlnd_ms.multi_master - was introduced in version 1.1.0-beta, to help find ways to remove this - limitation and to enable the use of synchronous clusters, such as MySQL Cluster. - - - The built-in read/write-split mechanism is very basic. Every + The built-in read-write-split mechanism is very basic. Every query which starts with SELECT is considered a read request to be sent to a MySQL slave server. All other queries (such as SHOW statements) @@ -227,7 +242,7 @@ callback function. - The read/write splitter is not aware of multi-statements. Multi-statements + The read-write splitter is not aware of multi-statements. Multi-statements are considered as one statement. The decision of where to run the statement will be based on the beginning of the statement string. For example, if using mysqli_multi_query @@ -236,16 +251,6 @@ SELECT. The INSERT statement, which is also part of the multi-statement, will not be redirected to a master server. - - Prior to version 1.1.0-beta, the plugin did not support native prepared statements. - Please note that PDO_MySQL uses - client-side prepared statement emulation by default. Client-side emulated - prepared statements are fully supported by any version of - the replication and load balancing plugin because the emulation is not - using native prepared statements. If you are using PHP based database - abstraction, please consult the vendor manual to learn if a client-side - prepared statement emulation is used. - Applications must be aware of the consequences of connection switches that are diff --git a/reference/mysqlnd_ms/changes.xml b/reference/mysqlnd_ms/changes.xml index f20c6ff886..74f86e0bdd 100644 --- a/reference/mysqlnd_ms/changes.xml +++ b/reference/mysqlnd_ms/changes.xml @@ -53,7 +53,7 @@ - Introduced new default charset setting offline_server_charset + Introduced new default charset setting server_charset to allow proper escaping before a connection is opened. This is most useful when using lazy connections, which are a default. diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 205e5b857f..24747c16b9 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -358,6 +358,30 @@ the connection state, if needed. + + Charsets and string escaping + + Due to the use of lazy connections, which are a default, it can happen that + an application tries to escape a string for use within SQL statements before + a connection has been established. In this case string escaping is not possible. + The string escape function does not know what charset to use before a connection + has been established. + + + To overcome the problem a new configuration setting + server_charset + has been introduced in version 1.4.0. + + + Attention has to be paid on escaping strings with a certain charset but using + the result on a connection that uses a different charset. Please note, + that PECL/mysqlnd_ms manipulates connections and one application level connection + represents a pool of multiple connections that all may have different default charsets. + It is recommended to configure the servers involved to use the same default charsets. + The configuration setting server_charset does help with this situation as well. + If using server_charset, the plugin will set the given + charset on all newly opened connections. +
diff --git a/reference/mysqlnd_ms/ini.xml b/reference/mysqlnd_ms/ini.xml index a2110b8add..b6b3d33a90 100755 --- a/reference/mysqlnd_ms/ini.xml +++ b/reference/mysqlnd_ms/ini.xml @@ -35,6 +35,12 @@ PHP_INI_SYSTEM + + mysqlnd_ms.config_file + "" + PHP_INI_SYSTEM + + mysqlnd_ms.collect_statistics 0 @@ -99,7 +105,21 @@ - Plugin specific configuration file. + Plugin specific configuration file. This setting has been + renamed to mysqlnd_ms.config_file in version 1.4.0. + + + + + + + mysqlnd_ms.config_file + string + + + + Plugin specific configuration file. This setting superseeds + mysqlnd_ms.ini_file since 1.4.0. diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml index c23a02b09e..c2b9dc7e58 100755 --- a/reference/mysqlnd_ms/quickstart.xml +++ b/reference/mysqlnd_ms/quickstart.xml @@ -21,17 +21,6 @@ difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster will find more information than needed. - - - The documentation has been updated to show the syntax used as of version - 1.1.0-beta. PECL/mysqlnd_ms 1.1.0-beta introduces many - changes. Among - others, it is using a new JSON - based - plugin configuration file - format. - -
Setup diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index 25146ba14e..49e0b3e948 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -1558,6 +1558,113 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio + + Please, see also server_charset to overcome potential + problems with string escaping and servers using different default + charsets. + + + + + + server_charset + string + + + + The setting has been introduced in 1.4.0. It is recommended to set it + if using lazy connections. + + + The server_charset setting serves two purposes. It + acts as a fallback charset to be used for string escaping done before + a connection has been established and it helps to avoid escaping pitfalls + in heteregenous environments which severs using different default charsets. + + + String escaping takes a connections charset into account. String escaping + is not possible before a connection has been opened and the connections + charset is known. The use of lazy connections delays the actual opening + of connections until a statement is send. + + + An application using lazy connections may attempt to escape a string + before sending a statement. In fact, this should be a common case as + the statement string may contain the string that is to be escaped. + However, due to the lazy connection feature no connection has been opened + yet and escaping fails. The plugin may report an error of the type + E_WARNING and a message like (mysqlnd_ms) + string escaping doesn't work without established connection. + Possible solution is to add server_charset to your configuration + to inform you of the pitfall. + + + Setting server_charset makes the plugin use + the given charset for string escaping done on lazy connection handles + before establishing a network connection to MySQL. Furthermore, the + plugin will enforce the use of the charset when the connection is + established. + + + Enforcing the use of the configured charset used for escaping is done + to prevent tapping into the pitfall of using a different charset for + escaping than used later for the connection. This has the additional + benefit of removing the need to align the charset configuration of all + servers used. No matter what the default charset on any of the servers is, + the plugin will set the configured one as a default. + + + The plugin does not stop the user from changing the charset at any time + using the set_charset call or correspoding SQL statements. + Please, note that the use of SQL is not recommended as it cannot be monitored + by the plugin. The user can, for example, change the charset on a + lazy connection handle after escaping a string and before the actual connection + is opened. The charset set by the user will be used for any subsequent escaping + before the connection is established. The connection will be established + using the configured charset, no matter what the server charset is or + what the user has set before. Once a connection has been opened, + set_charset is of no meaning anymore. + + + + String escaping on a lazy connection handle + + + + +real_escape("this will be escaped using the server_charset setting - utf8"); +$mysqli->set_charset("latin1"); +$mysqli->real_escape("this will be escaped using latin1"); +/* server_charset implicitly set - utf8 connection */ +$mysqli->query("SELECT 'This connection will be set to server_charset upon establishing' AS _msg FROM DUAL"); +/* latin1 used from now on */ +$mysqli->set_charset("latin1"); +?> +]]> + + +