Document MongoDB driver read preferences

https://jira.mongodb.org/browse/PHP-474


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@327468 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jeremy Mikola 2012-09-04 15:55:54 +00:00
parent 79fe4688e8
commit b8bef8d378
13 changed files with 1217 additions and 3 deletions

View file

@ -14,6 +14,7 @@
&reference.mongo.tutorial;
&reference.mongo.sqltomongo;
&reference.mongo.connecting;
&reference.mongo.readpreferences;
&reference.mongo.writes;
&reference.mongo.queries;
&reference.mongo.updates;

View file

@ -67,6 +67,36 @@ $db = $m->foo; // get the database named "foo"
<varname linkend="mongo.constants.defaultport">Mongo::DEFAULT_PORT</varname>
<initializer>27017</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongo.constants.rpprimary">Mongo::RP_PRIMARY</varname>
<initializer>"primary"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongo.constants.rpprimarypreferred">Mongo::RP_PRIMARY_PREFERRED</varname>
<initializer>"primaryPreferred"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongo.constants.rpsecondary">Mongo::RP_SECONDARY</varname>
<initializer>"secondary"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongo.constants.rpsecondary">Mongo::RP_SECONDARY_PREFERRED</varname>
<initializer>"secondaryPreferred"</initializer>
</fieldsynopsis>
<fieldsynopsis>
<modifier>const</modifier>
<type>string</type>
<varname linkend="mongo.constants.rpsecondary">Mongo::RP_NEAREST</varname>
<initializer>"nearest"</initializer>
</fieldsynopsis>
<classsynopsisinfo role="comment">Fields</classsynopsisinfo>
<fieldsynopsis>
@ -135,6 +165,56 @@ $db = $m->foo; // get the database named "foo"
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongo.constants.rpprimary">
<term><constant>Mongo::RP_PRIMARY</constant></term>
<term><constant>"primary"</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for the
primary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongo.constants.rpprimarypreferred">
<term><constant>Mongo::RP_PRIMARY_PREFERRED</constant></term>
<term><constant>"primaryPreferred"</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for
preferring the primary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongo.constants.rpsecondary">
<term><constant>Mongo::RP_SECONDARY</constant></term>
<term><constant>"secondary"</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for a
secondary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongo.constants.rpsecondarypreferred">
<term><constant>Mongo::RP_SECONDARY_PREFERRED</constant></term>
<term><constant>"secondaryPreferred"</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for
preferring a secondary replica set member.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="mongo.constants.rpnearest">
<term><constant>Mongo::RP_NEAREST</constant></term>
<term><constant>"nearest"</constant></term>
<listitem>
<simpara>
<link linkend="mongo.readpreferences">Read preference</link> for the
nearest replica set member.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>

View file

@ -45,9 +45,14 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db
throw a <classname>MongoConnectionException</classname>.
</para>
<para>
Finally, if you specified a username and password, you may specify a database
to authenticate with. If <literal>db</literal> is not specified, "admin"
will be used.
If you specified a username and password, you may specify a database to
authenticate with. If <literal>db</literal> is not specified, "admin" will
be used.
</para>
<para>
An optional query string may be used to specify
<link linkend="mongo.readpreferences">read preferences</link> for the
connection.
</para>
</refsect1>
@ -383,6 +388,24 @@ $m = new Mongo("mongodb://testUser:testPass@localhost");
]]>
</programlisting>
</example>
<example>
<title><function>Mongo::__construct</function> read preference example</title>
<programlisting role="php">
<![CDATA[
<?php
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
]]>
</programlisting>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link>
section of this manual for further information.
</para>
</example>
</refsect1>
</refentry>

View file

@ -0,0 +1,109 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::getReadPreference</refname>
<refpurpose>Get the read preference for this connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>Mongo::getReadPreference</methodname>
<void />
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array describing the read preference. The array
contains the values <literal>type</literal> for the numeric read preference
mode, <literal>type_string</literal> for the name of the read preference
mode, and <literal>tagsets</literal> containing a list of all tag set
criteria. If no tag sets were specified, <literal>tagsets</literal> will not
be present in the array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Mongo::getReadPreference</function> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$m->setReadPreference(Mongo::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($m->getReadPreference());
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["type"]=>
int(2)
["type_string"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
[0]=>
string(7) "dc:east"
[1]=>
string(13) "use:reporting"
}
[1]=>
array(1) {
[0]=>
string(7) "dc:west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,99 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongo.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Mongo::setReadPreference</refname>
<refpurpose>Set the read preference for this connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>Mongo::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>read_preference</parameter></term>
<listitem>
<para>
The read preference mode: <constant>Mongo::RP_PRIMARY</constant>,
<constant>Mongo::RP_PRIMARY_PREFERRED</constant>,
<constant>Mongo::RP_SECONDARY</constant>,
<constant>Mongo::RP_SECONDARY_PREFERRED</constant>, or
<constant>Mongo::RP_NEAREST</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tags</parameter></term>
<listitem>
<para>
An array of zero or more tag sets, where each tag set is itself an array
of criteria used to match tags on replica set members.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; on success, or &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>Mongo::setReadPreference</function> tag set array syntax example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$m->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,110 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::getReadPreference</refname>
<refpurpose>Get the read preference for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCollection::getReadPreference</methodname>
<void />
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array describing the read preference. The array
contains the values <literal>type</literal> for the numeric read preference
mode, <literal>type_string</literal> for the name of the read preference
mode, and <literal>tagsets</literal> containing a list of all tag set
criteria. If no tag sets were specified, <literal>tagsets</literal> will not
be present in the array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::getReadPreference</function> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$c = $m->test->users;
$c->setReadPreference(Mongo::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($c->getReadPreference());
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["type"]=>
int(2)
["type_string"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
[0]=>
string(7) "dc:east"
[1]=>
string(13) "use:reporting"
}
[1]=>
array(1) {
[0]=>
string(7) "dc:west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocollection.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCollection::setReadPreference</refname>
<refpurpose>Set the read preference for this collection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCollection::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>read_preference</parameter></term>
<listitem>
<para>
The read preference mode: <constant>Mongo::RP_PRIMARY</constant>,
<constant>Mongo::RP_PRIMARY_PREFERRED</constant>,
<constant>Mongo::RP_SECONDARY</constant>,
<constant>Mongo::RP_SECONDARY_PREFERRED</constant>, or
<constant>Mongo::RP_NEAREST</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tags</parameter></term>
<listitem>
<para>
An array of zero or more tag sets, where each tag set is itself an array
of criteria used to match tags on replica set members.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; on success, or &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCollection::setReadPreference</function> tag set array syntax example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$c = $m->test->users;
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$c->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,110 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocursor.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCursor::getReadPreference</refname>
<refpurpose>Get the read preference for this query</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoCursor::getReadPreference</methodname>
<void />
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array describing the read preference. The array
contains the values <literal>type</literal> for the numeric read preference
mode, <literal>type_string</literal> for the name of the read preference
mode, and <literal>tagsets</literal> containing a list of all tag set
criteria. If no tag sets were specified, <literal>tagsets</literal> will not
be present in the array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCursor::getReadPreference</function> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$cursor = $m->test->users->find();
$cursor->setReadPreference(Mongo::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($cursor->getReadPreference());
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["type"]=>
int(2)
["type_string"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
[0]=>
string(7) "dc:east"
[1]=>
string(13) "use:reporting"
}
[1]=>
array(1) {
[0]=>
string(7) "dc:west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,101 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongocursor.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoCursor::setReadPreference</refname>
<refpurpose>Set the read preference for this query</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoCursor::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>read_preference</parameter></term>
<listitem>
<para>
The read preference mode: <constant>Mongo::RP_PRIMARY</constant>,
<constant>Mongo::RP_PRIMARY_PREFERRED</constant>,
<constant>Mongo::RP_SECONDARY</constant>,
<constant>Mongo::RP_SECONDARY_PREFERRED</constant>, or
<constant>Mongo::RP_NEAREST</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tags</parameter></term>
<listitem>
<para>
An array of zero or more tag sets, where each tag set is itself an array
of criteria used to match tags on replica set members.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; on success, or &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoCursor::setReadPreference</function> tag set array syntaxexample
</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$cursor = $m->test->users->find();
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$cursor->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,110 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongodb.getreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB::getReadPreference</refname>
<refpurpose>Get the read preference for this database</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>array</type><methodname>MongoDB::getReadPreference</methodname>
<void />
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
&no.function.parameters;
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
This function returns an array describing the read preference. The array
contains the values <literal>type</literal> for the numeric read preference
mode, <literal>type_string</literal> for the name of the read preference
mode, and <literal>tagsets</literal> containing a list of all tag set
criteria. If no tag sets were specified, <literal>tagsets</literal> will not
be present in the array.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoDB::getReadPreference</function> return value example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$db = $m->test;
$db->setReadPreference(Mongo::RP_SECONDARY, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
array(),
));
var_dump($db->getReadPreference());
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(3) {
["type"]=>
int(2)
["type_string"]=>
string(9) "secondary"
["tagsets"]=>
array(3) {
[0]=>
array(2) {
[0]=>
string(7) "dc:east"
[1]=>
string(13) "use:reporting"
}
[1]=>
array(1) {
[0]=>
string(7) "dc:west"
}
[2]=>
array(0) {
}
}
}
]]>
</screen>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,100 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="mongodb.setreadpreference" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>MongoDB::setReadPreference</refname>
<refpurpose>Set the read preference for this database</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<modifier>public</modifier> <type>bool</type><methodname>MongoDB::setReadPreference</methodname>
<methodparam><type>string</type><parameter>read_preference</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>tags</parameter></methodparam>
</methodsynopsis>
<para>
See the <link linkend="mongo.readpreferences">read preferences</link> section
of this manual for further information.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>read_preference</parameter></term>
<listitem>
<para>
The read preference mode: <constant>Mongo::RP_PRIMARY</constant>,
<constant>Mongo::RP_PRIMARY_PREFERRED</constant>,
<constant>Mongo::RP_SECONDARY</constant>,
<constant>Mongo::RP_SECONDARY_PREFERRED</constant>, or
<constant>Mongo::RP_NEAREST</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>tags</parameter></term>
<listitem>
<para>
An array of zero or more tag sets, where each tag set is itself an array
of criteria used to match tags on replica set members.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns &true; on success, or &false; otherwise.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<example>
<title><function>MongoDB::setReadPreference</function> tag set array syntax example</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo();
$db = $m->test;
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$db->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
]]>
</programlisting>
</example>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

View file

@ -0,0 +1,263 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 317663 $ -->
<section xml:id="mongo.readpreferences" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Read Preferences</title>
<para>
MongoDB 2.2 and version 1.3.0 of the driver add support for
<link xlink:href="&url.mongodb.docs.readpreferences;">read preferences</link>,
which allow control over how queries are directed to mongod instances. Read
preferences may be specified on either a per-connection, per-database,
per-collection, or per-cursor basis. Preferences defined at a higher level
will be inherited by default (e.g. <classname>MongoCollection</classname> will
inherit read perferences defined on the corresponding
<classname>MongoDB</classname> instance).
</para>
<para>
Read preferences are specified with a combination of modes and tag sets. Modes
determine how mongod instances are prioritized, while
<link xlink:href="&url.mongodb.docs.tagsets;">tag sets</link> specify criteria
for eligible mongod instances.
</para>
<section>
<title>Read Preference Modes</title>
<warning>
<para>
All read preference modes except <literal>Mongo::RP_PRIMARY</literal> may
return stale data as secondaries replicate operations from the primary with
some delay. Ensure that your application can tolerate stale data if you
choose to use a mode other than <literal>Mongo::RP_PRIMARY</literal>.
</para>
</warning>
<itemizedlist>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY</literal>
</para>
<para>
All read operations use only the current replica set primary. This is the
default. If the primary is unavailable, read operations will produce an
exception.
</para>
<para>
This mode is incompatible with use of tag sets. Specifying a tag set with
<literal>Mongo::RP_PRIMARY</literal> will result in an error.
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY_PREFERRED</literal>
</para>
<para>
In most situations, operations read from the primary member of the set.
However, if the primary is unavailable, as is the case during failover
situations, operations read from secondary members.
</para>
<para>
When the read preference includes a tag set, the client reads first from
the primary, if available, and then from secondaries that match the
specified tags. If no secondaries have matching tags, the read operation
will produce an exception.
</para>
<warning>
<para>
Version 2.2 of mongos added full support for read preferences. When
connecting to older mongos instances,
<literal>Mongo::RP_PRIMARY_PREFERRED</literal> will send queries to
secondaries.
</para>
</warning>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY</literal>
</para>
<para>
Operations read only from the secondary members of the set. If no
secondaries are available, read operations will produce an exception.
</para>
<para>
Most sets have at least one secondary, but there are situations where
there may be no available secondary. For example, a set with a primary, a
secondary, and an arbiter may not have any secondaries if a member is in
recovering state or unavailable.
</para>
<para>
When the read preference includes a tag set, the client attempts to find
secondary members that match the specified tag set and directs reads to a
random secondary from among the nearest group. If no secondaries have
matching tags, the read operation will produce an exception.
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY_PREFERRED</literal>
</para>
<para>
In most situations, operations read from secondary members, but in
situations where the set consists of a single primary with no other
members, the read operation will use the set's primary.
</para>
<para>
When the read preference includes a tag set, the client attempts to find a
secondary member that matches the specified tag set and directs reads to a
random secondary from among the nearest group. If no secondaries have
matching tags, the read operation will produce an exception.
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_NEAREST</literal>
</para>
<para>
The driver reads from the nearest member of the set according to the member
selection process. Reads in the <literal>Mongo::RP_NEAREST</literal> mode
do not consider the member's type and may read from both primaries and
secondaries.
</para>
<para>
Set this mode to minimize the effect of network latency on read operations
without preference for current or stale data.
</para>
<para>
If you specify a tag set, the client attempts to find a secondary member
that matches the specified tag set and directs reads to a random secondary
from among the nearest group.
</para>
<note>
<para>
All operations read from the nearest member of the replica set that
matches the specified read preference mode. The
<literal>Mongo::RP_NEAREST</literal> mode prefers low latency reads over a
member's primary or secondary status.
</para>
</note>
</listitem>
</itemizedlist>
</section>
<section>
<title>Tag Sets</title>
<para>
<link xlink:href="&url.mongodb.docs.tagsets;">Tag sets</link> allow you to
specify criteria so that your application can target read operations to
specific members, based on custom parameters. Tag sets make it possible to
ensure that read operations target members in a particular data center or
target mongod instances designated for a particular class of operations, such
as reporting or analytics.
</para>
<para>
You can specify tag sets with the following read preference modes:
</para>
<itemizedlist>
<listitem>
<para>
<literal>Mongo::RP_PRIMARY_PREFERRED</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_SECONDARY_PREFERRED</literal>
</para>
</listitem>
<listitem>
<para>
<literal>Mongo::RP_NEAREST</literal>
</para>
</listitem>
</itemizedlist>
<para>
You cannot specify tag sets with the <literal>Mongo::RP_PRIMARY</literal>
read preference mode. Tags apply only when selecting a secondary member of a
set, except for the when in the nearest mode.
</para>
</section>
<section>
<title>Specifying Read Preferences</title>
<para>
Read preferences may be specified in either the connection URI provided to
<function>Mongo::__construct</function>, which uses a query string syntax, or
via setter methods on the core classes, which use an array syntax for tag
sets.
</para>
<para>
<example>
<title>Connection URI read preferences with query string syntax</title>
<programlisting role="php">
<![CDATA[
<?php
// Prefer the nearest server with no tag preference
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Prefer the nearest server in the "east" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east,use:reporting';
$uri .= '&readPreferenceTags=dc:west';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
// Prefer the nearest server in the "east" data center, then a server in the
// "west" data center, and finally fall back to no tag set preference
$uri = 'mongodb://rs1.example.com,rs2.example.com/';
$uri .= '?readPreference=nearest';
$uri .= '&readPreferenceTags=dc:east';
$uri .= '&readPreferenceTags=dc:west';
$uri .= '&readPreferenceTags=';
$m = new Mongo($uri, array('replicaSet' => 'rs'));
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Setting read preferences with array syntax for tag sets</title>
<programlisting role="php">
<![CDATA[
<?php
$m = new Mongo('mongodb://rs1.example.com,rs2.example.com', array(
'replicaSet' => 'rs',
));
// Prefer the nearest server with no tag preference
$m->setReadPreference(Mongo::RP_NEAREST, array());
// Prefer the nearest server in the "east" data center
$m->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east'),
));
// Prefer the nearest server in the "east" data center also used for reporting,
// but fall back to a server in the "west" data center
$m->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east', 'use' => 'reporting'),
array('dc' => 'west'),
));
// Prefer the nearest server in the "east" data center, then a server in the
// "west" data center, and finally fall back to no tag set preference
$m->setReadPreference(Mongo::RP_NEAREST, array(
array('dc' => 'east'),
array('dc' => 'west'),
array(),
));
]]>
</programlisting>
</example>
</para>
</section>
</section>

View file

@ -24,6 +24,8 @@
<function name='mongo::gethosts' from='PECL mongo &gt;=1.1.0'/>
<function name='mongo::getslave' from='PECL mongo &gt;=1.1.0'/>
<function name='mongo::switchslave' from='PECL mongo &gt;=1.1.0'/>
<function name='mongo::getreadpreference' from='PECL mongo &gt;=1.3.0'/>
<function name='mongo::setreadpreference' from='PECL mongo &gt;=1.3.0'/>
<!-- MongoDB -->
<function name='mongodb' from='PECL mongo &gt;=0.9.0'/>
<function name='mongodb::__construct' from='PECL mongo &gt;=0.9.0'/>
@ -51,6 +53,8 @@
<function name='mongodb::authenticate' from='PECL mongo &gt;=1.0.1'/>
<function name='mongodb::setslaveokay' from='PECL mongo &gt;=1.1.0'/>
<function name='mongodb::getslaveokay' from='PECL mongo &gt;=1.1.0'/>
<function name='mongodb::getreadpreference' from='PECL mongo &gt;=1.3.0'/>
<function name='mongodb::setseadpreference' from='PECL mongo &gt;=1.3.0'/>
<!-- MongoCollection -->
<function name='mongocollection' from='PECL mongo &gt;=0.9.0'/>
<function name='mongocollection::__construct' from='PECL mongo &gt;=0.9.0'/>
@ -78,6 +82,8 @@
<function name='mongocollection::distinct' from='PECL mongo &gt;=1.2.11'/>
<function name='mongocollection::setslaveokay' from='PECL mongo &gt;=1.1.0'/>
<function name='mongocollection::getslaveokay' from='PECL mongo &gt;=1.1.0'/>
<function name='mongocollection::getreadpreference' from='PECL mongo &gt;=1.3.0'/>
<function name='mongocollection::setseadpreference' from='PECL mongo &gt;=1.3.0'/>
<!-- MongoCursor -->
<function name='mongocursor' from='PECL mongo &gt;=0.9.0'/>
<function name='mongocursor::__construct' from='PECL mongo &gt;=0.9.0'/>
@ -106,6 +112,8 @@
<function name='mongocursor::info' from='PECL mongo &gt;=1.0.5'/>
<function name='mongocursor::batchSize' from='PECL mongo &gt;=1.0.11'/>
<function name='mongocursor::partial' from='PECL mongo &gt;=1.2.0'/>
<function name='mongocursor::getreadpreference' from='PECL mongo &gt;=1.3.0'/>
<function name='mongocursor::setseadpreference' from='PECL mongo &gt;=1.3.0'/>
<!-- MongoGridFS -->
<function name='mongogridfs' from='PECL mongo &gt;=0.9.0'/>
<function name='mongogridfs::__construct' from='PECL mongo &gt;=0.9.0'/>