From 7327d8a18429f423dd5bc5a6f39075e82e7e118c Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Tue, 27 Sep 2011 11:25:28 +0000 Subject: [PATCH] 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 --- reference/mysqlnd_ms/concepts.xml | 252 ++++++++++++++++++++++++++---- 1 file changed, 224 insertions(+), 28 deletions(-) diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml index 5dd0152105..2b062af214 100755 --- a/reference/mysqlnd_ms/concepts.xml +++ b/reference/mysqlnd_ms/concepts.xml @@ -3,13 +3,25 @@ Concepts + + 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. + + + 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. +
Architecture - 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 mysqlnd plugin to replace selected mysqlnd C methods. @@ -41,7 +53,7 @@ connections, such as when using BEGIN TRANSACTION, the plugin leaves it to the user to handle. Please, find further details below. - +
@@ -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. @@ -264,10 +276,10 @@ The plugin does not proxy or remember all settings to apply them on connections opened in the future. This is important to remember, if - using + using lazy connections. - 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. @@ -324,7 +336,7 @@ Adds SET AUTOCOMMIT=0|1 to the list of init commands of a lazy connection using - set_client_option(MYSQL_INIT_COMMAND, "SET AUTOCOMMIT=...%quot;). + set_client_option(MYSQL_INIT_COMMAND, "SET AUTOCOMMIT=...%quot;). Since 1.1.0. PHP >= 5.4.0. @@ -349,8 +361,8 @@ 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. At the time of writing, applications using SQL transactions together with @@ -373,14 +385,14 @@ PDO::setAttribute(PDO::ATTR_AUTOCOMMIT) user API calls. - The experimental pluging configuration option - trx_stickiness=master can be used to make the plugin + The experimental pluging configuration option + trx_stickiness=master 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.
- +
Failover @@ -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. - 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. The failover policy is configured in the plugins configuration file by help - of the + of the failover configuration directive.
- +
Load balancing Four load balancing strategies are supported to distribute read-only - statements over the configured MySQL slave servers: + statements over the configured MySQL slave servers: random, random_once (default), roundrobin, user. - 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 pick[] configuration directive.
- +
Read-write splitting @@ -444,14 +456,14 @@ running the previous query and the query starts with the SQL hint /*ms=last_used*/. In all other cases the query will be send to the MySQL replication master server. - + 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 constants - 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. @@ -465,15 +477,199 @@ - 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 SELECT 1 FROM DUAL; INSERT INTO test(id) VALUES (1); ... the plugin will run it on a slave although the statement is not read-only. - +
+ +
+ Filter + + + + The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta. + It is not valid for earlier versions. + + + + PECL/mysqlnd 1.1.0-beta introduces the concept of + filters. + 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. + + + 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. + + + The following filters are available with version 1.1.0-beta. + + + + Load balancing filter: + random, + roundrobin. + + + + + Selection filter: + user. + + + + + + The random and roundrobin + filters replace the + pick[] + configuration directive found in earlier versions. The random + filter implementes the random and random once load balancing policies. + Round robin load balancing can be configured through the + roundrobin filter. Setting a user defined callbacks for server + selection is possible with the user filter. The + + mysqlnd_ms_set_user_pick_server function previously + used for this has been removed. + + + Filters can accept parameters to change their behaviour. + The random filter accepts an optional + sticky 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. + + + 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. + + + A filter sequence of not much value: + + + + Statement to be excuted: SELECT 1 FROM DUAL. Passed to all filters. + + + + + All configured nodes are passed as input to the first filter. + Master nodes: master_0. + Slave nodes:slave_0, slave_1 + + + + + Filter: random, argument sticky=1. + Picks a random slave once to be used for the rest of the PHP request. + Output: slave_0. + + + + + Output of slave_0 and the statement to be executed + is passed as input to the next filter. Here: roundrobin, + server list passed to filter is: slave_0. + + + + + Filter: roundrobin. Server list consists of + one server only, round robin will always return the same server. + + + + If trying to use such a filter sequence, + the plugin may emit a warning like (mysqlnd_ms) Error while creating + filter '%s' . Non-multi filter '%s' already created. Stopping in %s on + line %d. Furthermode an appropriate error on the connection handle + may be set. + + + In future versions there may be filters which return more than one candidate + for statement execution. For example, there may be a table + 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 (slave_0, slave_1, + slave_2, slave_3) two of which replicate a database named + sales (slave_0, slave_1). + If the application queries the database.slaves the + hypothetical table filter reduces the list of possible + servers to slave_0, slave_1. 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. + + + A hypothetical filter sequence, assuming the existance of a table + filter to support MySQL Replication filtering (client-side partitioning). + + + + Statement to be excuted: SELECT col FROM sales.reports. Passed to all filters. + + + + + All configured nodes are passed as input to the first filter. + Master nodes: master_0. + Slave nodes: slave_0, slave_1, + slave_2, slave_3 + + + + + Filter: table, rules set for database sales. + Output: slave_0, slave_1. + + + + + Output of slave_0, slave_1 + and the statement to be executed + is passed as input to the next filter, which is roundrobin. + + + + + Filter: roundrobin. Server list consists of + two servers. Round robin selectes slave_0. + Upon subsequent execution, if the same server list is given as + input, the filter will return slave_1 followed + by slave_0, slave_1, + slave_0 and so forth. + + + + + + The example aims to illustrate the strength of the filter + concept. It does not make any promises on future features. + + + +
+