From d77e6a996a71ef057c9e17da136eed237698dc64 Mon Sep 17 00:00:00 2001 From: Ulf Wendel Date: Mon, 26 Sep 2011 19:48:32 +0000 Subject: [PATCH] Coverage for new plugin configuration file syntax, which is introduced by 1.1.0-beta. Next is updating all examples in the rest of the mysqlnd_ms manual. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317342 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_ms/setup.xml | 865 ++++++++++++++++++++++++++++++++- 1 file changed, 861 insertions(+), 4 deletions(-) diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml index f8bfcadaa5..3e20f3bd3b 100755 --- a/reference/mysqlnd_ms/setup.xml +++ b/reference/mysqlnd_ms/setup.xml @@ -25,8 +25,865 @@ &reference.mysqlnd-ms.configure; &reference.mysqlnd-ms.ini; -
- Plugin configuration file +
+ Plugin configuration file (>=1.1.x) + + + The below description applies to PECL/mysqlnd_ms >= 1.1.0-beta. + It is not valid for prior versions. + + + + The plugin is using its own configuration file. The configuration file + holds information on the MySQL replication master server, + the MySQL replication slave servers, the server pick (load balancing) policy, + the failover strategy and the use of lazy connections. + + + The PHP configuration directive + mysqlnd_ms.ini_file + is used to set the plugins configuration file. + + + As of mysqlnd 1.1.0-beta JSON format is used + for the plugins configuration file. JSON structures + are fast to parse by the plugin, thanks PHPs JSON support. + The JSON format makes it easy to define hierarchical + data structures. Hierachical data structures are used, for example, + to allow definition of chained filters. Expressing hierarchical data structures + with the standard php.ini format is much more inconvenient. + + + If you are unfamiliar with the JSON you may want to convert + the configuration file into a PHP hash, edit the hash and convert it back + to JSON format. + + + + Converting a PHP hash into JSON format + + array( + "master" => array( + "master_0" => array( + "host" => "localhost", + "socket" => "/tmp/mysql.sock", + ), + ), + "slave" => array(), + ), +); + +file_put_contents("mysqlnd_ms.ini", json_encode($config, JSON_PRETTY_PRINT)); +printf("mysqlnd_ms.ini file created...\n"); +printf("Dumping file contents...\n"); +printf("%s\n", str_repeat("-", 80)); +echo file_get_contents("mysqlnd_ms.ini"); +printf("\n%s\n", str_repeat("-", 80)); +?> +]]> + + &example.outputs; + + + + + + + A plugin configuration file consists of one or more sections. Sections + are represented by the top-level object properties of the + object encoded in the JSON file. Sections could also + be called configuration names. + + + Applications reference sections by their name. Applications use section names + as the host (server) parameter to the various connect methods of the + mysqli, + mysql and + PDO_MYSQL extensions. Upon connect + the mysqlnd plugin compares the hostname + with all section names from the plugin configuration file. If hostname and + section name match, the plugin will load the sections settings. + + + + Using section names example + + + + + +]]> + + + + + Section names are strings. It is valid to use a section name such as + 192.168.2.1, 127.0.0.1 or + localhost. If, for example, an application + connects to localhost and a plugin + configuration section localhost exists, the + semantics of the connect operation are changed. The application will + no longer only use the MySQL server running on the host + localhost but the plugin will start to load balance + MySQL queries following the rules from the localhost + configuration section. This way you can load balance queries from + an application without changing the applications source code. + + + Each configuration section contains at least a list of master servers + and a list of slave servers. The master list is configured with the keyword + master, the slave list is configured with the slave + Failing to provide a slave list will result in an error of type + E_ERROR (fatal error). Although you are not allowed + to omit the slave list, it may be empty. + + + The master and slave server lists can be optionally indexed by symbolic + names for the servers they describe. If optional indexing entries + by symbolic names is not needed, use an array of server descriptions for + the slave or master that is to be described. + + List of anonymous slaves + + + + + An anonymous server list is encoded by the JSON array type. + You can optionally use symbolic names for indexing the slave or master servers + of a server list. In the latter case you have to use the + JSON object type. + + Master list using symbolic names + + + + + It is recommended to index the server lists with symbolic server names. + The alias names will be shown in error messages. + + + The order of servers is preserved and taken into account by mysqlnd_ms. + If, for example, you configure round robin load balancing strategy, the + first SELECT statement will be executed on the + slave that appears first in the slave server list. + + + A configured server can be described with the host, + port, socket, db, + user, password and connect_flags. + It is mandatory to set the database server host using the host + keyword. All other settings are optional. + + Keywords to configure a server + + + + + If a setting is omitted, the plugin will use the value provided by the user + API call used to open a connection. Please, see the + using section names example above. + + + The configuration file format has been changed in version 1.1.0-beta to allow for + chained filters. Filters are responsible for filtering the configured list of + servers to identify a server for execution of a given statement. + Filters are configured with the filter keyword. Filters + are executed by mysqlnd_ms in the order of their appearance. + Defining filters is optional. A configuration section in the plugins + configuration file does not need to have a filters entry. + + + Filters replace the + pick[] + setting from prior versions. The new random and + roundrobin provide the same functionality. + + New <literal>roundrobin</literal> filter, old functionality + + + + + The function + + mysqlnd_ms_set_user_pick_server + has been removed. Setting a callback is now done with the user + filter. Some filters accept parameters. The user filter + requires and accepts a mandatory callback parameter + to set the callback previously set through the function mysqlnd_ms_set_user_pick_server. + + The <literal>user</literal> filter replaces <function>mysqlnd_ms_set_user_pick_server</function> + + + + + + + Here is a short explanation of the configuration directives that can be used. + + + + + + master + array or object + + + + List of MySQL replication master servers. The list of either + of the JSON type array to declare an anonymous list + of servers or of the JSON type object. Please, + see above + for examples. + + + Setting at least one master server is mandatory. The plugin will issue an + error of type E_ERROR if the user has failed to + provide a master server list for a configuration section. + The fatal error may read + (mysqlnd_ms) Section [master] doesn't exist for host + [name_of_a_config_section] in %s on line %d. + + + A server is described with + the host, port, + socket, db, + user, password and + connect_flags. It is mandatory to + provide at a value for host. If any of the + other values is not given, it will be taken from the user + API connect call, please, see also: + using section names example. + + + Table of server configuration keywords. + + + + + + + + + Keyword + Description + Version + + + + + + host + + + + Database server host. This is a mandatory setting. + Failing to provide, will cause an error of type E_RECOVERABLE_ERROR + when the plugin tries to connect to the server. The error message may + read (mysqlnd_ms) Cannot find [host] in + [%s] section in config in %s on line %d. + + + Since 1.1.0. + + + + port + + + + Database server TCP/IP port. + + + Since 1.1.0. + + + + socket + + + + Database server Unix domain socket. + + + Since 1.1.0. + + + + db + + + + Database (schemata). + + + Since 1.1.0. + + + + user + + + + MySQL database user. + + + Since 1.1.0. + + + + password + + + + MySQL database user password. + + + Since 1.1.0. + + + + connect_flags + + + + Connection flags. + + + Since 1.1.0. + + + + + + The plugin supports using only one master server. An experimental + setting exists to enable multi-master support. The details are + not documented. The setting is meant for development only. + + + + + + slave + array or object + + + + List of one or more MySQL replication slave servers. The syntax is + identical to setting master servers, please, see + master + above for details. + + + The plugin supports using one or more slave servers. + + + Setting a list of slave servers is mandatory. The plugin will report + an error of the type E_ERROR if slave + is not given for a configuration section. The fatal error message may read + (mysqlnd_ms) Section [slave] doesn't exist for host [%s] in %s on line %d. + Note, that it is valid to use an empty slave server list. + The error has been introduced to prevent accidently setting no slaves by + forgetting about the slave setting. + A master-only setup is still possible using an empty slave server list. + + + + + + filters + object + + + + List of filters. A filter is responsible to filter the list of available + servers for executing a given statement. Filters can be chained. + The random and roundrobin filter + replace the + pick[] + directive used in prior version to select a load balancing policy. + The user filter replaces the + + mysqlnd_ms_set_user_pick_server function + + + Filters may accept parameters to refine their actions. + + + If no load balancing policy is set, the plugin will default to + random_once. The random_once + policy picks a random slave server when running the first read-only + statement. The slave server will be used for all read-only + statements until the PHP script execution ends. No load balancing + policy is set and thus, defaulting takes place, + if neither the random nor the + roundrobin are part of a configuration section. + + + + + + Filter: random + object + + + + The random filter features the load balancing policies + random and random_once, previously set + through the + pick[] + directive in older versions. + + + The random policy will pick a random server whenever + a read-only statement is to be executed. The random_once + picks a random slave server once and continues using the slave for the + rest of the PHP web request. random_once is a default, + if load balancing is not configured through a filter. + + + If the random filter is not given any arguments, it + stands for random load balancing policy. + + <literal>random</literal> load balancing policy + + + + + Optionally, the sticky argument can be passed to the + filter. If the parameter sticky is set to the string + 1, the filter provides the random_once + load balancing policy. + + <literal>random_once</literal> load balancing policy + + + + + Unknown arguments are ignored. No warning or error is given. + + + + + + Filter: roundrobin + object + + + + If using roundrobin the plugin iterates over the list of + configured slave servers to pick a server for statement execution. + If the plugin reaches the end of the list, it wraps around to the beginning + of the list and picks the first configured slave server. + + + + + + failover + string + + + + Failover policy. Supported policies: + disabled (default), master. + + + If no failover policy is set, the plugin will not do any + automatic failover (failover=disabled). Whenever + the plugin fails to connect a server it will emit a warning and + set the connections error code and message. Thereafter it is up to + the application to handle the error and, for example, resent the + last statement to trigger the selection of another server. + + + If using failover=master the plugin will implicitly + failover to a slave, if available. Please check the + concepts documentation to learn about potential + pitfalls and risks of using failover=master. + + Optional master failover when failing to connect to slave + + + + + + + Setting failover to any other value but + disabled or master will not + emit any warning or error. + + + + + + lazy_connections + bool + + + + Controls the use of lazy connections. Lazy connections + are connections which are not opened before the client sends the first + connection. Lazy connections are a default. + + + It is strongly recommended to use lazy connections. + Lazy connections help to keep the number of open connections low. + If you disable lazy connections and, for example, configure one MySQL + replication master server and two MySQL replication slaves, the + plugin will open three connections upon the first call to a + connect function although the application might use the master + connection only. + + + Lazy connections bare a risk if you make heavy use of actions + which change the state of a connection. The plugin does not dispatch + all state changing actions to all connections from the connection pool. + The few dispatched actions are applied to already opened connections + only. Lazy connections opened in the future are not affected. + Only some settings are "remembered" and applied when lazy + connections are opened. + + Disabling lazy connection + + + + + + + + + + master_on_write + bool + + + + If set, the plugin will use the master server only after the + first statement has been executed on the master. Applications + can still send statements to the slaves using SQL hints to + overrule the automatic decision. + + + The setting may help with replication lag. If an application runs + an INSERT the plugin will, by default, use the + master to execute all following statements, including + SELECT statements. This helps to avoid problems + with reads from slaves which have not replicated the + INSERT yet. + + Master on write for consistent reads + + + + + + + + + + trx_stickiness + string + + + + Transaction stickiness policy. Supported policies: + disabled (default), master. + + + Experimental feature. + + + The setting requires 5.4.0 or newer. If used with PHP older than 5.4.0, + the plugin will emit a warning like + (mysqlnd_ms) trx_stickiness strategy is not supported before PHP 5.3.99. + + + If no transaction stickiness policy is set or, + if setting trx_stickiness=disabled, + the plugin is not transaction aware. Thus, the plugin may load balance + connections and switch connections in the middle of a transaction. + The plugin is not transaction safe. SQL hints must be used + avoid connection switches during a transaction. + + + As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor + the autocommit mode set by calls to the + libraries set_autocommit() function. + If setting set_stickiness=master and + autocommit gets disabled by a PHP MySQL extension + invoking the mysqlnd library internal + function call set_autocommit(), the plugin is made + aware of the begin of a transaction. Then, the plugin stops load balancing + and directs all statements to the master server until + autocommit is enabled. Thus, no SQL hints are required. + + + An example of a PHP MySQL API function calling the mysqlnd + library internal function call set_autocommit() is + mysqli_autocommit. + + + Although setting ser_stickiness=master, the plugin + cannot be made aware of autocommit mode changes caused + by SQL statements such as SET AUTOCOMMIT=0. + + Using master to execute transactions + + + + + + + + + +
+ +
+ Plugin configuration file (<= 1.0.x) + + + The below description applies to PECL/mysqlnd_ms < 1.1.0-beta. + It is not valid for later versions. + + The plugin is using its own configuration file. The configuration file holds information on the MySQL replication master server, @@ -37,7 +894,7 @@ The PHP configuration directive mysqlnd_ms.ini_file is used to set the plugins configuration file. - + The configuration file mimics standard the php.ini format. It consists of one or more sections. Every section defines its own unit @@ -328,7 +1185,7 @@ slave[] = mysql_slave_2 avoid connection switches during a transaction. - As of PHP 5.4.ß the mysqlnd library allows the plugin to monitor + As of PHP 5.4.0 the mysqlnd library allows the plugin to monitor the autocommit mode set by calls to the libraries trx_autocommit() function. If setting trx_stickiness=master and