From 8a4640c71cd1b8b6ad42f5c58ba0daacfea739c4 Mon Sep 17 00:00:00 2001 From: Jeremy Mikola Date: Mon, 26 Nov 2012 03:07:28 +0000 Subject: [PATCH] Revise replica set language and MongoClient references Replace master/slave terminology with primary/secondary Change most Mongo class references to MongoClient Enforce 80-char line widths and trim trailing whitespace Add literal formatting within some paragraphs https://jira.mongodb.org/browse/PHP-583 git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328496 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/connecting.xml | 149 ++++++++++-------- reference/mongo/mongo/getslave.xml | 19 +-- reference/mongo/mongo/getslaveokay.xml | 2 +- reference/mongo/mongo/pooldebug.xml | 8 +- reference/mongo/mongo/setslaveokay.xml | 6 +- reference/mongo/mongo/switchslave.xml | 25 +-- reference/mongo/mongoclient/construct.xml | 12 +- reference/mongo/mongoclient/gethosts.xml | 2 +- .../mongo/mongocollection/batchinsert.xml | 2 +- .../mongo/mongocollection/deleteindex.xml | 2 +- .../mongo/mongocollection/ensureindex.xml | 20 +-- reference/mongo/mongocollection/find.xml | 8 +- reference/mongo/mongocollection/get.xml | 12 +- reference/mongo/mongocollection/getname.xml | 6 +- .../mongocollection/getreadpreference.xml | 4 +- .../mongo/mongocollection/getslaveokay.xml | 2 +- reference/mongo/mongocollection/insert.xml | 24 +-- reference/mongo/mongocollection/remove.xml | 12 +- reference/mongo/mongocollection/save.xml | 12 +- .../mongocollection/setreadpreference.xml | 4 +- .../mongo/mongocollection/setslaveokay.xml | 2 +- reference/mongo/mongocollection/tostring.xml | 6 +- reference/mongo/mongocollection/update.xml | 12 +- reference/mongo/mongoconnectionexception.xml | 2 +- reference/mongo/mongocursor.xml | 4 +- reference/mongo/mongocursor/awaitdata.xml | 8 +- reference/mongo/mongocursor/batchsize.xml | 2 +- reference/mongo/mongocursor/construct.xml | 2 +- reference/mongo/mongocursor/doquery.xml | 4 +- .../mongo/mongocursor/getreadpreference.xml | 4 +- reference/mongo/mongocursor/info.xml | 2 +- reference/mongo/mongocursor/setflag.xml | 2 +- .../mongo/mongocursor/setreadpreference.xml | 4 +- reference/mongo/mongocursor/slaveokay.xml | 28 ++-- reference/mongo/mongocursorexception.xml | 10 +- reference/mongo/mongodb.xml | 29 ++-- reference/mongo/mongodb/authenticate.xml | 28 ++-- reference/mongo/mongodb/command.xml | 2 +- reference/mongo/mongodb/construct.xml | 22 +-- reference/mongo/mongodb/get.xml | 2 +- reference/mongo/mongodb/getreadpreference.xml | 4 +- reference/mongo/mongodb/getslaveokay.xml | 2 +- reference/mongo/mongodb/listcollections.xml | 2 +- reference/mongo/mongodb/setreadpreference.xml | 4 +- reference/mongo/mongodb/setslaveokay.xml | 2 +- reference/mongo/mongoid/tostring.xml | 2 +- reference/mongo/mongolog/setcallback.xml | 2 +- reference/mongo/mongopool/info.xml | 6 +- reference/mongo/queries.xml | 56 +++---- reference/mongo/readpreferences.xml | 71 +++++---- reference/mongo/tutorial.xml | 14 +- reference/mongo/writes.xml | 6 +- 52 files changed, 345 insertions(+), 332 deletions(-) diff --git a/reference/mongo/connecting.xml b/reference/mongo/connecting.xml index cbc9b75f33..bd13f5f254 100644 --- a/reference/mongo/connecting.xml +++ b/reference/mongo/connecting.xml @@ -5,10 +5,11 @@ Connecting - Connecting to MongoDB can be as easy as new Mongo, but - there are many additional options and configurations. The - Mongo::__construct page covers all of the API options, - but this page gives some more details and advice for practical use cases. + Connecting to MongoDB can be as easy as new MongoClient, + but there are many additional options and configurations. The documentation + for MongoClient::__construct covers all of the API + options, but this page gives some more details and advice for practical use + cases.
@@ -19,16 +20,16 @@ any operations with the driver. You may authenticate a connection by specifying the username and password in either the connection URI or the "username" and "password" options for - Mongo::__construct. + MongoClient::__construct. $username, "password" => $password)); +$m = new MongoClient("mongodb://localhost", array("username" => $username, "password" => $password)); ?> ]]> @@ -36,16 +37,16 @@ $m = new Mongo("mongodb://localhost", array("username" => $username, "password" By default, the driver will authenticate against the admin database. You may authenticate against a different database by specifying it in either the connection URI or the "db" option for - Mongo::__construct. + MongoClient::__construct. "myDatabase")); +$m = new MongoClient("mongodb://${username}:${password}@localhost", array("db" => "myDatabase")); ?> ]]> @@ -59,45 +60,47 @@ $m = new Mongo("mongodb://${username}:${password}@localhost", array("db" => "myD Replica Sets To connect to a replica set, specify one or more members of the set and use - the replicaSet option. Multiple servers may be delimited + the "replicaSet" option. Multiple servers may be delimited by a comma. "myReplSetName")); +$m = new MongoClient("mongodb://rs1.example.com:27017", array("replicaSet" => "myReplSetName")); // Using multiple servers as the seed list -$m = new Mongo("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName")); +$m = new MongoClient("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("replicaSet" => "myReplSetName")); ?> ]]> - Version 1.0.9+ of the driver is required to connect to a replica set - (earlier versions of the driver will not autodetect the master or reconnect - correctly). + Version 1.0.9+ of the driver is required to connect to a replica set. Earlier + versions of the driver will not auto-detect the primary or reconnect + correctly. - The PHP driver will query the database server(s) listed to figure out who is - master. So long as it can connect to at least one host listed and find a - master, the connection will succeed. If it cannot make a connection to any - servers listed or cannot find a master, a + The PHP driver will query the database server(s) listed to determine the + primary. So long as it can connect to at least one host listed and find a + primary, the connection will succeed. If it cannot make a connection to any + servers listed or cannot find a primary, a MongoConnectionException will be thrown. - If the master becomes unavailable, the slaves will not promote a new master - for a few seconds. During that time, this connection will not be able to - perform any database operations (connections to slaves will still be able to - perform reads). Thus, if you attempt to do any sort of read or write on this - connection, it will throw an exception. + If the primary becomes unavailable, an election will take place and a + secondary will be promoted to the role of primary (unless a majority vote + cannot be established). During this time + (20-60 seconds), the + connection will not be able to perform any write operations and attempts to + do so will result in an exception. Connections to secondaries will still be + able to perform reads. - Once a master is elected, attempting to perform a read or write will allow - the driver to detect the new master. The driver will make this its primary + Once a primary is elected, attempting to perform a read or write will allow + the driver to detect the new primary. The driver will make this its primary database connection and continue operating normally. @@ -118,10 +121,10 @@ $m = new Mongo("mongodb://rs1.example.com:27017,rs2.example.com:27017", array("r ]]> @@ -142,8 +145,8 @@ $m = new Mongo("mongodb://mongos1.example.com:27017,mongos2.example.com:27017")) If you are running MongoDB locally and using version 1.0.9+ of the driver, - you can connect to the database via file. MongoDB automatically opens a - socket file on startup: /tmp/mongodb-<port>.sock. + you can connect to the database via a socket file. MongoDB automatically + opens a socket file on startup: /tmp/mongodb-<port>.sock. @@ -154,21 +157,22 @@ $m = new Mongo("mongodb://mongos1.example.com:27017,mongos2.example.com:27017")) ]]> - If you would like to use authentication on connection (as described above) - with a socket file, you must specify a port of 0 so that the connection - string parser knows where the end of the connection string is. + If you would like to authenticate against a database (as described above) + with a socket file, you must specify a port of 0 so that + the connection string parser can detect the end of the socket path. + Alternatively, you can use the constructor options. ]]> @@ -180,23 +184,24 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); Creating connections is one of the most heavyweight things that the driver does. It can take hundreds of milliseconds to set up a connection correctly, - even on a fast network. Thus, the driver tries to minimize the number of new + even on a fast network. Thus, the driver tries to minimize the number of new connections created by reusing connections from a pool. - When a user creates a new instance of Mongo, all + When a user creates a new instance of MongoClient, all necessary connections will be taken from their pools (replica sets may - require multple connections, one for each member of the set). When the - Mongo instance goes out of scope, the connections will - be returned to the pool. When the PHP process exits, all connections in the - pools will be closed. + require multiple connections, one for each member of the set). When the + MongoClient instance goes out of scope, the + connections will be returned to the pool. When the PHP process exits, all + connections in the pools will be closed.
"Why do I have so many open connections?" - Connection pools can generate a large number of connections. This is expected - and, using a little arithmetic, you can figure out how many connections to - expect. There are three factors in the total number of connections: + Connection pools can generate a large number of connections. This is + expected and, using a little arithmetic, you can figure out how many + connections will be created. There are three factors in determining the + total number of connections: @@ -218,8 +223,8 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); You can see how many connections you have in a pool using the - MongoPool::info function. Add up the "in use" and - "in pool" fields for a given server. That is the total number of + MongoPool::info function. Add up the "in use" and + "in pool" fields for a given server. That is the total number of connections for that pool. @@ -231,9 +236,9 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); Each MongoDB server address you're connecting to gets its own connection - pool. For example, if your local hostname is "example.net", connecting + pool. For example, if your local hostname is "example.net", connecting to "example.net:27017", "localhost:27017", and "/tmp/mongodb-27017.sock" - will create three connection pools. You can see how many connection pools + will create three connection pools. You can see how many connection pools you have open using MongoPool::info. @@ -244,31 +249,34 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); - Each PHP process has a separate set of pools. PHP-FPM and Apache - generally create between 6 and a couple dozen PHP worker children. Check - your settings to see what the max number of PHP processes is that can be - spawned. + Each PHP process has a separate set of pools. PHP-FPM and Apache + generally create between 6 and a couple of dozen PHP worker children. + Check your settings to see what the max number of PHP processes is that + can be spawned. If you are using PHP-FPM, estimating the number of connections can be tricky because it will spawn more PHP-FPM workers under heavy load. To be - on the safe side, look at the max_children parameter or add up - spare_servers+start_servers (choose whichever number is higher). That's - how many PHP processes (and, thus sets of pools) you should plan for. + on the safe side, look at the max_children parameter or + add up spare_servers + start_servers + (choose whichever number is higher). That will indicate how many PHP + processes (i.e. sets of pools) you should plan for. The three variables above can be multiplied together to give the max number of connections expected: - connections_per_pool*pools_per_process*processes. Note - that connections_per_pool can be different for different + connections_per_pool * + pools_per_process * + processes. Note that + connections_per_pool can be different for different pools, so connections_per_pool should be the max. For example, suppose we're getting 30 connections per pool, 10 pools per PHP - process, and 128 PHP processes. Then we can expect 38400 connections from - this machine. Thus, we should set this machine's file descriptor limit to + process, and 128 PHP processes. Then we can expect 38400 connections from + this machine. Thus, we should set this machine's file descriptor limit to be high enough to handle all of these connections or it may run out of file descriptors. @@ -291,8 +299,8 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); - Creating new connection to the database is very slow. To minimize the number - of connections that you need to make, you can use persistent connections. A + Creating new connection to the database is very slow. To minimize the number + of connections that you need to make, you can use persistent connections. A persistent connection is saved by PHP, so you can use the same connection for multiple requests. @@ -306,7 +314,7 @@ $m = new Mongo("mongodb://username:password@/tmp/mongo-27017.sock:0/foo"); @@ -314,7 +322,7 @@ for ($i=0; $i<1000; $i++) { - It takes approximately 18 seconds to execute. If we change it to use a + It takes approximately 18 seconds to execute. If we change it to use a persistent connection: @@ -323,7 +331,7 @@ for ($i=0; $i<1000; $i++) { "x")); + $m = new MongoClient("localhost:27017", array("persist" => "x")); } ?> @@ -337,10 +345,11 @@ for ($i=0; $i<1000; $i++) { Persistent connections need an identifier string (which is "x" in the above - example) to uniquely identify them. For a persistent connection to be used, - the hostname, port, persist string, and username and password (if given) must - match an existing persistent connection. Otherwise, a new connection will be - created with this identifying information. + example) to uniquely identify them. For a persistent connection to be used, + the hostname, port, persist string, and authentication credentials (username, + password and database, if given) must match an existing persistent + connection. Otherwise, a new connection will be created with this identifying + information. Persistent connections are highly recommended and should diff --git a/reference/mongo/mongo/getslave.xml b/reference/mongo/mongo/getslave.xml index bbddbd51da..12849c2583 100644 --- a/reference/mongo/mongo/getslave.xml +++ b/reference/mongo/mongo/getslave.xml @@ -15,22 +15,23 @@ - This finds the address of the slave currently being used for reads. It is a - read-only method: it does not change anything about the internal state of the - object. + This finds the address of the secondary currently being used for reads. It is + a read-only method: it does not change anything about the internal state of + the object. When you create a connection to the database, the driver will not immediately - decide on a slave to use. Thus, after you connect, this function will return - &null; even if there are slaves available. When you first do a query with - slaveOkay set, at that point the driver will choose a slave for this - connection. At that point, this function will return the chosen slave. + decide on a secondary to use. Thus, after you connect, this function will + return &null; even if there are secondaries available. When you first do a + query with slaveOkay set, at that point the driver will choose a secondary + for this connection. At that point, this function will return the chosen + secondary. See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. @@ -43,7 +44,7 @@ &reftitle.returnvalues; - The address of the slave this connection is using for reads. + The address of the secondary this connection is using for reads. This returns &null; if this is not connected to a replica set or not yet diff --git a/reference/mongo/mongo/getslaveokay.xml b/reference/mongo/mongo/getslaveokay.xml index c1c4d2da20..b0ea05d4e4 100644 --- a/reference/mongo/mongo/getslaveokay.xml +++ b/reference/mongo/mongo/getslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongo/pooldebug.xml b/reference/mongo/mongo/pooldebug.xml index a78fedc90c..926091f394 100644 --- a/reference/mongo/mongo/pooldebug.xml +++ b/reference/mongo/mongo/pooldebug.xml @@ -44,7 +44,7 @@ The number of connections currently being used by - Mongo instances. + MongoClient instances. @@ -67,9 +67,9 @@ The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of - Mongo before we exhausted this pool (assuming no - instances of Mongo went out of scope, returning - their connections to the pool). + MongoClient before we exhausted this pool + (assuming no instances of MongoClient went out of + scope, returning their connections to the pool). A negative number means that this pool will spawn unlimited connections. diff --git a/reference/mongo/mongo/setslaveokay.xml b/reference/mongo/mongo/setslaveokay.xml index a7de3fa42a..ee2857dd3b 100644 --- a/reference/mongo/mongo/setslaveokay.xml +++ b/reference/mongo/mongo/setslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. @@ -30,8 +30,8 @@ - If reads should be sent to secondary members of a replica set for all - possible queries using this Mongo instance. + If reads should be sent to secondary members of a replica set for all + possible queries using this MongoClient instance. diff --git a/reference/mongo/mongo/switchslave.xml b/reference/mongo/mongo/switchslave.xml index cc4c3b9e9a..7be79bb16f 100644 --- a/reference/mongo/mongo/switchslave.xml +++ b/reference/mongo/mongo/switchslave.xml @@ -4,7 +4,7 @@ Mongo::switchSlave - Choose a new slave for slaveOkay reads + Choose a new secondary for slaveOkay reads @@ -15,15 +15,15 @@ - This choses a random slave for a connection to read from. It is called - automatically by the driver and should not need to be used. It calls - Mongo::getHosts (to refresh the status of hosts) and - Mongo::getSlave (to get the return value). + This choses a random secondary for a connection to read from. It is called + automatically by the driver and should not need to be used. It calls + MongoClient::getHosts (to refresh the status of hosts) + and Mongo::getSlave (to get the return value). See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. @@ -36,14 +36,15 @@ &reftitle.returnvalues; - The address of the slave this connection is using for reads. This may be the - same as the previous address as addresses are randomly chosen. It may return - only one address if only one secondary (or only the primary) is available. + The address of the secondary this connection is using for reads. This may be + the same as the previous address as addresses are randomly chosen. It may + return only one address if only one secondary (or only the primary) is + available. - For example, if we had a three member replica set with a primary, secondary, - and arbiter this method would always return the address of the secondary. - If the secondary became unavailable, this method would always return the + For example, if we had a three member replica set with a primary, secondary, + and arbiter this method would always return the address of the secondary. + If the secondary became unavailable, this method would always return the address of the primary. If the primary also became unavailable, this method would throw an exception, as an arbiter cannot handle reads. diff --git a/reference/mongo/mongoclient/construct.xml b/reference/mongo/mongoclient/construct.xml index e60c406719..c7716d86fb 100644 --- a/reference/mongo/mongoclient/construct.xml +++ b/reference/mongo/mongoclient/construct.xml @@ -162,7 +162,7 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db The name of the replica set to connect to. If this is given, the - master will be automatically be determined. This means that the + primary will be automatically be determined. This means that the driver may end up connecting to a server that was not even listed. See the replica set example below for details. @@ -380,9 +380,9 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db <function>MongoClient::__construct</function> replica set example - This example shows how to connect the driver to a replica set. It assumes + This example shows how to connect the driver to a replica set. It assumes that there is a set of three servers: sf1.example.com, sf2.example.com, and - ny1.example.com. The master could be any one of these servers. + ny1.example.com. The primary could be any one of these servers. "myReplSet")); // you only need to pass a single seed, the driver will derive the full list and -// find the master from this seed +// find the primary from this seed $m2 = new MongoClient("mongodb://ny1.example.com", array("replicaSet" => "myReplSet")); ?> ]]> - If the current master fails, the driver will figure out which secondary - server became the new master and automatically start using that connection. + If the current primary fails, the driver will figure out which secondary + server became the new primary and automatically start using that connection. Automatic failover will not work correctly if replicaSet is not specified. diff --git a/reference/mongo/mongoclient/gethosts.xml b/reference/mongo/mongoclient/gethosts.xml index ec14db63f2..0c6f340725 100644 --- a/reference/mongo/mongoclient/gethosts.xml +++ b/reference/mongo/mongoclient/gethosts.xml @@ -23,7 +23,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml index 6b378f69a9..fb6b94f23e 100644 --- a/reference/mongo/mongocollection/batchinsert.xml +++ b/reference/mongo/mongocollection/batchinsert.xml @@ -164,7 +164,7 @@ for ($i = 0; $i<100; $i++) { $users[] = array('username' => 'user'.$i, 'i' => $i); } -$mongo = new Mongo(); +$mongo = new MongoClient(); $collection = $mongo->my_db->users; $collection->drop(); diff --git a/reference/mongo/mongocollection/deleteindex.xml b/reference/mongo/mongocollection/deleteindex.xml index ff87161fa6..1315af9480 100644 --- a/reference/mongo/mongocollection/deleteindex.xml +++ b/reference/mongo/mongocollection/deleteindex.xml @@ -102,7 +102,7 @@ $db->command(array("deleteIndexes" => $collection->getName(), "index" => "superf example->indices; // create an index diff --git a/reference/mongo/mongocollection/ensureindex.xml b/reference/mongo/mongocollection/ensureindex.xml index b907a71e1c..01c30b64df 100644 --- a/reference/mongo/mongocollection/ensureindex.xml +++ b/reference/mongo/mongocollection/ensureindex.xml @@ -128,20 +128,20 @@ "safe" - Starting with driver version 1.0.4, you can specify a boolean value + Starting with driver version 1.0.4, you can specify a boolean value for checking if the index creation succeeded. The driver will throw a MongoCursorException if index creation failed. - If you are using replication and the master has changed, using "safe" - will make the driver disconnect from the master, throw and exception, - and attempt to find a new master on the next operation (your + If you are using replication and the primary has changed, using "safe" + will make the driver disconnect from the primary, throw and exception, + and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the - new master). + new primary). - If you do not use "safe" with a replica set and - the master changes, there will be no way for the driver to know about + If you do not use "safe" with a replica set and + the primary changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write. @@ -160,7 +160,7 @@ "timeout" - Integer, defaults to MongoCursor::$timeout. If + Integer, defaults to MongoCursor::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException @@ -217,8 +217,8 @@ 1.0.11 - The "safe" option will trigger a master failover, if - necessary. + The "safe" option will trigger a primary failover, + if necessary. MongoException will be thrown if the index name diff --git a/reference/mongo/mongocollection/find.xml b/reference/mongo/mongocollection/find.xml index 5f8aff2cfd..723c291efc 100644 --- a/reference/mongo/mongocollection/find.xml +++ b/reference/mongo/mongocollection/find.xml @@ -74,7 +74,7 @@ selectDB('test'); $collection = new MongoCollection($db, 'phpmanual'); @@ -123,7 +123,7 @@ array(2) { selectDB('test'); $collection = new MongoCollection($db, 'phpmanual'); @@ -162,7 +162,7 @@ array(3) { selectDB('test'); $collection = new MongoCollection($db, 'phpmanual'); @@ -202,7 +202,7 @@ array(3) { selectDB('test'); $collection = new MongoCollection($db, 'phpmanual'); diff --git a/reference/mongo/mongocollection/get.xml b/reference/mongo/mongocollection/get.xml index ab2c9af672..6c09efd26c 100644 --- a/reference/mongo/mongocollection/get.xml +++ b/reference/mongo/mongocollection/get.xml @@ -14,13 +14,13 @@ A concise syntax for getting a collection with a dot-separated name. If a - collection name contains strange characters, you may have to use + collection name contains strange characters, you may have to use MongoDB::selectCollection instead. selectDB("foo")->selectCollection("bar.baz"); @@ -32,7 +32,7 @@ $collection = $mongo->foo->bar->baz; - &reftitle.parameters; + &reftitle.parameters; @@ -44,12 +44,12 @@ $collection = $mongo->foo->bar->baz; The next string in the collection name. - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns the collection. @@ -73,4 +73,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> +--> diff --git a/reference/mongo/mongocollection/getname.xml b/reference/mongo/mongocollection/getname.xml index d67a730cb4..cce2c50aaa 100644 --- a/reference/mongo/mongocollection/getname.xml +++ b/reference/mongo/mongocollection/getname.xml @@ -13,7 +13,7 @@ - + &reftitle.parameters; &no.function.parameters; @@ -34,7 +34,7 @@ foo->bar->baz; echo "Working with collection " . $c->getName() . ".\n"; @@ -74,4 +74,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> +--> diff --git a/reference/mongo/mongocollection/getreadpreference.xml b/reference/mongo/mongocollection/getreadpreference.xml index 9213b26181..cbc64a87ef 100644 --- a/reference/mongo/mongocollection/getreadpreference.xml +++ b/reference/mongo/mongocollection/getreadpreference.xml @@ -40,9 +40,9 @@ test->users; -$c->setReadPreference(Mongo::RP_SECONDARY, array( +$c->setReadPreference(MongoClient::RP_SECONDARY, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), array(), diff --git a/reference/mongo/mongocollection/getslaveokay.xml b/reference/mongo/mongocollection/getslaveokay.xml index 149098dd5f..8eb17a7a1f 100644 --- a/reference/mongo/mongocollection/getslaveokay.xml +++ b/reference/mongo/mongocollection/getslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml index 156bd29a56..2a81fd3c9f 100644 --- a/reference/mongo/mongocollection/insert.xml +++ b/reference/mongo/mongocollection/insert.xml @@ -34,7 +34,7 @@ An array. - + options @@ -48,22 +48,22 @@ "safe" - Can be a boolean or integer, defaults to &false;. If &false;, the - program continues executing without waiting for a database response. + Can be a boolean or integer, defaults to &false;. If &false;, the + program continues executing without waiting for a database response. If &true;, the program will wait for the database response and throw a - MongoCursorException if the insert did not - succeed. + MongoCursorException if the insert did not + succeed. - If you are using replication and the master has changed, using "safe" - will make the driver disconnect from the master, throw an exception, - and attempt to find a new master on the next operation (your + If you are using replication and the primary has changed, using "safe" + will make the driver disconnect from the primary, throw an exception, + and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the - new master). + new primary). - If you do not use "safe" with a replica set and - the master changes, there will be no way for the driver to know about + If you do not use "safe" with a replica set and + the primary changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write. @@ -328,7 +328,7 @@ selectDB('test'); $collection = new MongoCollection($db, 'phpmanual'); diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml index a0d6881b12..a18c87323b 100644 --- a/reference/mongo/mongocollection/remove.xml +++ b/reference/mongo/mongocollection/remove.xml @@ -58,15 +58,15 @@ succeed. - If you are using replication and the master has changed, using "safe" - will make the driver disconnect from the master, throw and exception, - and attempt to find a new master on the next operation (your + If you are using replication and the primary has changed, using "safe" + will make the driver disconnect from the primary, throw and exception, + and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the - new master). + new primary). - If you do not use "safe" with a replica set and - the master changes, there will be no way for the driver to know about + If you do not use "safe" with a replica set and + the primary changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write. diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml index 2f2433f391..62b1e55054 100644 --- a/reference/mongo/mongocollection/save.xml +++ b/reference/mongo/mongocollection/save.xml @@ -54,15 +54,15 @@ succeed. - If you are using replication and the master has changed, using "safe" - will make the driver disconnect from the master, throw and exception, - and attempt to find a new master on the next operation (your + If you are using replication and the primary has changed, using "safe" + will make the driver disconnect from the primary, throw and exception, + and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the - new master). + new primary). - If you do not use "safe" with a replica set and - the master changes, there will be no way for the driver to know about + If you do not use "safe" with a replica set and + the primary changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write. diff --git a/reference/mongo/mongocollection/setreadpreference.xml b/reference/mongo/mongocollection/setreadpreference.xml index be08ee4003..9cf000ace2 100644 --- a/reference/mongo/mongocollection/setreadpreference.xml +++ b/reference/mongo/mongocollection/setreadpreference.xml @@ -34,12 +34,12 @@ 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( +$c->setReadPreference(MongoClient::RP_NEAREST, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), )); diff --git a/reference/mongo/mongocollection/setslaveokay.xml b/reference/mongo/mongocollection/setslaveokay.xml index 2bea6c5142..a4fd548446 100644 --- a/reference/mongo/mongocollection/setslaveokay.xml +++ b/reference/mongo/mongocollection/setslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongocollection/tostring.xml b/reference/mongo/mongocollection/tostring.xml index 7dfd1f31ed..56872128e5 100644 --- a/reference/mongo/mongocollection/tostring.xml +++ b/reference/mongo/mongocollection/tostring.xml @@ -13,7 +13,7 @@ - + &reftitle.parameters; &no.function.parameters; @@ -34,7 +34,7 @@ foo->bar->baz; echo "Working with collection $c1."; @@ -74,4 +74,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> +--> diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml index a88d9b460d..9ac57ab7b4 100644 --- a/reference/mongo/mongocollection/update.xml +++ b/reference/mongo/mongocollection/update.xml @@ -95,15 +95,15 @@ succeed. - If you are using replication and the master has changed, using "safe" - will make the driver disconnect from the master, throw an exception, - and attempt to find a new master on the next operation (your + If you are using replication and the primary has changed, using "safe" + will make the driver disconnect from the primary, throw an exception, + and attempt to find a new primary on the next operation (your application must decide whether or not to retry the operation on the - new master). + new primary). - If you do not use "safe" with a replica set and - the master changes, there will be no way for the driver to know about + If you do not use "safe" with a replica set and + the primary changes, there will be no way for the driver to know about the change so it will continuously and silently fail to write. diff --git a/reference/mongo/mongoconnectionexception.xml b/reference/mongo/mongoconnectionexception.xml index 728c109ef6..9342feb2bd 100644 --- a/reference/mongo/mongoconnectionexception.xml +++ b/reference/mongo/mongoconnectionexception.xml @@ -66,7 +66,7 @@ couldn't determine master - Neither server in a paired connection appeared to be master. + No server in a replica set connection was identified as the primary. diff --git a/reference/mongo/mongocursor.xml b/reference/mongo/mongocursor.xml index d7e3327244..baa4a9752d 100644 --- a/reference/mongo/mongocursor.xml +++ b/reference/mongo/mongocursor.xml @@ -149,8 +149,8 @@ $cursor->skip(4); If the query should have the "slaveOkay" flag set, which allows reads on - the slave (slaves are, by default, just for backup and unreadable). Can - be overridden with MongoCursor::slaveOkay. + the secondary (secondaries are, by default, just for backup and not + queried). Can be overridden with MongoCursor::slaveOkay. diff --git a/reference/mongo/mongocursor/awaitdata.xml b/reference/mongo/mongocursor/awaitdata.xml index 4d0067d1f0..8cc59b0b3c 100644 --- a/reference/mongo/mongocursor/awaitdata.xml +++ b/reference/mongo/mongocursor/awaitdata.xml @@ -33,13 +33,13 @@ If the cursor should wait for more data to become available. - + - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns this cursor. @@ -65,7 +65,7 @@ 'seta' ) ); +$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) ); $c = $m->local->selectCollection( 'oplog.rs' ); $cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) ); $cursor->tailable( true ); diff --git a/reference/mongo/mongocursor/batchsize.xml b/reference/mongo/mongocursor/batchsize.xml index 2d13781752..339a9e22b7 100644 --- a/reference/mongo/mongocursor/batchsize.xml +++ b/reference/mongo/mongocursor/batchsize.xml @@ -101,7 +101,7 @@ &reftitle.examples; - <function>Mongo::batchSize</function> and combinations with + <title><function>MongoCursor::batchSize</function> and combinations with <function>MongoCursor::limit</function> public MongoCursor::__construct - Mongoconnection + MongoClientconnection stringns arrayqueryarray() arrayfieldsarray() diff --git a/reference/mongo/mongocursor/doquery.xml b/reference/mongo/mongocursor/doquery.xml index c92f92be27..b2bc60c5ac 100644 --- a/reference/mongo/mongocursor/doquery.xml +++ b/reference/mongo/mongocursor/doquery.xml @@ -74,8 +74,8 @@ <function>MongoCursor::doQuery</function> example - You could override this function to attempt a query on a slave and, if that - fails, try it again on the master. + You could override this function to attempt a query on a secondary and, if + that fails, try it again on the primary. test->users->find(); -$cursor->setReadPreference(Mongo::RP_SECONDARY, array( +$cursor->setReadPreference(MongoClient::RP_SECONDARY, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), array(), diff --git a/reference/mongo/mongocursor/info.xml b/reference/mongo/mongocursor/info.xml index 6c6c02727e..70784e5af3 100644 --- a/reference/mongo/mongocursor/info.xml +++ b/reference/mongo/mongocursor/info.xml @@ -75,7 +75,7 @@ foo->bar->find(array("x" => 4), array("y" => false)); var_dump($cursor->info()); diff --git a/reference/mongo/mongocursor/setflag.xml b/reference/mongo/mongocursor/setflag.xml index 001e0887cb..9924e366a7 100644 --- a/reference/mongo/mongocursor/setflag.xml +++ b/reference/mongo/mongocursor/setflag.xml @@ -76,7 +76,7 @@ 'seta' ) ); +$m = new MongoClient( 'mongodb://localhost:13000', array( 'replSet' => 'seta' ) ); $c = $m->local->selectCollection( 'oplog.rs' ); $cursor = $c->find( array( 'ns' => 'demo.article', 'op' => 'i' ) ); $cursor->setFlag( 1, true ); // sets the tailable flag diff --git a/reference/mongo/mongocursor/setreadpreference.xml b/reference/mongo/mongocursor/setreadpreference.xml index 4cf460dd72..d930f8d595 100644 --- a/reference/mongo/mongocursor/setreadpreference.xml +++ b/reference/mongo/mongocursor/setreadpreference.xml @@ -35,12 +35,12 @@ 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( +$cursor->setReadPreference(MongoClient::RP_NEAREST, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), )); diff --git a/reference/mongo/mongocursor/slaveokay.xml b/reference/mongo/mongocursor/slaveokay.xml index 0f59092acf..3ce19ca347 100644 --- a/reference/mongo/mongocursor/slaveokay.xml +++ b/reference/mongo/mongocursor/slaveokay.xml @@ -4,7 +4,7 @@ MongoCursor::slaveOkay - Sets whether this query can be done on a slave + Sets whether this query can be done on a secondary @@ -14,7 +14,7 @@ boolokaytrue - Calling this will make the driver route reads to slaves if: + Calling this will make the driver route reads to secondaries if: @@ -23,13 +23,13 @@ - You created a Mongo instance using the option + You created a MongoClient instance using the option "replicaSet" => "setName" and - There is a healthy slave that can be reached by the driver. + There is a healthy secondary that can be reached by the driver. @@ -38,11 +38,11 @@ server field will show which server the query was sent to. - Note that you should use this function even if you do not use the automatic - routing to slaves. If you connect directly to a secondary in a replica set, - you still need to call this function, which basically tells the database that - you are aware that you might be getting older data and you're okay with that. - If you do not call this, you'll get "not master" errors when you try to + Note that you should use this function even if you do not use the automatic + routing to secondaries. If you connect directly to a secondary in a replica + set, you still need to call this function, which basically tells the database + that you are aware that you might be getting older data and you're okay with + that. If you do not call this, you'll get "not master" errors when you try to query. @@ -64,7 +64,7 @@ - If it is okay to query the slave. + If it is okay to query the secondary. @@ -96,18 +96,18 @@ MongoCursor::$slaveOkay = false; -// cannot query slave +// cannot query secondary $cursor = $collection->find(); -// can query slave +// can query secondary $cursor = $collection->find()->slaveOkay(); MongoCursor::$slaveOkay = true; -// can query slave +// can query secondary $cursor = $collection->find(); -// cannot query slave +// cannot query secondary $cursor = $collection->find()->slaveOkay(false); ?> diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml index e508c3158e..d9cda78b35 100644 --- a/reference/mongo/mongocursorexception.xml +++ b/reference/mongo/mongocursorexception.xml @@ -17,8 +17,8 @@ just queries. Writes, commands, and any other operation that sends information to the database and waits for a response can throw a MongoCursorException. The only exception is - new Mongo() (creating a new connection), which will only - throw MongoConnectionExceptions. + new MongoClient() (creating a new connection), which will + only throw MongoConnectionExceptions. @@ -372,10 +372,10 @@ catch (MongoCursorException $e) { Codes: 10107, 13435, and 10058 - Not master errors, piped through by the database. Each of these will - cause the driver to disconnect and attempt to find a new master. The + Not master errors, piped through by the database. ach of these will + cause the driver to disconnect and attempt to find a new primary. The actual error you get on failover may not be a "not master" error, - depending on when the change in master occurs. + depending on when the change in primary occurs. diff --git a/reference/mongo/mongodb.xml b/reference/mongo/mongodb.xml index 8bc211d1b5..24cf015e6f 100644 --- a/reference/mongo/mongodb.xml +++ b/reference/mongo/mongodb.xml @@ -18,7 +18,7 @@ selectDB("example"); ?> @@ -149,21 +149,22 @@ $db = $m->selectDB("example"); MongoCollection::update, MongoCollection::remove, MongoCollection::save, and - MongoCollection::ensureIndex all support safe - options). With the default value (1), a safe operation will return once - the database server has the operation. If the server goes down before - the operation has been replicated to a slave, it is possible to lose the - operation forever. Thus, you can specify w to be - higher than one and guarantee that at least one slave has the operation - before it is considered successful. + MongoCollection::ensureIndex all support safe + options). With the default value (1), a safe operation will return once + the database server has the operation. If the server goes down before + the operation has been replicated to a secondary, it is possible to lose + the operation forever. Thus, you can specify w to be + higher than one and guarantee that at least one secondary has the + operation before it is considered successful. - For example, if w is 2, the main server and one slave - must have a record of the operation or the driver will throw a - MongoCursorException. It is tempting to set - w to the total number of slaves + master, but then if - one slave is down the op will fail and an exception will be thrown, so - usually w=2 is safest (master+1 slave). + For example, if w is 2, the primary and one secondary + must have a record of the operation or the driver will throw a + MongoCursorException. It is tempting to set + w to the total number of secondaries + primary, but + then if one secondary is down the operation will fail and an exception + will be thrown, so usually w=2 is safest (primary and + one secondary). diff --git a/reference/mongo/mongodb/authenticate.xml b/reference/mongo/mongodb/authenticate.xml index 591e4f1d10..8945230a87 100644 --- a/reference/mongo/mongodb/authenticate.xml +++ b/reference/mongo/mongodb/authenticate.xml @@ -14,17 +14,17 @@ stringpassword - This method causes its connection to be authenticated. If authentication is - enabled for the database server (it's not, by default), you need to log in + This method causes its connection to be authenticated. If authentication is + enabled for the database server (it's not, by default), you need to log in before the database will allow you to do anything. - In general, you should use the authenticate built into - Mongo::__construct in preference to this method. If you - authenticate on connection and the connection drops and reconnects during - your session, you'll be reauthenticated. If you manually authenticated using - this method and the connection drops, you'll have to call this method again - once you're reconnected. + In general, you should use the authenticate built into + MongoClient::__construct in preference to this method. + If you authenticate on connection and the connection drops and reconnects + during your session, you'll be reauthenticated. If you manually + authenticated using this method and the connection drops, you'll have to call + this method again once you're reconnected. This method is identical to running: @@ -39,7 +39,7 @@ $nonce = $db->command(array("getnonce" => 1)); $saltedHash = md5($nonce["nonce"]."${username}${hash}"); -$result = $db->command(array("authenticate" => 1, +$result = $db->command(array("authenticate" => 1, "user" => $username, "nonce" => $nonce["nonce"], "key" => $saltedHash @@ -50,7 +50,7 @@ $result = $db->command(array("authenticate" => 1, - Once a connection has been authenticated, it can only be un-authenticated by + Once a connection has been authenticated, it can only be un-authenticated by using the "logout" database command: command(array("logout" => 1)); The username. - + password @@ -86,12 +86,12 @@ $db->command(array("logout" => 1)); The password (in plaintext). - + - &reftitle.returnvalues; + &reftitle.returnvalues; Returns database response. If the login was successful, it will return @@ -165,4 +165,4 @@ End: vim600: syn=xml fen fdm=syntax fdl=2 si vim: et tw=78 syn=sgml vi: ts=1 sw=1 ---> +--> diff --git a/reference/mongo/mongodb/command.xml b/reference/mongo/mongodb/command.xml index b62f44b9d0..ab3c53d73f 100644 --- a/reference/mongo/mongodb/command.xml +++ b/reference/mongo/mongodb/command.xml @@ -62,7 +62,7 @@ public function command($data) { "timeout" - Integer, defaults to Mongo::$timeout. If + Integer, defaults to MongoClient::$timeout. If "safe" is set, this sets how long (in milliseconds) for the client to wait for a database response. If the database does not respond within the timeout period, a MongoCursorTimeoutException diff --git a/reference/mongo/mongodb/construct.xml b/reference/mongo/mongodb/construct.xml index cf641a4cba..532dcceef8 100644 --- a/reference/mongo/mongodb/construct.xml +++ b/reference/mongo/mongodb/construct.xml @@ -11,23 +11,23 @@ &reftitle.description; public MongoDB::__construct - Mongoconn + MongoClientconn stringname - This method is not meant to be called directly. The preferred way to create - an instance of MongoDB is through Mongo::__get or - Mongo::selectDB. + This method is not meant to be called directly. The preferred way to create + an instance of MongoDB is through MongoClient::__get or + MongoClient::selectDB. - If you're ignoring the previous paragraph and want to call it directly you + If you're ignoring the previous paragraph and want to call it directly you can do so: @@ -40,7 +40,7 @@ $db = new MongoDB($m, 'mydbname'); mydbname; // or, if the name contains weird characters: @@ -51,14 +51,14 @@ $db = $m->selectDB('my,db:name'); ]]> - + &reftitle.parameters; - Mongo + MongoClient conn @@ -66,7 +66,7 @@ $db = $m->selectDB('my,db:name'); Database connection. - + name @@ -76,7 +76,7 @@ $db = $m->selectDB('my,db:name'); Database name. - + diff --git a/reference/mongo/mongodb/get.xml b/reference/mongo/mongodb/get.xml index 409e83eedb..d0cf059899 100644 --- a/reference/mongo/mongodb/get.xml +++ b/reference/mongo/mongodb/get.xml @@ -20,7 +20,7 @@ selectDB("foo")->selectCollection("bar"); diff --git a/reference/mongo/mongodb/getreadpreference.xml b/reference/mongo/mongodb/getreadpreference.xml index 636026a71d..3c7535137e 100644 --- a/reference/mongo/mongodb/getreadpreference.xml +++ b/reference/mongo/mongodb/getreadpreference.xml @@ -40,9 +40,9 @@ test; -$db->setReadPreference(Mongo::RP_SECONDARY, array( +$db->setReadPreference(MongoClient::RP_SECONDARY, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), array(), diff --git a/reference/mongo/mongodb/getslaveokay.xml b/reference/mongo/mongodb/getslaveokay.xml index 9d6be6833f..96282b2d2c 100644 --- a/reference/mongo/mongodb/getslaveokay.xml +++ b/reference/mongo/mongodb/getslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongodb/listcollections.xml b/reference/mongo/mongodb/listcollections.xml index 78e35600e8..c99197dce6 100644 --- a/reference/mongo/mongodb/listcollections.xml +++ b/reference/mongo/mongodb/listcollections.xml @@ -74,7 +74,7 @@ selectDB("sample"); $list = $db->listCollections(); diff --git a/reference/mongo/mongodb/setreadpreference.xml b/reference/mongo/mongodb/setreadpreference.xml index d02d63ebaa..3264ff21b6 100644 --- a/reference/mongo/mongodb/setreadpreference.xml +++ b/reference/mongo/mongodb/setreadpreference.xml @@ -34,12 +34,12 @@ 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( +$db->setReadPreference(MongoClient::RP_NEAREST, array( array('dc' => 'east', 'use' => 'reporting'), array('dc' => 'west'), )); diff --git a/reference/mongo/mongodb/setslaveokay.xml b/reference/mongo/mongodb/setslaveokay.xml index b854b4ff78..32a38f2c1d 100644 --- a/reference/mongo/mongodb/setslaveokay.xml +++ b/reference/mongo/mongodb/setslaveokay.xml @@ -16,7 +16,7 @@ See the query section of this manual for - information on distributing reads to slaves. + information on distributing reads to secondaries. diff --git a/reference/mongo/mongoid/tostring.xml b/reference/mongo/mongoid/tostring.xml index 22b96dd911..613e07ecc4 100644 --- a/reference/mongo/mongoid/tostring.xml +++ b/reference/mongo/mongoid/tostring.xml @@ -35,7 +35,7 @@ selectDB("foo")->selectCollection("bar"); $collection->insert(array( "x" => "y" )); diff --git a/reference/mongo/mongolog/setcallback.xml b/reference/mongo/mongolog/setcallback.xml index 6bd7c74dfd..fb091d10e6 100644 --- a/reference/mongo/mongolog/setcallback.xml +++ b/reference/mongo/mongolog/setcallback.xml @@ -121,7 +121,7 @@ MongoLog::setLevel(MongoLog::ALL); MongoLog::setModule(MongoLog::ALL); MongoLog::setCallback("callback"); -new Mongo(); +new MongoClient(); ?> ]]> diff --git a/reference/mongo/mongopool/info.xml b/reference/mongo/mongopool/info.xml index 64672be52b..659b8cc10c 100644 --- a/reference/mongo/mongopool/info.xml +++ b/reference/mongo/mongopool/info.xml @@ -60,9 +60,9 @@ The number of connections that could be created by this pool. For example, suppose a pool had 5 connections remaining and 3 connections in the pool. We could create 8 new instances of - Mongo before we exhausted this pool (assuming no - instances of Mongo went out of scope, returning - their connections to the pool). + MongoClient before we exhausted this pool + (assuming no instances of MongoClient went out of + scope, returning their connections to the pool). A negative number means that this pool will spawn unlimited connections. diff --git a/reference/mongo/queries.xml b/reference/mongo/queries.xml index ec12bb8c04..dbb264fa0e 100644 --- a/reference/mongo/queries.xml +++ b/reference/mongo/queries.xml @@ -4,7 +4,7 @@ Querying
- Distributing queries to slaves + Distributing queries to secondaries 1.1.0+ @@ -12,15 +12,15 @@ If you are using a replica set and version 1.1.0 or above of the driver, the driver can automatically route reads to - slaves. This behavior does not exist in earlier versions of the driver and - cannot be used with "normal" master-slave. + secondaries. This behavior does not exist in earlier versions of the driver + and cannot be used with legacy master-slave clusters. - By default, the driver will send all queries to the master. If you set the - "slaveOkay" option, the driver will send all queries to a non-primary server, - if possible. The "slaveOkay" option can be set at every "level": + By default, the driver will send all queries to the primary. If you set the + "slaveOkay" option, the driver will send read queries to a secondary server, + if possible. The "slaveOkay" option can be set at every "level": connection, database, collection, and @@ -42,19 +42,19 @@ $cursor = $c->find(); - then the query will be executed against a slave (the collection inherited + then the query will be executed against a secondary (the collection inherited "slaveOkay" from the database and the cursor inherited it from the collection).
- How slaves are chosen + How secondaries are chosen - Each instance of Mongo chooses its own slave using - the available slave with the lowest ping time. So, if we had a PHP client - in Europe and one in Australia and we had one secondary in each of these - data centers, we could do: + Each instance of MongoClient chooses its own + secondary using the available secondary with the lowest ping time. So, if we + had a PHP client in Europe and one in Australia and we had one secondary in + each of these data centers, we could do: find(); // P is the primary // on the Australian client -$m1 = new Mongo("mongodb://P", array("replicaSet" => 'setName')); +$m1 = new MongoClient("mongodb://P", array("replicaSet" => 'setName')); $m1->foo->bar->find()->slaveOkay()->getNext(); -echo "m1's slave is ".$m1->getSlave()."\n"; +echo "m1's secondary is ".$m1->getSlave()."\n"; // on the European client -$m2 = new Mongo("mongodb://P", array("replicaSet" => 'setName')); +$m2 = new MongoClient("mongodb://P", array("replicaSet" => 'setName')); $m2->foo->bar->find()->slaveOkay()->getNext(); -echo "m2's slave is ".$m2->getSlave()."\n"; +echo "m2's secondary is ".$m2->getSlave()."\n"; ?> ]]> @@ -79,32 +79,32 @@ echo "m2's slave is ".$m2->getSlave()."\n"; we'd probably end up with something like: -m1's slave is: australianHost -m2's slave is: europeanHost +m1's secondary is: australianHost +m2's secondary is: europeanHost - Note that we have to do a query before a slave is chosen: slaves are chosen - lazily by the driver. Mongo::getSlave will return - &null; until a slave is used. + Note that we have to do a query before a secondary is chosen: secondaries + are chosen lazily by the driver. Mongo::getSlave will + return &null; until a secondary is used. You can see what the driver thinks is the current status of the set members - by running Mongo::getHosts. + by running MongoClient::getHosts. If no non-primary server is readable, the driver will send reads to the primary (even if "slaveOkay" is set). A server is considered readable if its state is 2 (SECONDARY) and its health is 1. You can check - this with Mongo::getHosts. + this with MongoClient::getHosts. If you enjoy twiddling knobs that you probably shouldn't mess with, you can - request the driver to use a different slave by calling - Mongo::switchSlave. This may choose a new slave + request the driver to use a different secondary by calling + Mongo::switchSlave. This may choose a new secondary (if one is available) and shouldn't be used unless you know what you're doing. @@ -119,9 +119,9 @@ m2's slave is: europeanHost - The health and state of a slave is checked every 5 seconds or when the next - operation occurs after 5 seconds. It will also recheck the configuration - when the driver has a problem reaching a server. + The health and state of a secondary is checked every 5 seconds or when the + next operation occurs after 5 seconds. It will also recheck the + configuration when the driver has a problem reaching a server. diff --git a/reference/mongo/readpreferences.xml b/reference/mongo/readpreferences.xml index dfeb37bd3a..51ec8cf234 100644 --- a/reference/mongo/readpreferences.xml +++ b/reference/mongo/readpreferences.xml @@ -23,16 +23,16 @@ 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. + All read preference modes except MongoClient::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 MongoClient::RP_PRIMARY. - Mongo::RP_PRIMARY + MongoClient::RP_PRIMARY All read operations use only the current replica set primary. This is the @@ -41,12 +41,12 @@ This mode is incompatible with use of tag sets. Specifying a tag set with - Mongo::RP_PRIMARY will result in an error. + MongoClient::RP_PRIMARY will result in an error. - Mongo::RP_PRIMARY_PREFERRED + MongoClient::RP_PRIMARY_PREFERRED In most situations, operations read from the primary member of the set. @@ -63,14 +63,14 @@ 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 + MongoClient::RP_PRIMARY_PREFERRED will send queries to secondaries. - Mongo::RP_SECONDARY + MongoClient::RP_SECONDARY Operations read only from the secondary members of the set. If no @@ -85,13 +85,13 @@ 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 + random secondary from among the nearest group. If no secondaries have matching tags, the read operation will produce an exception. - Mongo::RP_SECONDARY_PREFERRED + MongoClient::RP_SECONDARY_PREFERRED In most situations, operations read from secondary members, but in @@ -107,12 +107,12 @@ - Mongo::RP_NEAREST + MongoClient::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 + selection process. Reads in the MongoClient::RP_NEAREST + mode do not consider the member's type and may read from both primaries and secondaries. @@ -128,8 +128,8 @@ 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. + MongoClient::RP_NEAREST mode prefers low latency reads + over a member's primary or secondary status. @@ -151,38 +151,39 @@ - Mongo::RP_PRIMARY_PREFERRED + MongoClient::RP_PRIMARY_PREFERRED - Mongo::RP_SECONDARY + MongoClient::RP_SECONDARY - Mongo::RP_SECONDARY_PREFERRED + MongoClient::RP_SECONDARY_PREFERRED - Mongo::RP_NEAREST + MongoClient::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. + You cannot specify tag sets with the + MongoClient::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. + MongoClient::__construct, which uses a query string + syntax, or via setter methods on the core classes, which use an array syntax + for tag sets. When specifying read preference modes in a query string, the names @@ -212,13 +213,13 @@ // 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')); +$m = new MongoClient($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')); +$m = new MongoClient($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 @@ -226,7 +227,7 @@ $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')); +$m = new MongoClient($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 @@ -235,7 +236,7 @@ $uri .= '?readPreference=nearest'; $uri .= '&readPreferenceTags=dc:east'; $uri .= '&readPreferenceTags=dc:west'; $uri .= '&readPreferenceTags='; -$m = new Mongo($uri, array('replicaSet' => 'rs')); +$m = new MongoClient($uri, array('replicaSet' => 'rs')); ]]> @@ -247,28 +248,28 @@ $m = new Mongo($uri, array('replicaSet' => 'rs')); 'rs', )); // Prefer the nearest server with no tag preference -$m->setReadPreference(Mongo::RP_NEAREST, array()); +$m->setReadPreference(MongoClient::RP_NEAREST, array()); // Prefer the nearest server in the "east" data center -$m->setReadPreference(Mongo::RP_NEAREST, array( +$m->setReadPreference(MongoClient::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( +$m->setReadPreference(MongoClient::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( +$m->setReadPreference(MongoClient::RP_NEAREST, array( array('dc' => 'east'), array('dc' => 'west'), array(), diff --git a/reference/mongo/tutorial.xml b/reference/mongo/tutorial.xml index 645b68760c..b75ffcc05c 100644 --- a/reference/mongo/tutorial.xml +++ b/reference/mongo/tutorial.xml @@ -17,7 +17,7 @@ comedy; @@ -64,9 +64,9 @@ XKCD ]]> @@ -83,9 +83,9 @@ $connection = new Mongo( "example.com:65432" ); // connect to a remote host at a covers different types of connections. - The API documentation on the Mongo class and - Mongo::__construct give a comprehensive look at all - possible options with a number of examples. + The API documentation on the MongoClient class and + MongoClient::__construct give a comprehensive look at + all possible options with a number of examples.
diff --git a/reference/mongo/writes.xml b/reference/mongo/writes.xml index 9908c0df7d..67ae70467f 100644 --- a/reference/mongo/writes.xml +++ b/reference/mongo/writes.xml @@ -68,10 +68,10 @@ $collection->insert($someDoc, array("safe" => 3)); ]]> - If you specify "safe" => N, the MongoDB server will + If you specify "safe" => N, the MongoDB server will make sure that at least N servers have a copy of the write - before returning success. So, if N is 3, the master and - two slaves must have the write. + before returning success. So, if N is 3, the primary and + two secondaries must acknowledge the write.