sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updates for 1.4 (server_charset, config_file) and removing a warning on beta status or the like here and there

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@325466 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2012-04-26 19:54:56 +00:00
parent 6c0500759f
commit 649f89731c
6 changed files with 183 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
reference/mysqlnd_ms/book.xml
View file

@ -34,12 +34,6 @@
It does not change existing APIs. Therefore, it can easily be used with
existing PHP applications.
</para>
<note>
<para>
The mysqlnd replication and load balancing plugin is a beta plugin, and
is not feature complete.
</para>
</note>
<section xml:id="mysqlnd-ms.key-features">
<title>Key Features</title>
<para>
@ -89,6 +83,34 @@
</para>
</listitem>
<listitem>
<para>
Can be used with any MySQL clustering solution.
</para>
<para>
<itemizedlist>
<listitem>
<para>
MySQL Replication: Read-write splitting is done by the plugin.
Primary focus of the plugin.
</para>
</listitem>
<listitem>
<para>
MySQL Cluster: Read-write splitting can be disabled.
Configuration of multiple masters possilbe
</para>
</listitem>
<listitem>
<para>
Third-party solutions: the plugin is optimized for MySQL Replication
but can be used with any other kind of MySQL clustering solution.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Featured read-write split strategies
@ -210,14 +232,7 @@
<section xml:id="mysqlnd-ms.limitations">
<title>Limitations</title>
<para>
The plugin does not support MySQL replication setups with more
than one master server. The experimental configuration setting
<link linkend="ini.mysqlnd-ms.multi-master"><literal>mysqlnd_ms.multi_master</literal></link>
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.
</para>
<para>
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 <literal>SELECT</literal>
is considered a read request to be sent to a MySQL slave server.
All other queries (such as <literal>SHOW</literal> statements)
@ -227,7 +242,7 @@
<link linkend="ini.mysqlnd-ms-plugin-config-v2.filter-user">callback function</link>.
</para>
<para>
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 <function>mysqli_multi_query</function>
@ -236,16 +251,6 @@
<literal>SELECT</literal>. The <literal>INSERT</literal> statement, which is
also part of the multi-statement, will not be redirected to a master server.
</para>
<para>
Prior to version 1.1.0-beta, the plugin did not support native prepared statements.
Please note that <link linkend="ref.pdo-mysql">PDO_MySQL</link> 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.
</para>
<note>
<para>
Applications must be aware of the consequences of connection switches that are

2
reference/mysqlnd_ms/changes.xml
View file

@ -53,7 +53,7 @@
</listitem>
<listitem>
<para>
Introduced new default charset setting <literal>offline_server_charset</literal>
Introduced new default charset setting <literal>server_charset</literal>
to allow proper escaping before a connection
is opened. This is most useful when using lazy connections, which are a default.
</para>

24
reference/mysqlnd_ms/concepts.xml
View file

@ -358,6 +358,30 @@
the connection state, if needed.
</para>
</caution>
<para>Charsets and string escaping</para>
<para>
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.
</para>
<para>
To overcome the problem a new configuration setting
<link linkend="ini.mysqlnd-ms-plugin-config-v2.server-charset"><literal>server_charset</literal></link>
has been introduced in version 1.4.0.
</para>
<para>
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 <literal>server_charset</literal> does help with this situation as well.
If using <literal>server_charset</literal>, the plugin will set the given
charset on all newly opened connections.
</para>
</section>
<section xml:id="mysqlnd-ms.transaction">

22
reference/mysqlnd_ms/ini.xml
View file

@ -35,6 +35,12 @@
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script --></entry>
</row>
<row>
<entry><link linkend="ini.mysqlnd-ms.config-file">mysqlnd_ms.config_file</link></entry>
<entry>""</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script --></entry>
</row>
<row>
<entry>mysqlnd_ms.collect_statistics</entry>
<entry>0</entry>
@ -99,7 +105,21 @@
</term>
<listitem>
<para>
Plugin specific configuration file.
Plugin specific configuration file. This setting has been
renamed to <literal>mysqlnd_ms.config_file</literal> in version 1.4.0.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms.config-file">
<term>
<parameter>mysqlnd_ms.config_file</parameter>
<type>string</type>
</term>
<listitem>
<para>
Plugin specific configuration file. This setting superseeds
<literal>mysqlnd_ms.ini_file</literal> since 1.4.0.
</para>
</listitem>
</varlistentry>

11
reference/mysqlnd_ms/quickstart.xml
View file

@ -21,17 +21,6 @@
difficult to use than a synchronous one. Thus, users of, for example, MySQL Cluster
will find more information than needed.
</para>
<note>
<para>
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
<link linkend="mysqlnd-ms.changes-one-one">changes</link>. Among
others, it is using a new <literal>JSON</literal>
based
<link linkend="mysqlnd-ms.plugin-ini-json">plugin configuration file</link>
format.
</para>
</note>
<section xml:id="mysqlnd-ms.quickstart.configuration">
<title>Setup</title>
<para>

107
reference/mysqlnd_ms/setup.xml
View file

@ -1558,6 +1558,113 @@ function pick_server($connected, $query, $masters, $slaves, $last_used_connectio
</programlisting>
</example>
</para>
<para>
Please, see also <literal>server_charset</literal> to overcome potential
problems with string escaping and servers using different default
charsets.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.server-charset">
<term>
<parameter>server_charset</parameter>
<type>string</type>
</term>
<listitem>
<para>
The setting has been introduced in 1.4.0. It is recommended to set it
if using lazy connections.
</para>
<para>
The <literal>server_charset</literal> 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.
</para>
<para>
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.
</para>
<para>
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
<literal>E_WARNING</literal> and a message like <literal>(mysqlnd_ms)
string escaping doesn't work without established connection.
Possible solution is to add server_charset to your configuration</literal>
to inform you of the pitfall.
</para>
<para>
Setting <literal>server_charset</literal> 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.
</para>
<para>
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.
</para>
<para>
The plugin does not stop the user from changing the charset at any time
using the <function>set_charset</function> 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,
<literal>set_charset</literal> is of no meaning anymore.
</para>
<para>
<example>
<title>String escaping on a lazy connection handle</title>
<programlisting role="ini">
<![CDATA[
{
"myapp": {
"master": {
"master_0": {
"host": "localhost"
}
},
"slave": {
"slave_0": {
"host": "192.168.78.136",
"port": "3306"
}
},
"lazy_connections": 1,
"server_charset" : "utf8"
}
}
]]>
</programlisting>
<programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("myapp", "username", "password", "database");
$mysqli->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");
?>
]]>
</programlisting>
</example>
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.master-on-write">