svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ changes.xml setup.xml

From: Date: Tue, 11 Mar 2014 14:50:29 +0000
Subject: svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ changes.xml setup.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-12191@lists.php.net to get a copy of this message
uw Tue, 11 Mar 2014 14:50:29 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=332953 Log: Document Fabric related MS config file settings Changed paths: U phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml U phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml Modified: phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2014-03-11 14:46:05 UTC (rev 332952) +++ phpdoc/en/trunk/reference/mysqlnd_ms/changes.xml 2014-03-11 14:50:29 UTC (rev 332953) @@ -103,8 +103,8 @@ </listitem> <listitem> <para> - Introduced most basic support for the MySQL Fabric High Availability and sharding - framework. + Introduced <link linkend="mysqlnd-ms.quickstart.mysql_fabric">most basic support</link> + for the MySQL Fabric High Availability and sharding framework. </para> <para> Please, consider this pre-alpha quality. Both the Modified: phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2014-03-11 14:46:05 UTC (rev 332952) +++ phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2014-03-11 14:50:29 UTC (rev 332953) @@ -767,6 +767,205 @@ </informaltable> </listitem> </varlistentry> + <varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.fabric"> + <term> + <parameter>fabric</parameter> + <type>object</type> + </term> + <listitem> + <para> + MySQL Fabric related settings. If the plugin is used together with MySQL + Fabric, then the plugins configuration file no longer contains lists of MySQL servers. + Instead, the plugin will ask MySQL Fabric which list of servers to use to + perform a certain task. + </para> + <para> + A minimum plugin configuration for use with MySQL Fabric contains a list + of one or more MySQL Fabric hosts that the plugin can query. If more + than one MySQL Fabric host is configured, the plugin will use a roundrobin + strategy to choose among them. Other strategies are currently not available. + </para> + <para> + <example> + <title>Minimum pluging configuration for use with MySQL Fabric</title> + <programlisting role="ini"> +<![CDATA[ +{ + "myapp": { + "fabric": { + "hosts": [ + { + "host" : "127.0.0.1", + "port" : 8080 + } + ] + } + } +} +]]> + </programlisting> + </example> + </para> + <para> + Each MySQL Fabric host is described using a JSON object with the following + members. + </para> + <informaltable> + <tgroup cols="3"> + <colspec colwidth="1*"/> + <colspec colwidth="7*"/> + <colspec colwidth="2*"/> + <thead> + <row> + <entry>Keyword</entry> + <entry>Description</entry> + <entry>Version</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>host</literal> + </entry> + <entry> + <para> + Host name of the MySQL Fabric host. + </para> + </entry> + <entry>Since 1.6.0.</entry> + </row> + <row> + <entry> + <literal>port</literal> + </entry> + <entry> + <para> + The TCP/IP port on which the MySQL Fabric host listens + for remote procedure calls sent by clients such as + the plugin. + </para> + </entry> + <entry>Since 1.6.0.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para> + The plugin is using PHP streams to communicate with MySQL Fabric + through XML RPC over HTTP. By default no timeouts are set + for the network communication. Thus, the plugin defaults to PHP + stream default timeouts. Those defaults are out of control of + the plugin itself. + </para> + <para> + An optional timeout value can be set to overrule the PHP streams + default timeout setting. Setting the timeout in the plugins + configuration file has the same effect as + setting a timeout for a PHP user space HTTP connection established + through PHP streams. + </para> + <para> + The plugins Fabric timeout value unit is seconds. The allowed value + range is from 0 to 65535. The setting exists since version 1.6. + </para> + <para> + <example> + <title>Optional timeout for communication with Fabric</title> + <programlisting role="ini"> +<![CDATA[ +{ + "myapp": { + "fabric": { + "hosts": [ + { + "host" : "127.0.0.1", + "port" : 8080 + } + ], + "timeout": 2 + } + } +} +]]> + </programlisting> + </example> + </para> + <para> + <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness">Transaction stickiness</link> + and MySQL Fabric logic can collide. The stickiness option disables switching + between servers for the duration of a transaction. When using Fabric and + sharding the user may (erroneously) start a local transaction on one share and + then attempt to switch to a different shard using either + <link linkend="function.mysqlnd-ms-fabric-select-shard"> + <function>mysqlnd_ms_fabric_select_shard</function></link> or + <link linkend="function.mysqlnd-ms-fabric-select-global"> + <function>mysqlnd_ms_fabric_select_global</function></link>. In this case, the + plugin will not reject the request to switch servers in the middle of a transaction + but allow the user to switch to another server regardless of the transaction + stickiness setting used. It is clearly a user error to write such code. + </para> + <para> + If transaction stickiness is enabled and you would like to get an error of type + warning when calling <link linkend="function.mysqlnd-ms-fabric-select-shard"> + <function>mysqlnd_ms_fabric_select_shard</function></link> or + <link linkend="function.mysqlnd-ms-fabric-select-global"> + <function>mysqlnd_ms_fabric_select_global</function></link>, + set the boolean flag <literal>trx_warn_server_list_changes</literal>. + </para> +<para> + <example> + <title>Warnings about the violation of transaction boundaries</title> + <programlisting role="ini"> +<![CDATA[ +{ + "myapp": { + "fabric": { + "hosts": [ + { + "host" : "127.0.0.1", + "port" : 8080 + } + ], + "trx_warn_serverlist_changes": 1 + }, + "trx_stickiness": "on" + } +} +]]> + </programlisting> + <programlisting role="php"> +<![CDATA[ +<?php +$link = new mysqli("myapp", "root", "", "test"); +/* + For the demo the call may fail. + Failed or not we get into the state + needed for the example. +*/ +@mysqlnd_ms_fabric_select_global($link, 1); +$link->begin_transaction(); +@$link->query("DROP TABLE IF EXISTS test"); +/* + Switching servers/shards is a mistake due to open + local transaction! +*/ +mysqlnd_ms_select_global($link, 1); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +PHP Warning: mysqlnd_ms_fabric_select_global(): (mysqlnd_ms) Fabric server exchange in the middle of a transaction in %s on line %d +]]> + </screen> + </example> + </para> + <para> + Please, consider the feature experimental. Changes to syntax and semantics may happen. + </para> + </listitem> + </varlistentry> <varlistentry xml:id="ini.mysqlnd-ms-plugin-config-v2.filters"> <term> <parameter>filters</parameter>

« previous php.doc.cvs (#12191) next »