mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
My dear editor has removed a bit of end of line whitespace.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317392 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel
parent
7327d8a184
commit
174c6269a5
9 changed files with 114 additions and 111 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<book xml:id="book.mysqlnd-ms" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Mysqlnd replication and load balancing plugin</title>
|
||||
|
|
@ -13,7 +13,7 @@
|
|||
<link linkend="book.mysqlnd">mysqlnd</link>.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
(<literal>mysqlnd</literal>)
|
||||
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, <literal>SHOW</literal>
|
||||
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
|
||||
<link linkend="mysqlnd-ms.constants">SQL hints</link> or an user-defined
|
||||
<link linkend="function.mysqlnd-ms-set-user-pick-server">callback function</link>.
|
||||
</para>
|
||||
|
|
@ -181,20 +181,20 @@
|
|||
<note>
|
||||
<para>
|
||||
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
|
||||
<link linkend="mysqlnd-ms.pooling">connection pooling and switching</link>,
|
||||
<link linkend="mysqlnd-ms.transaction">transaction handling</link>,
|
||||
<link linkend="mysqlnd-ms.failover">failover</link>
|
||||
<link linkend="mysqlnd-ms.loadbalancing">load balancing</link> and
|
||||
<link linkend="mysqlnd-ms.failover">failover</link>
|
||||
<link linkend="mysqlnd-ms.loadbalancing">load balancing</link> and
|
||||
<link linkend="mysqlnd-ms.rwsplit">read-write splitting</link> carefully.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="mysqlnd-ms.name">
|
||||
<title>On the name</title>
|
||||
<para>
|
||||
The shortcut <literal>mysqlnd_ms</literal>
|
||||
The shortcut <literal>mysqlnd_ms</literal>
|
||||
stands for <literal>mysqlnd master slave plugin</literal>. 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;
|
||||
|
||||
</book>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<chapter xml:id="mysqlnd-ms.changes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title xmlns="http://docbook.org/ns/docbook">Change History</title>
|
||||
<title xmlns="http://docbook.org/ns/docbook">Change History</title>
|
||||
<para>
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<section xml:id="mysqlnd-ms.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.install;
|
||||
|
|
@ -10,7 +10,7 @@
|
|||
It is not feature complete.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
|
||||
<para>
|
||||
&pecl.moved;
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<appendix xml:id="mysqlnd-ms.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
&reftitle.constants;
|
||||
|
|
@ -159,7 +159,7 @@ slave_query = /*ms=slave*/SHOW TABLES
|
|||
<para>
|
||||
The plugins version number can be obtained using
|
||||
<constant>MYSQLND_MS_VERSION</constant> or
|
||||
<constant>MYSQLND_MS_VERSION_ID</constant>.
|
||||
<constant>MYSQLND_MS_VERSION_ID</constant>.
|
||||
<constant>MYSQLND_MS_VERSION</constant>
|
||||
is the string representation of the numerical version number
|
||||
<constant>MYSQLND_MS_VERSION_ID</constant>, which is an integer such as 10000.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<refentry xml:id="function.mysqlnd-ms-get-stats" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<refnamediv>
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
<void />
|
||||
</methodsynopsis>
|
||||
<para>
|
||||
Returns an array of statistics collected by the replication
|
||||
Returns an array of statistics collected by the replication
|
||||
and load balancing plugin.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -23,7 +23,7 @@
|
|||
<literal><link linkend="ini.mysqlnd-ms.collect_statistics">mysqlnd_ms.collect_statistics</link></literal>
|
||||
controls the collection of statistics. The collection of statistics
|
||||
is disabled by default for performance reasons.
|
||||
</para>
|
||||
</para>
|
||||
<para>
|
||||
The scope of the statistics is the
|
||||
<literal>PHP</literal> process.
|
||||
|
|
@ -48,8 +48,8 @@
|
|||
<refsect1 role="returnvalues">
|
||||
&reftitle.returnvalues;
|
||||
<para>
|
||||
Returns <literal>NULL</literal> if
|
||||
the PHP configuration directive
|
||||
Returns <literal>NULL</literal> if
|
||||
the PHP configuration directive
|
||||
<link linkend="ini.mysqlnd-ms.enable"><literal>mysqlnd_ms.enable</literal></link>
|
||||
has disabled the plugin. Otherwise, returns array of statistics.
|
||||
</para>
|
||||
|
|
@ -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
|
||||
<literal>use_slave</literal> + <literal>use_slave_sql_hint</literal> +
|
||||
<literal>use_slave_callback</literal>.
|
||||
</para>
|
||||
|
|
@ -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 <literal>use_slave</literal>, will be executed on the slaves.
|
||||
increments <literal>use_slave</literal>, will be executed on the slaves.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<literal>use_master</literal> + <literal>use_master_sql_hint</literal> +
|
||||
<literal>use_master_callback</literal>.
|
||||
</para>
|
||||
|
|
@ -228,10 +228,10 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of successfully opened slave connections from
|
||||
configurations not using
|
||||
configurations not using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
The total number of successfully opened slave connections
|
||||
is <literal>non_lazy_connections_slave_success</literal> +
|
||||
is <literal>non_lazy_connections_slave_success</literal> +
|
||||
<literal>lazy_connections_slave_success</literal>
|
||||
</entry>
|
||||
<entry>Since 1.0.0.</entry>
|
||||
|
|
@ -242,7 +242,7 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of failed slave connection attempts from
|
||||
configurations not using
|
||||
configurations not using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
The total number of failed slave connection attempts
|
||||
is <literal>non_lazy_connections_slave_failure</literal> +
|
||||
|
|
@ -256,10 +256,10 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of successfully opened master connections from
|
||||
configurations not using
|
||||
configurations not using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
The total number of successfully opened master connections
|
||||
is <literal>non_lazy_connections_master_success</literal> +
|
||||
is <literal>non_lazy_connections_master_success</literal> +
|
||||
<literal>lazy_connections_master_success</literal>
|
||||
</entry>
|
||||
<entry>Since 1.0.0.</entry>
|
||||
|
|
@ -270,7 +270,7 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of failed master connection attempts from
|
||||
configurations not using
|
||||
configurations not using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
The total number of failed master connection attempts
|
||||
is <literal>non_lazy_connections_master_failure</literal> +
|
||||
|
|
@ -284,7 +284,7 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of successfully opened slave connections from
|
||||
configurations using
|
||||
configurations using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
</entry>
|
||||
<entry>Since 1.0.0.</entry>
|
||||
|
|
@ -306,7 +306,7 @@
|
|||
</entry>
|
||||
<entry>
|
||||
Number of successfully opened master connections from
|
||||
configurations using
|
||||
configurations using
|
||||
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
||||
</entry>
|
||||
<entry>Since 1.0.0.</entry>
|
||||
|
|
@ -331,11 +331,11 @@
|
|||
This figure may be used to monitor activity related to the plugin configuration
|
||||
setting
|
||||
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness</literal></link>.
|
||||
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
|
||||
<literal>mysqlnd</literal> library function <literal>trx_autocommit()</literal>,
|
||||
which is a requirement for
|
||||
which is a requirement for
|
||||
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness</literal></link>,
|
||||
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 <literal>trx_autocommit()</literal>
|
||||
method.
|
||||
|
|
@ -356,7 +356,7 @@
|
|||
<literal>trx_master_forced</literal>
|
||||
</entry>
|
||||
<entry>
|
||||
Number of statemens redirected to the master while
|
||||
Number of statemens redirected to the master while
|
||||
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness=master</literal></link>
|
||||
and <literal>autocommit</literal> mode is disabled.
|
||||
</entry>
|
||||
|
|
@ -366,7 +366,7 @@
|
|||
</tgroup>
|
||||
</informaltable>
|
||||
</refsect1>
|
||||
|
||||
|
||||
<refsect1 role="examples">
|
||||
&reftitle.examples;
|
||||
<para>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<section xml:id="mysqlnd-ms.configuration" xmlns="http://docbook.org/ns/docbook">
|
||||
&reftitle.runtime;
|
||||
|
|
@ -101,7 +101,7 @@
|
|||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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
|
||||
<function>mysqlnd_ms_get_stats</function>.
|
||||
|
|
@ -116,8 +116,11 @@
|
|||
<listitem>
|
||||
<para>
|
||||
Enables or disables support of MySQL multi master replication setups.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
<chapter xml:id="mysqlnd-ms.quickstart" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Quickstart and Examples</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<section xml:id="mysqlnd-ms.quickstart.configuration">
|
||||
<title>Setup</title>
|
||||
<para>
|
||||
The plugin is implemented as a PHP extension.
|
||||
Please, follow the
|
||||
The plugin is implemented as a PHP extension.
|
||||
Please, follow the
|
||||
<link linkend="mysqlnd-ms.installation">installation instructions</link> to
|
||||
install the
|
||||
install the
|
||||
<link xlink:href="&url.pecl.package;mysqlnd_ms">PECL/mysqlnd_ms</link> extension.
|
||||
Then, load the extension into PHP and activate the plugin in the PHP configuration
|
||||
file using the PHP configuration directive named
|
||||
<link linkend="ini.mysqlnd-ms.enable">mysqlnd_ms.enable</link>.
|
||||
<link linkend="ini.mysqlnd-ms.enable">mysqlnd_ms.enable</link>.
|
||||
</para>
|
||||
<para>
|
||||
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
|
|||
</para>
|
||||
<para>
|
||||
Create a plugin-specific configuration file. Save the file to the path
|
||||
set by the PHP configuration directive
|
||||
set by the PHP configuration directive
|
||||
<link linkend="ini.mysqlnd-ms.ini-file">mysqlnd_ms.ini_file</link>.
|
||||
The plugin-specific file must be readable by PHP.
|
||||
</para>
|
||||
<para>
|
||||
The plugins configuration file is divided into one or more sections.
|
||||
Each section has a name, for example, <literal>myapp</literal>. Every section
|
||||
makes its own set of configuration settings.
|
||||
makes its own set of configuration settings.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<link linkend="ini.mysqlnd-ms-plugin-config.slave">slave[]</link>.
|
||||
A configuration section may contain no, one or multiple
|
||||
A configuration section may contain no, one or multiple
|
||||
<literal>slave[]</literal> directives to set no, one or multiple
|
||||
MySQL slaves.
|
||||
MySQL slaves.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
|
|
@ -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
|
||||
<link linkend="mysqlnd-ms.pooling">connection pooling and switching</link>,
|
||||
<link linkend="mysqlnd-ms.transaction">transaction handling</link>,
|
||||
<link linkend="mysqlnd-ms.failover">fail over</link>
|
||||
<link linkend="mysqlnd-ms.loadbalancing">load balancing</link> and
|
||||
<link linkend="mysqlnd-ms.failover">fail over</link>
|
||||
<link linkend="mysqlnd-ms.loadbalancing">load balancing</link> and
|
||||
<link linkend="mysqlnd-ms.rwsplit">read-write splitting</link> 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.
|
||||
</para>
|
||||
<para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
|
|
@ -135,23 +135,23 @@ slave[]=127.0.0.1:3306
|
|||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="mysqlnd-ms.quickstart.usage">
|
||||
<title>Running statements</title>
|
||||
<para>
|
||||
The plugin can be used with any PHP MySQL extension
|
||||
The plugin can be used with any PHP MySQL extension
|
||||
(<link linkend="ref.mysqli">mysqli</link>,
|
||||
<link linkend="ref.mysql">mysql</link>,
|
||||
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>)
|
||||
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>)
|
||||
compiled to use the <link linkend="book.mysqlnd">mysqlnd</link> library.
|
||||
PECL/mysqlnd_ms plugs into the <link linkend="book.mysqlnd">mysqlnd</link> library.
|
||||
It does not change the PHP MySQL extensions and their API.
|
||||
It does not change the PHP MySQL extensions and their API.
|
||||
</para>
|
||||
<para>
|
||||
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 <literal>myapp</literal>
|
||||
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 <literal>192.168.2.27</literal> and listening on port <literal>3306</literal>
|
||||
for MySQL client connection. All other statements will be directed to the
|
||||
MySQL master server running on the host <literal>localhost</literal> accepting
|
||||
MySQL master server running on the host <literal>localhost</literal> accepting
|
||||
MySQL client connection on the Unix domain socket <literal>/tmp/mysql.sock</literal>.
|
||||
The plugin will use the user name <literal>username</literal> and the password
|
||||
<literal>password</literal> to connect to any of the MySQL servers listed in
|
||||
the section <literal>myapp</literal> of the plugins configuration file. Upon
|
||||
connect, the plugin will select <literal>database</literal> as the current
|
||||
connect, the plugin will select <literal>database</literal> 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.
|
||||
</para>
|
||||
<para>
|
||||
The plugin does not change the API for running statements.
|
||||
The plugin does not change the API for running statements.
|
||||
<link linkend="mysqlnd-ms.rwsplit">Read-write splitting</link>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -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'
|
|||
]]>
|
||||
</screen>
|
||||
</example>
|
||||
</para>
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
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
|
||||
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>
|
||||
will be unaffected by this restriction because
|
||||
<link linkend="ref.pdo-mysql">PDO_MYSQL</link> is using a
|
||||
<link linkend="ref.pdo-mysql">PDO_MYSQL</link> is using a
|
||||
client-side prepared statement emulation by default.
|
||||
</para>
|
||||
</note>
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="mysqlnd-ms.quickstart.connectionpooling">
|
||||
<title>Connection state</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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
|
||||
<link linkend="mysqlnd-ms.pooling">connection pooling and switching</link>.
|
||||
|
|
@ -328,7 +328,7 @@ $mysqli->close();
|
|||
</example>
|
||||
</para>
|
||||
<para>
|
||||
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 <literal>SET @myrole='master'</literal> does not begin
|
||||
with the string <literal>SELECT</literal>. 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.
|
||||
</para>
|
||||
<para>
|
||||
The next statement is <literal>SELECT @myrole AS _role</literal>.
|
||||
The plugin does recognize it as a read-only query and sends it to
|
||||
The next statement is <literal>SELECT @myrole AS _role</literal>.
|
||||
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();
|
|||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
|
@ -355,7 +355,7 @@ $mysqli->close();
|
|||
The pitfalls can easily be worked around using SQL hints.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="mysqlnd-ms.quickstart.sqlhints">
|
||||
<title>SQL Hints</title>
|
||||
<para>
|
||||
|
|
@ -370,14 +370,14 @@ $mysqli->close();
|
|||
or a firewall.
|
||||
</para>
|
||||
<para>
|
||||
Three SQL hints are supported by the plugin:
|
||||
Three SQL hints are supported by the plugin:
|
||||
<constant>MYSQLND_MS_MASTER_SWITCH</constant>,
|
||||
<constant>MYSQLND_MS_SLAVE_SWITCH</constant> and
|
||||
<constant>MYSQLND_MS_LAST_USED_SWITCH</constant>.
|
||||
<constant>MYSQLND_MS_LAST_USED_SWITCH</constant>.
|
||||
<constant>MYSQLND_MS_MASTER_SWITCH</constant> makes the plugin run a statement
|
||||
on the master, <constant>MYSQLND_MS_SLAVE_SWITCH</constant> enforces the use
|
||||
of the slave and <constant>MYSQLND_MS_MASTER_SWITCH</constant> will run a
|
||||
statement on the same server that has been used for running the previous
|
||||
of the slave and <constant>MYSQLND_MS_MASTER_SWITCH</constant> will run a
|
||||
statement on the same server that has been used for running the previous
|
||||
statement.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -434,8 +434,8 @@ $mysqli->close();
|
|||
</example>
|
||||
</para>
|
||||
<para>
|
||||
In the example the session variables issue from the previous page is solved
|
||||
using <constant>MYSQLND_MS_LAST_USED_SWITCH</constant> to prevent switching
|
||||
In the example the session variables issue from the previous page is solved
|
||||
using <constant>MYSQLND_MS_LAST_USED_SWITCH</constant> to prevent switching
|
||||
from the master to a slave when running the <literal>SELECT</literal> statement.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -460,14 +460,14 @@ if (!$mysqli->query(sprintf("/*%s*/SELECT critical_data FROM important_table", M
|
|||
}
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
use case may include the creation of tables on a slave.
|
||||
If no SQL hint is given, the plugin will send <literal>CREATE</literal>
|
||||
and <literal>INSERT</literal> statements to the master. Use the
|
||||
SQL hint <constant>MYSQLND_MS_SLAVE_SWITCH</constant> if you want to
|
||||
SQL hint <constant>MYSQLND_MS_SLAVE_SWITCH</constant> if you want to
|
||||
run any such statement on a slave, for example, to build temporary
|
||||
reporting tables.
|
||||
</para>
|
||||
|
|
@ -501,23 +501,23 @@ if ($res = $mysqli->query(sprintf("/*%s*/SELECT COUNT(*) AS _num FROM slave_repo
|
|||
$mysqli->close();
|
||||
?>
|
||||
]]>
|
||||
</programlisting>
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
<para>
|
||||
The SQL hint <constant>MYSQLND_MS_LAST_USED</constant> forbids switching
|
||||
connection and forces the use of the previously used connection.
|
||||
connection and forces the use of the previously used connection.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
|
||||
<section xml:id="mysqlnd-ms.quickstart.transactions">
|
||||
<title>Transactions</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
|
|
@ -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();
|
|||
</para>
|
||||
<para>
|
||||
If using PHP 5.4.0 or newer, API calls to set the <literal>autocommit</literal> mode
|
||||
and setting the experimental plugin configuration option
|
||||
and setting the experimental plugin configuration option
|
||||
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness=master</literal></link>
|
||||
the plugin can automatically disable load balancing and connection switches
|
||||
for SQL transactions. In this configuration the plugin stops load balancing,
|
||||
if <literal>autocommit</literal> is disabled and directs all statements to
|
||||
the master. This is done to prevent connection switches in the middle of
|
||||
a transaction. Once <literal>autocommit</literal> gets enabled again, the plugin
|
||||
starts to load balance statements again.
|
||||
starts to load balance statements again.
|
||||
</para>
|
||||
<para>
|
||||
<example>
|
||||
|
|
@ -620,7 +620,7 @@ trx_stickiness=master
|
|||
<?php
|
||||
if (version_compare(PHP_VERSION, "5.3.99", "<"))
|
||||
die("This feature requires PHP 5.3.99, you are using " . PHP_VERSION);
|
||||
|
||||
|
||||
$mysqli = new mysqli("myapp", "username", "password", "database");
|
||||
if (!$mysqli)
|
||||
/* Of course, your error handling is nicer... */
|
||||
|
|
@ -629,9 +629,9 @@ if (!$mysqli)
|
|||
/* Disable autocommit, plugin will run all statements on the master */
|
||||
$mysqli->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));
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
|
||||
<reference xml:id="ref.mysqlnd-ms" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<title>Mysqlnd_ms &Functions;</title>
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- $Revision$ -->
|
||||
<!-- $Revision$ -->
|
||||
<!--
|
||||
Do NOT translate this file
|
||||
-->
|
||||
|
|
|
|||
Loading…
Reference in a new issue