mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
Description of filter concept. Filter syntax and new plugin config file syntax got documented yesterday, A bit of end of line whitespace removal.
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317391 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel
parent
ee3ee7bf44
commit
7327d8a184
1 changed files with 224 additions and 28 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue