[prev in list] [next in list] [prev in thread] [next in thread]
List: php-doc-cvs
Subject: [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/mysqlnd=5Fms/_concepts.xml?=
From: Ulf_Wendel <uw () php ! net>
Date: 2011-09-27 11:25:28
Message-ID: svn-uw-1317122728-317391-79341057 () svn ! php ! net
[Download RAW message or body]
uw Tue, 27 Sep 2011 11:25:28 +0000
Revision: http://svn.php.net/viewvc?view=revision&revision=317391
Log:
Description of filter concept. Filter syntax and new plugin config file syntax got \
documented yesterday, A bit of end of line whitespace removal.
Changed paths:
U phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml
["svn-diffs-317391.txt" (text/x-diff)]
Modified: phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml
===================================================================
--- phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml 2011-09-27 11:23:49 UTC (rev \
317390)
+++ phpdoc/en/trunk/reference/mysqlnd_ms/concepts.xml 2011-09-27 11:25:28 UTC (rev \
317391) @@ -3,13 +3,25 @@
<chapter xml:id="mysqlnd-ms.concepts" xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Concepts</title>
+ <para>
+ The concept section explains the overall architecture and important concepts
+ of the plugin. The materials aim to help you understanding the impact of
+ MySQL replication and using the plugin for your development tasks.
+ Any application using MySQL Replication must take care of certain tasks that
+ arise from using a database cluster.
+ </para>
+ <para>
+ It is strongly recommended to work through the materials in order to
+ be able to use the plugin with success. This is particulary true, if you are
+ new to using MySQL Replication.
+ </para>
<section xml:id="mysqlnd-ms.architecture">
<title>Architecture</title>
<para>
- The mysqlnd replication and load balancing plugin is
+ The mysqlnd replication and load balancing 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 init phase of the
+ startup of the PHP interpreter, in the module init phase of the
PHP engine, it gets registered as a
<link linkend="book.mysqlnd">mysqlnd</link> plugin to replace selected
mysqlnd C methods.
@@ -41,7 +53,7 @@
connections, such as when using <literal>BEGIN TRANSACTION</literal>, the
plugin leaves it to the user to handle. Please, find further details below.
</para>
-
+
</section>
<section xml:id="mysqlnd-ms.pooling">
@@ -72,7 +84,7 @@
At some point in time one and the same PHP connection handle
may point to the MySQL master server. Later on, it may point
to one of the slave servers or still the master. Manipulating
- and replacing the wire connection referenced by a PHP MySQL
+ and replacing the wire connection referenced by a PHP MySQL
connection handle is not a transparent operation.
</para>
<para>
@@ -264,10 +276,10 @@
The plugin does not proxy or
<quote>remember</quote> all settings to apply them on connections
opened in the future. This is important to remember, if
- using
+ using
<link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy \
connections</link>.
- Lazy connections are connections which are not
- opened before the client sends the first connection.
+ Lazy connections are connections which are not
+ opened before the client sends the first connection.
Use of lazy connections is the default plugin action.
</para>
<para>
@@ -324,7 +336,7 @@
<entry>
Adds <literal>SET AUTOCOMMIT=0|1</literal> to the list of init commands
of a lazy connection using
- <literal>set_client_option(MYSQL_INIT_COMMAND, "SET \
AUTOCOMMIT=...%quot;)</literal>. + \
<literal>set_client_option(MYSQL_INIT_COMMAND, "SET \
AUTOCOMMIT=...%quot;)</literal>. </entry>
<entry>Since 1.1.0. PHP >= 5.4.0.</entry>
</row>
@@ -349,8 +361,8 @@
<para>
By default the plugin is not aware of SQL transactions. The plugin may
switch connections for load balancing at any point in time. Connection
- switches may happen in the middle of a transaction. This is against the
- nature of a SQL transaction. By default the plugin is not transaction safe.
+ switches may happen in the middle of a transaction. This is against the
+ nature of a SQL transaction. By default the plugin is not transaction safe.
</para>
<para>
At the time of writing, applications using SQL transactions together with
@@ -373,14 +385,14 @@
<function>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)</function> user API calls.
</para>
<para>
- The experimental pluging configuration option
- <literal>trx_stickiness=master</literal> can be used to make the plugin
+ The experimental pluging configuration option
+ <literal>trx_stickiness=master</literal> can be used to make the plugin
transaction aware if using PHP 5.4.0 or newer. In this mode the plugin stops \
load
balancing if autocommit gets disabled and directs all statements to the
master until autocommit gets enabled.
</para>
</section>
-
+
<section xml:id="mysqlnd-ms.failover">
<title>Failover</title>
<para>
@@ -399,41 +411,41 @@
cannot ensure that an automatic failover will not change the state of
the connection. For example, the application may have issued a query
which depends on SQL user variables which are bound to a specific connection.
- Such a query might return wrong results if the plugin would switch the
+ Such a query might return wrong results if the plugin would switch the
connection implicitly as part of automatic failover. To ensure correct
results the application must take care of the failover and rebuild
the required connection state. Therefore, by default, no automatic failover
is done by the plugin.
</para>
<para>
- An user who does not change the connection state after opening a connection
+ An user who does not change the connection state after opening a connection
may activate automatic master failover.
</para>
<para>
The failover policy is configured in the plugins configuration file by help
- of the
+ of the
<literal><link linkend="ini.mysqlnd-ms-plugin-config.failover">failover</link></literal>
configuration directive.
</para>
</section>
-
+
<section xml:id="mysqlnd-ms.loadbalancing">
<title>Load balancing</title>
<para>
Four load balancing strategies are supported to distribute read-only
- statements over the configured MySQL slave servers:
+ statements over the configured MySQL slave servers:
<literal>random</literal>, <literal>random_once</literal> (default),
<literal>roundrobin</literal>, <literal>user</literal>.
</para>
<para>
- The load balancing policy is configured in the plugins configuration
- file using the
+ The load balancing policy is configured in the plugins configuration
+ file using the
<link linkend="ini.mysqlnd-ms-plugin-config.pick">pick[]</link>
configuration directive.
</para>
</section>
-
+
<section xml:id="mysqlnd-ms.rwsplit">
<title>Read-write splitting</title>
<para>
@@ -444,14 +456,14 @@
running the previous query and the query starts with the SQL hint
<literal>/*ms=last_used*/</literal>. In all other cases the query will
be send to the MySQL replication master server.
- </para>
+ </para>
<para>
SQL hints are a special kind of standard compliant SQL comments. The plugin
does check every statement for certain SQL hints. The SQL hints are described
together with the <link linkend="mysqlnd-ms.constants">constants</link>
- exported by the extension. Other systems
+ exported by the extension. Other systems
involved in the statement processing, such as the MySQL server, SQL firewalls
- or SQL proxies are unaffected by the SQL hints because those systems are
+ or SQL proxies are unaffected by the SQL hints because those systems are
supposed to ignore SQL comments.
</para>
<para>
@@ -465,15 +477,199 @@
</para>
<note>
<para>
- The built-in read-write splitter is not aware of multi-statements.
- Multi-statements are seen as one statement. The splitter will check the
+ The built-in read-write splitter is not aware of multi-statements.
+ Multi-statements are seen as one statement. The splitter will check the
beginning of the statement to decide where to run the statement. If, for \
example,
- a multi-statement begins with
+ a multi-statement begins with
<literal>SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ...</literal>
the plugin will run it on a slave although the statement is not read-only.
</para>
- </note>
+ </note>
</section>
+
+<section xml:id="mysqlnd-ms.filter">
+ <title>Filter</title>
+
+ <note>
+ <para>
+ The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta.
+ It is not valid for earlier versions.
+ </para>
+ </note>
+ <para>
+ PECL/mysqlnd 1.1.0-beta introduces the concept of
+ <link linkend="mysqlnd-ms.plugin-ini-json">filters</link>.
+ Any PHP application using any kind of MySQL replication cluster first needs to \
identify + a group of servers in the cluster which could execute a given statement \
before + the statement is executed on one of the candidates. In other words: a \
given + list of servers has to be filtered until one server is left.
+ </para>
+ <para>
+ The process of filtering may include the use one or more filters. Filters can be
+ chained. They are executed in the order of their appearance in the plugins
+ configuration file. The concept of chained filters can be compared to using
+ pipes to connect command line utitilies on an operating system command shell: an \
input stream + is passed to a processor, filtered and transferred to be output.
+ Then the output is passed as input to the next command which is connected
+ to the previous using the pipe operator.
+ </para>
+ <para>
+ The following filters are available with version 1.1.0-beta.
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Load balancing filter:
+ <link linkend="ini.mysqlnd-ms-plugin-config-v2.filters"><literal>random</literal></link>,
+ <link linkend="ini.mysqlnd-ms-plugin-config-v2.filters"><literal>roundrobin</literal></link>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Selection filter:
+ <link linkend="ini.mysqlnd-ms-plugin-config-v2.filters"><literal>user</literal></link>.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The <literal>random</literal> and <literal>roundrobin</literal>
+ filters replace the
+ <link linkend="ini.mysqlnd-ms-plugin-config.pick"><literal>pick[]</literal></link>
+ configuration directive found in earlier versions. The <literal>random</literal>
+ filter implementes the random and random once load balancing policies.
+ Round robin load balancing can be configured through the
+ <literal>roundrobin</literal> filter. Setting a user defined callbacks for server
+ selection is possible with the <literal>user</literal> filter. The
+ <link linkend="function.mysqlnd-ms-set-user-pick-server">
+ <function>mysqlnd_ms_set_user_pick_server</function></link> function previously
+ used for this has been removed.
+ </para>
+ <para>
+ Filters can accept parameters to change their behaviour.
+ The <literal>random</literal> filter accepts an optional
+ <literal>sticky</literal> parameter. If set to true, the filter chnages
+ load balancing from random to random once. Random picks a random server
+ every time a statement is to be executed. Random once picks a random
+ server when the first statement is to be executed and uses the same
+ server for the rest of the PHP request.
+ </para>
+ <para>
+ One of the biggest strength of the filter concept is the possibility to
+ chain filters. This strength coes not become immediately visible with the
+ filters provided by version 1.1.0-beta because all of the above filters
+ are supposed to output no more than one server. If a filter reduces
+ the list of candidates for running a statement to only one server, it
+ makes little sense to use that one server as input for another filter for
+ further reduction of the list of candidates.
+ </para>
+ <para>
+ A filter sequence of not much value:
+ <itemizedlist>
+ <listitem>
+ <simpara>
+ Statement to be excuted: <literal>SELECT 1 FROM DUAL</literal>. Passed to all \
filters. + </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ All configured nodes are passed as input to the first filter.
+ Master nodes: <literal>master_0</literal>.
+ Slave nodes:<literal>slave_0</literal>, <literal>slave_1</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Filter: <literal>random</literal>, argument <literal>sticky=1</literal>.
+ Picks a random slave once to be used for the rest of the PHP request.
+ Output: <literal>slave_0</literal>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Output of <literal>slave_0</literal> and the statement to be executed
+ is passed as input to the next filter. Here: <literal>roundrobin</literal>,
+ server list passed to filter is: <literal>slave_0</literal>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Filter: <literal>roundrobin</literal>. Server list consists of
+ one server only, round robin will always return the same server.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ If trying to use such a filter sequence,
+ the plugin may emit a warning like <literal>(mysqlnd_ms) Error while creating
+ filter '%s' . Non-multi filter '%s' already created. Stopping in %s on
+ line %d</literal>. Furthermode an appropriate error on the connection handle
+ may be set.
+ </para>
+ <para>
+ In future versions there may be filters which return more than one candidate
+ for statement execution. For example, there may be a <literal>table</literal>
+ filter to support MySQL Replication filtering. MySQL replication filter allow
+ you to define rules which database or table is to be replicated to which
+ node of a replication cluster. Assume your replication cluster
+ consists of four slaves (<literal>slave_0</literal>, <literal>slave_1</literal>,
+ <literal>slave_2</literal>, <literal>slave_3</literal>) two of which replicate a \
database named + <literal>sales</literal> (<literal>slave_0</literal>, \
<literal>slave_1</literal>). + If the application queries the \
database.<literal>slaves</literal> the + hypothetical <literal>table</literal> \
filter reduces the list of possible + servers to <literal>slave_0</literal>, \
<literal>slave_1</literal>. Because + the output and list of candidates consists of \
more than one server, it is + necessary and possible to further filter the \
candidate list, for example, using + a load balancing filter to identiy a server \
for statement execution. + </para>
+ <para>
+ A hypothetical filter sequence, assuming the existance of a \
<literal>table</literal> + filter to support MySQL Replication filtering \
(client-side partitioning). + <itemizedlist>
+ <listitem>
+ <simpara>
+ Statement to be excuted: <literal>SELECT col FROM sales.reports</literal>. \
Passed to all filters. + </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ All configured nodes are passed as input to the first filter.
+ Master nodes: <literal>master_0</literal>.
+ Slave nodes: <literal>slave_0</literal>, <literal>slave_1</literal>,
+ <literal>slave_2</literal>, <literal>slave_3</literal>
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Filter: <literal>table</literal>, rules set for database \
<literal>sales</literal>. + Output: <literal>slave_0</literal>, \
<literal>slave_1</literal>. + </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Output of <literal>slave_0</literal>, <literal>slave_1</literal>
+ and the statement to be executed
+ is passed as input to the next filter, which is <literal>roundrobin</literal>.
+ </simpara>
+ </listitem>
+ <listitem>
+ <simpara>
+ Filter: <literal>roundrobin</literal>. Server list consists of
+ two servers. Round robin selectes <literal>slave_0</literal>.
+ Upon subsequent execution, if the same server list is given as
+ input, the filter will return <literal>slave_1</literal> followed
+ by <literal>slave_0</literal>, <literal>slave_1</literal>,
+ <literal>slave_0</literal> and so forth.
+ </simpara>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ The example aims to illustrate the strength of the filter
+ concept. It does not make any promises on future features.
+ </para>
+ </note>
+ </para>
+ </section>
+
</chapter>
<!-- Keep this comment at the end of the file
--
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic