diff --git a/reference/mongo/manual.xml b/reference/mongo/manual.xml index a584560690..73bddcdd2b 100644 --- a/reference/mongo/manual.xml +++ b/reference/mongo/manual.xml @@ -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; diff --git a/reference/mongo/mongo.xml b/reference/mongo/mongo.xml index 858a1622aa..62090a8bad 100644 --- a/reference/mongo/mongo.xml +++ b/reference/mongo/mongo.xml @@ -67,6 +67,36 @@ $db = $m->foo; // get the database named "foo" Mongo::DEFAULT_PORT 27017 + + const + string + Mongo::RP_PRIMARY + "primary" + + + const + string + Mongo::RP_PRIMARY_PREFERRED + "primaryPreferred" + + + const + string + Mongo::RP_SECONDARY + "secondary" + + + const + string + Mongo::RP_SECONDARY_PREFERRED + "secondaryPreferred" + + + const + string + Mongo::RP_NEAREST + "nearest" + Fields @@ -135,6 +165,56 @@ $db = $m->foo; // get the database named "foo" + + Mongo::RP_PRIMARY + "primary" + + + Read preference for the + primary replica set member. + + + + + Mongo::RP_PRIMARY_PREFERRED + "primaryPreferred" + + + Read preference for + preferring the primary replica set member. + + + + + Mongo::RP_SECONDARY + "secondary" + + + Read preference for a + secondary replica set member. + + + + + Mongo::RP_SECONDARY_PREFERRED + "secondaryPreferred" + + + Read preference for + preferring a secondary replica set member. + + + + + Mongo::RP_NEAREST + "nearest" + + + Read preference for the + nearest replica set member. + + + diff --git a/reference/mongo/mongo/construct.xml b/reference/mongo/mongo/construct.xml index 52e28966a9..6cd1a69490 100644 --- a/reference/mongo/mongo/construct.xml +++ b/reference/mongo/mongo/construct.xml @@ -45,9 +45,14 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db throw a MongoConnectionException. - Finally, if you specified a username and password, you may specify a database - to authenticate with. If db is not specified, "admin" - will be used. + If you specified a username and password, you may specify a database to + authenticate with. If db is not specified, "admin" will + be used. + + + An optional query string may be used to specify + read preferences for the + connection. @@ -383,6 +388,24 @@ $m = new Mongo("mongodb://testUser:testPass@localhost"); ]]> + + <function>Mongo::__construct</function> read preference example + + 'rs')); +]]> + + + See the read preferences + section of this manual for further information. + + diff --git a/reference/mongo/mongo/getreadpreference.xml b/reference/mongo/mongo/getreadpreference.xml new file mode 100644 index 0000000000..7a41a0b4cc --- /dev/null +++ b/reference/mongo/mongo/getreadpreference.xml @@ -0,0 +1,109 @@ + + + + + + Mongo::getReadPreference + Get the read preference for this connection + + + + &reftitle.description; + + public arrayMongo::getReadPreference + + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + This function returns an array describing the read preference. The array + contains the values type for the numeric read preference + mode, type_string for the name of the read preference + mode, and tagsets containing a list of all tag set + criteria. If no tag sets were specified, tagsets will not + be present in the array. + + + + + &reftitle.examples; + + <function>Mongo::getReadPreference</function> return value example + +setReadPreference(Mongo::RP_SECONDARY, array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + array(), +)); +var_dump($m->getReadPreference()); +]]> + + &example.outputs; + + + 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) { + } + } +} +]]> + + + + + + + diff --git a/reference/mongo/mongo/setreadpreference.xml b/reference/mongo/mongo/setreadpreference.xml new file mode 100644 index 0000000000..e4b28d650a --- /dev/null +++ b/reference/mongo/mongo/setreadpreference.xml @@ -0,0 +1,99 @@ + + + + + + Mongo::setReadPreference + Set the read preference for this connection + + + + &reftitle.description; + + public boolMongo::setReadPreference + stringread_preference + arraytags + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + + + read_preference + + + The read preference mode: Mongo::RP_PRIMARY, + Mongo::RP_PRIMARY_PREFERRED, + Mongo::RP_SECONDARY, + Mongo::RP_SECONDARY_PREFERRED, or + Mongo::RP_NEAREST. + + + + + tags + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns &true; on success, or &false; otherwise. + + + + + &reftitle.examples; + + <function>Mongo::setReadPreference</function> tag set array syntax example + +setReadPreference(Mongo::RP_NEAREST, array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), +)); +]]> + + + + + + + diff --git a/reference/mongo/mongocollection/getreadpreference.xml b/reference/mongo/mongocollection/getreadpreference.xml new file mode 100644 index 0000000000..98823c223f --- /dev/null +++ b/reference/mongo/mongocollection/getreadpreference.xml @@ -0,0 +1,110 @@ + + + + + + MongoCollection::getReadPreference + Get the read preference for this collection + + + + &reftitle.description; + + public arrayMongoCollection::getReadPreference + + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + This function returns an array describing the read preference. The array + contains the values type for the numeric read preference + mode, type_string for the name of the read preference + mode, and tagsets containing a list of all tag set + criteria. If no tag sets were specified, tagsets will not + be present in the array. + + + + + &reftitle.examples; + + <function>MongoCollection::getReadPreference</function> return value example + +test->users; +$c->setReadPreference(Mongo::RP_SECONDARY, array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + array(), +)); +var_dump($c->getReadPreference()); +]]> + + &example.outputs; + + + 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) { + } + } +} +]]> + + + + + + + diff --git a/reference/mongo/mongocollection/setreadpreference.xml b/reference/mongo/mongocollection/setreadpreference.xml new file mode 100644 index 0000000000..7c8f14c2bc --- /dev/null +++ b/reference/mongo/mongocollection/setreadpreference.xml @@ -0,0 +1,100 @@ + + + + + + MongoCollection::setReadPreference + Set the read preference for this collection + + + + &reftitle.description; + + public boolMongoCollection::setReadPreference + stringread_preference + arraytags + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + + + read_preference + + + The read preference mode: Mongo::RP_PRIMARY, + Mongo::RP_PRIMARY_PREFERRED, + Mongo::RP_SECONDARY, + Mongo::RP_SECONDARY_PREFERRED, or + Mongo::RP_NEAREST. + + + + + tags + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns &true; on success, or &false; otherwise. + + + + + &reftitle.examples; + + <function>MongoCollection::setReadPreference</function> tag set array syntax example + +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'), +)); +]]> + + + + + + + diff --git a/reference/mongo/mongocursor/getreadpreference.xml b/reference/mongo/mongocursor/getreadpreference.xml new file mode 100644 index 0000000000..4204776bad --- /dev/null +++ b/reference/mongo/mongocursor/getreadpreference.xml @@ -0,0 +1,110 @@ + + + + + + MongoCursor::getReadPreference + Get the read preference for this query + + + + &reftitle.description; + + public arrayMongoCursor::getReadPreference + + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + This function returns an array describing the read preference. The array + contains the values type for the numeric read preference + mode, type_string for the name of the read preference + mode, and tagsets containing a list of all tag set + criteria. If no tag sets were specified, tagsets will not + be present in the array. + + + + + &reftitle.examples; + + <function>MongoCursor::getReadPreference</function> return value example + +test->users->find(); +$cursor->setReadPreference(Mongo::RP_SECONDARY, array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + array(), +)); +var_dump($cursor->getReadPreference()); +]]> + + &example.outputs; + + + 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) { + } + } +} +]]> + + + + + + + diff --git a/reference/mongo/mongocursor/setreadpreference.xml b/reference/mongo/mongocursor/setreadpreference.xml new file mode 100644 index 0000000000..29a847ea33 --- /dev/null +++ b/reference/mongo/mongocursor/setreadpreference.xml @@ -0,0 +1,101 @@ + + + + + + MongoCursor::setReadPreference + Set the read preference for this query + + + + &reftitle.description; + + public boolMongoCursor::setReadPreference + stringread_preference + arraytags + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + + + read_preference + + + The read preference mode: Mongo::RP_PRIMARY, + Mongo::RP_PRIMARY_PREFERRED, + Mongo::RP_SECONDARY, + Mongo::RP_SECONDARY_PREFERRED, or + Mongo::RP_NEAREST. + + + + + tags + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns &true; on success, or &false; otherwise. + + + + + &reftitle.examples; + + <function>MongoCursor::setReadPreference</function> tag set array syntaxexample + + +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'), +)); +]]> + + + + + + + diff --git a/reference/mongo/mongodb/getreadpreference.xml b/reference/mongo/mongodb/getreadpreference.xml new file mode 100644 index 0000000000..5834a15b18 --- /dev/null +++ b/reference/mongo/mongodb/getreadpreference.xml @@ -0,0 +1,110 @@ + + + + + + MongoDB::getReadPreference + Get the read preference for this database + + + + &reftitle.description; + + public arrayMongoDB::getReadPreference + + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + This function returns an array describing the read preference. The array + contains the values type for the numeric read preference + mode, type_string for the name of the read preference + mode, and tagsets containing a list of all tag set + criteria. If no tag sets were specified, tagsets will not + be present in the array. + + + + + &reftitle.examples; + + <function>MongoDB::getReadPreference</function> return value example + +test; +$db->setReadPreference(Mongo::RP_SECONDARY, array( + array('dc' => 'east', 'use' => 'reporting'), + array('dc' => 'west'), + array(), +)); +var_dump($db->getReadPreference()); +]]> + + &example.outputs; + + + 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) { + } + } +} +]]> + + + + + + + diff --git a/reference/mongo/mongodb/setreadpreference.xml b/reference/mongo/mongodb/setreadpreference.xml new file mode 100644 index 0000000000..c7b704bdd6 --- /dev/null +++ b/reference/mongo/mongodb/setreadpreference.xml @@ -0,0 +1,100 @@ + + + + + + MongoDB::setReadPreference + Set the read preference for this database + + + + &reftitle.description; + + public boolMongoDB::setReadPreference + stringread_preference + arraytags + + + See the read preferences section + of this manual for further information. + + + + + &reftitle.parameters; + + + read_preference + + + The read preference mode: Mongo::RP_PRIMARY, + Mongo::RP_PRIMARY_PREFERRED, + Mongo::RP_SECONDARY, + Mongo::RP_SECONDARY_PREFERRED, or + Mongo::RP_NEAREST. + + + + + tags + + + 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. + + + + + + + + &reftitle.returnvalues; + + Returns &true; on success, or &false; otherwise. + + + + + &reftitle.examples; + + <function>MongoDB::setReadPreference</function> tag set array syntax example + +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'), +)); +]]> + + + + + + + diff --git a/reference/mongo/readpreferences.xml b/reference/mongo/readpreferences.xml new file mode 100644 index 0000000000..e3469b3c36 --- /dev/null +++ b/reference/mongo/readpreferences.xml @@ -0,0 +1,263 @@ + + + +
+ Read Preferences + + MongoDB 2.2 and version 1.3.0 of the driver add support for + read preferences, + 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. MongoCollection will + inherit read perferences defined on the corresponding + MongoDB instance). + + + Read preferences are specified with a combination of modes and tag sets. Modes + determine how mongod instances are prioritized, while + tag sets specify criteria + for eligible mongod instances. + +
+ Read Preference Modes + + + All read preference modes except Mongo::RP_PRIMARY 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 Mongo::RP_PRIMARY. + + + + + + Mongo::RP_PRIMARY + + + 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. + + + This mode is incompatible with use of tag sets. Specifying a tag set with + Mongo::RP_PRIMARY will result in an error. + + + + + Mongo::RP_PRIMARY_PREFERRED + + + 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. + + + 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. + + + + Version 2.2 of mongos added full support for read preferences. When + connecting to older mongos instances, + Mongo::RP_PRIMARY_PREFERRED will send queries to + secondaries. + + + + + + Mongo::RP_SECONDARY + + + Operations read only from the secondary members of the set. If no + secondaries are available, read operations will produce an exception. + + + 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. + + + 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. + + + + + Mongo::RP_SECONDARY_PREFERRED + + + 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. + + + 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. + + + + + Mongo::RP_NEAREST + + + The driver reads from the nearest member of the set according to the member + selection process. Reads in the Mongo::RP_NEAREST mode + do not consider the member's type and may read from both primaries and + secondaries. + + + Set this mode to minimize the effect of network latency on read operations + without preference for current or stale data. + + + 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. + + + + All operations read from the nearest member of the replica set that + matches the specified read preference mode. The + Mongo::RP_NEAREST mode prefers low latency reads over a + member's primary or secondary status. + + + + +
+
+ Tag Sets + + Tag sets 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. + + + You can specify tag sets with the following read preference modes: + + + + + Mongo::RP_PRIMARY_PREFERRED + + + + + Mongo::RP_SECONDARY + + + + + Mongo::RP_SECONDARY_PREFERRED + + + + + Mongo::RP_NEAREST + + + + + You cannot specify tag sets with the Mongo::RP_PRIMARY + read preference mode. Tags apply only when selecting a secondary member of a + set, except for the when in the nearest mode. + +
+
+ Specifying Read Preferences + + Read preferences may be specified in either the connection URI provided to + Mongo::__construct, which uses a query string syntax, or + via setter methods on the core classes, which use an array syntax for tag + sets. + + + + Connection URI read preferences with query string syntax + + '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')); +]]> + + + + + + Setting read preferences with array syntax for tag sets + + '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(), +)); +]]> + + + +
+
diff --git a/reference/mongo/versions.xml b/reference/mongo/versions.xml index cbb5e43265..077d1ca964 100644 --- a/reference/mongo/versions.xml +++ b/reference/mongo/versions.xml @@ -24,6 +24,8 @@ + + @@ -51,6 +53,8 @@ + + @@ -78,6 +82,8 @@ + + @@ -106,6 +112,8 @@ + +