diff --git a/language-snippets.ent b/language-snippets.ent index 17400fa763..04e32eaaa2 100644 --- a/language-snippets.ent +++ b/language-snippets.ent @@ -1721,3 +1721,7 @@ tag sets, where each tag set is itself an array of criteria used to match tags on replica set members. '> Returns &true; on success, or &false; otherwise.'> +"w"See WriteConcerns. The default value for MongoClient is 1.'> +"fsync"Boolean, defaults to &false;. Forces the insert to be synced to disk before returning success. If &true;, an acknowledged insert is implied and will override setting w to 0.'> +"timeout"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 will be thrown.'> +"safe"Deprecated. Please use the WriteConcern w option.'> diff --git a/reference/mongo/mongoclient/construct.xml b/reference/mongo/mongoclient/construct.xml index c7716d86fb..5e75ce4d83 100644 --- a/reference/mongo/mongoclient/construct.xml +++ b/reference/mongo/mongoclient/construct.xml @@ -191,8 +191,9 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db "w" - The w option specifies the write concern for the - driver, which determines how long the driver blocks when writing. The + The w option specifies the + Write Concern for the driver, + which determines how long the driver blocks when writing. The default value is 1. @@ -211,11 +212,6 @@ mongodb://[username:password@]host1[:port1][,host2[:port2:],...]/db and ensures that the write operation has been applied to the majority (more than 50%) of the participating nodes. - - See the core - documentation on replica sets for more information. - diff --git a/reference/mongo/mongocollection/aggregate.xml b/reference/mongo/mongocollection/aggregate.xml index 6cf4b7e227..c2c03cb60a 100644 --- a/reference/mongo/mongocollection/aggregate.xml +++ b/reference/mongo/mongocollection/aggregate.xml @@ -125,7 +125,7 @@ $data = array ( 'foo' => 5, ), ); -$d = $c->insert($data, array("safe" => true)); +$d = $c->insert($data, array("w" => 1)); $ops = array( array( diff --git a/reference/mongo/mongocollection/batchinsert.xml b/reference/mongo/mongocollection/batchinsert.xml index fb6b94f23e..025e226546 100644 --- a/reference/mongo/mongocollection/batchinsert.xml +++ b/reference/mongo/mongocollection/batchinsert.xml @@ -38,34 +38,9 @@ Options for the inserts. - - - "safe" - - - 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. - - - If safe is an integer, will replicate the - insert to that many machines before returning success (or throw an - exception if the replication times out, see wtimeout). This overrides - the w variable set on the collection. - - - - - "fsync" - - - Boolean, defaults to &false;. Forces the insert to be synced to - disk before returning success. If &true;, a safe insert is implied - and will override setting safe to &false;. - - + &mongo.writes.parameters.writeconcern; + &mongo.writes.parameters.fsync; + &mongo.writes.parameters.timeout; "continueOnError" @@ -80,6 +55,7 @@ MongoDB::lastError. + &mongo.writes.parameters.safe; diff --git a/reference/mongo/mongocollection/distinct.xml b/reference/mongo/mongocollection/distinct.xml index c99da91cfd..2a3ce59ab1 100644 --- a/reference/mongo/mongocollection/distinct.xml +++ b/reference/mongo/mongocollection/distinct.xml @@ -63,7 +63,7 @@ $c = $db->distinct; $c->insert(array("stuff" => "bar", "zip-code" => 10010)); $c->insert(array("stuff" => "foo", "zip-code" => 10010)); -$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("safe" => true)); +$c->insert(array("stuff" => "bar", "zip-code" => 99701), array("w" => 1)); $retval = $c->distinct("zip-code"); var_dump($retval); diff --git a/reference/mongo/mongocollection/ensureindex.xml b/reference/mongo/mongocollection/ensureindex.xml index 01c30b64df..c348fdc79d 100644 --- a/reference/mongo/mongocollection/ensureindex.xml +++ b/reference/mongo/mongocollection/ensureindex.xml @@ -51,6 +51,7 @@ array("optionname" => <boolean>, ...). Currently supported options are: + &mongo.writes.parameters.writeconcern; "unique" @@ -123,28 +124,6 @@ - - - "safe" - - - 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 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 primary). - - - 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. - - "name" @@ -155,18 +134,8 @@ about the index name being too long. - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.timeout; + &mongo.writes.parameters.safe; diff --git a/reference/mongo/mongocollection/findandmodify.xml b/reference/mongo/mongocollection/findandmodify.xml index bdd55ae079..50cb7ff5e7 100644 --- a/reference/mongo/mongocollection/findandmodify.xml +++ b/reference/mongo/mongocollection/findandmodify.xml @@ -165,7 +165,7 @@ $col->insert(array( "priority" => 2, "tasks" => array( "run marketing report", "email report" ) ), - array("safe" => true) + array("w" => 1) ); diff --git a/reference/mongo/mongocollection/insert.xml b/reference/mongo/mongocollection/insert.xml index 2a81fd3c9f..2fd95130ed 100644 --- a/reference/mongo/mongocollection/insert.xml +++ b/reference/mongo/mongocollection/insert.xml @@ -43,58 +43,10 @@ Options for the insert. - - - "safe" - - - 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. - - - 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 primary). - - - 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. - - - If safe is an integer, will replicate the - insert to that many machines before returning success (or throw an - exception if the replication times out, see wtimeout). This overrides - the w variable set on the collection. - - - - - "fsync" - - - Boolean, defaults to &false;. Forces the insert to be synced to - disk before returning success. If &true;, a safe insert is implied - and will override setting safe to &false;. - - - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.writeconcern; + &mongo.writes.parameters.fsync; + &mongo.writes.parameters.timeout; + &mongo.writes.parameters.safe; @@ -107,7 +59,7 @@ &reftitle.returnvalues; Returns an array containing the status of the insertion if the - "safe" option is set. Otherwise, returns &true; if the + "w" option is set. Otherwise, returns &true; if the inserted array is not empty (a MongoException will be thrown if the inserted array is empty). @@ -239,11 +191,11 @@ Throws MongoCursorException if the - "safe" option is set and the operation fails. + "w" option is set and the operation fails. Throws MongoCursorTimeoutException if the - "safe" option is set and the operation takes longer than + "w" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server; it is a client-side timeout. @@ -265,8 +217,9 @@ 1.3.0 The options parameter no longer accepts a boolean - to signify a safe insert. Instead, this now has to be done with - array('safe' => true). + to signify a acknowledged write. Instead, this now has to be done with + array('w' => 1) (The default behaviour of + MongoClient). @@ -363,23 +316,23 @@ array(12) { - <function>MongoCollection::insert</function> safe example + <function>MongoCollection::insert</function> acknowledged write example This example shows inserting two elements with the same _id, which causes a MongoCursorException to be thrown, as - safe was set. + w was set. "Joe", "age" => 20); -$collection->insert($person, true); +$collection->insert($person); // now $person has an _id field, so if we save it // again, we will get an exception try { - $collection->insert($person, true); + $collection->insert($person, array("w" => 1)); } catch(MongoCursorException $e) { echo "Can't save the same person twice!\n"; } diff --git a/reference/mongo/mongocollection/remove.xml b/reference/mongo/mongocollection/remove.xml index a18c87323b..46f56dbc5c 100644 --- a/reference/mongo/mongocollection/remove.xml +++ b/reference/mongo/mongocollection/remove.xml @@ -38,6 +38,7 @@ Options for remove. + &mongo.writes.parameters.writeconcern; "justOne" @@ -46,58 +47,9 @@ Remove at most one record matching this criteria. - - - "safe" - - - 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 update did not - succeed. - - - 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 primary). - - - 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. - - - If safe is an integer, will replicate the - update to that many machines before returning success (or throw an - exception if the replication times out, see wtimeout). This overrides - the w variable set on the collection. - - - - - "fsync" - - - Boolean, defaults to &false;. Forces the update to be synced to - disk before returning success. If &true;, a safe update is implied - and will override setting safe to &false;. - - - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.fsync; + &mongo.writes.parameters.timeout; + &mongo.writes.parameters.safe; @@ -110,7 +62,7 @@ &reftitle.returnvalues; Returns an array containing the status of the removal if the - "safe" option is set. Otherwise, returns &true;. + "w" option is set. Otherwise, returns &true;. Fields in the status array are described in the documentation for @@ -122,11 +74,11 @@ &reftitle.errors; Throws MongoCursorException if the - "safe" option is set and the operation fails. + "w" option is set and the operation fails. Throws MongoCursorTimeoutException if the - "safe" option is set and the operation takes longer than + "w" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server; it is a client-side timeout. diff --git a/reference/mongo/mongocollection/save.xml b/reference/mongo/mongocollection/save.xml index 62b1e55054..1b72df8451 100644 --- a/reference/mongo/mongocollection/save.xml +++ b/reference/mongo/mongocollection/save.xml @@ -42,58 +42,10 @@ Options for the save. - - - "safe" - - - 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. - - - 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 primary). - - - 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. - - - If safe is an integer, will replicate the - insert to that many machines before returning success (or throw an - exception if the replication times out, see wtimeout). This overrides - the w variable set on the collection. - - - - - "fsync" - - - Boolean, defaults to &false;. Forces the insert to be synced to - disk before returning success. If &true;, a safe insert is implied - and will override setting safe to &false;. - - - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.writeconcern; + &mongo.writes.parameters.fsync; + &mongo.writes.parameters.timeout; + &mongo.writes.parameters.safe; diff --git a/reference/mongo/mongocollection/update.xml b/reference/mongo/mongocollection/update.xml index 9ac57ab7b4..e58538e928 100644 --- a/reference/mongo/mongocollection/update.xml +++ b/reference/mongo/mongocollection/update.xml @@ -51,6 +51,7 @@ array("optionname" => <boolean>, ...). Currently supported options are: + &mongo.writes.parameters.writeconcern; "upsert" @@ -83,58 +84,9 @@ may change its default behavior at some point in the future. - - - "safe" - - - 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 update did not - succeed. - - - 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 primary). - - - 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. - - - If safe is an integer, will replicate the - update to that many machines before returning success (or throw an - exception if the replication times out, see wtimeout). This overrides - the w variable set on the collection. - - - - - "fsync" - - - Boolean, defaults to &false;. Forces the update to be synced to - disk before returning success. If &true;, a safe update is implied - and will override setting safe to &false;. - - - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.fsync; + &mongo.writes.parameters.timeout; + &mongo.writes.parameters.safe; @@ -147,7 +99,7 @@ &reftitle.returnvalues; Returns an array containing the status of the update if the - "safe" option is set. Otherwise, returns &true;. + "w" option is set. Otherwise, returns &true;. Fields in the status array are described in the documentation for @@ -159,11 +111,11 @@ &reftitle.errors; Throws MongoCursorException if the - "safe" option is set and the operation fails. + "w" option is set and the operation fails. Throws MongoCursorTimeoutException if the - "safe" option is set and the operation takes longer than + "w" option is set and the operation takes longer than MongoCursor::$timeout milliseconds to complete. This does not kill the operation on the server; it is a client-side timeout. diff --git a/reference/mongo/mongocursorexception.xml b/reference/mongo/mongocursorexception.xml index d9cda78b35..78daf6c767 100644 --- a/reference/mongo/mongocursorexception.xml +++ b/reference/mongo/mongocursorexception.xml @@ -33,8 +33,8 @@ insert(array("_id" => 1), array("safe" => true)); - $collection->insert(array("_id" => 1), array("safe" => true)); + $collection->insert(array("_id" => 1), array("w" => 1)); + $collection->insert(array("_id" => 1), array("w" => 1)); } catch (MongoCursorException $e) { echo "error message: ".$e->getMessage()."\n"; diff --git a/reference/mongo/mongodb.xml b/reference/mongo/mongodb.xml index 24cf015e6f..dd4fb53113 100644 --- a/reference/mongo/mongodb.xml +++ b/reference/mongo/mongodb.xml @@ -144,13 +144,14 @@ $db = $m->selectDB("example"); version 1.5.1+ of the MongoDB server and 1.0.8+ of the driver. - w is used whenever you perform a "safe" operation + w is used whenever you need to adjust the + acknowledgement level (MongoCollection::insert, MongoCollection::update, MongoCollection::remove, MongoCollection::save, and - MongoCollection::ensureIndex all support safe - options). With the default value (1), a safe operation will return once + MongoCollection::ensureIndex all support this + option). With the default value (1), an acknowledged 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 diff --git a/reference/mongo/mongodb/command.xml b/reference/mongo/mongodb/command.xml index ab3c53d73f..fecea87caf 100644 --- a/reference/mongo/mongodb/command.xml +++ b/reference/mongo/mongodb/command.xml @@ -57,18 +57,7 @@ public function command($data) { array("optionname" => <boolean>, ...). Currently supported options are: - - - "timeout" - - - 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 - will be thrown. - - + &mongo.writes.parameters.timeout; diff --git a/reference/mongo/mongogridfs/remove.xml b/reference/mongo/mongogridfs/remove.xml index 6631fc94f6..e4eaab4952 100644 --- a/reference/mongo/mongogridfs/remove.xml +++ b/reference/mongo/mongogridfs/remove.xml @@ -39,14 +39,7 @@ Options for the remove. Valid options are: - - - "safe" - - - Check that the remove succeeded. - - + &mongo.writes.parameters.writeconcern; diff --git a/reference/mongo/mongogridfs/storebytes.xml b/reference/mongo/mongogridfs/storebytes.xml index f9ef854f9d..edb3a4afb8 100644 --- a/reference/mongo/mongogridfs/storebytes.xml +++ b/reference/mongo/mongogridfs/storebytes.xml @@ -49,14 +49,7 @@ Options for the store. - - - "safe" - - - Check that this store succeeded. - - + &mongo.writes.parameters.writeconcern; @@ -75,7 +68,7 @@ &reftitle.errors; - Throws MongoCursorException if the "safe" option is + Throws MongoCursorException if the "w" option is set and the insert fails. diff --git a/reference/mongo/mongogridfs/storefile.xml b/reference/mongo/mongogridfs/storefile.xml index 29ff11480a..143702bea3 100644 --- a/reference/mongo/mongogridfs/storefile.xml +++ b/reference/mongo/mongogridfs/storefile.xml @@ -49,14 +49,7 @@ Options for the store. - - - "safe" - - - Check that this store succeeded. - - + &mongo.writes.parameters.writeconcern; @@ -75,7 +68,7 @@ &reftitle.errors; - Throws MongoCursorException if the "safe" option is + Throws MongoCursorException if the "w" option is set and the insert fails. diff --git a/reference/mongo/tutorial.xml b/reference/mongo/tutorial.xml index fd8c33cc65..36e2d86663 100644 --- a/reference/mongo/tutorial.xml +++ b/reference/mongo/tutorial.xml @@ -291,12 +291,12 @@ array(6) { foo->insert(array("_id" => 1), array("safe" => true)); +$db->foo->insert(array("_id" => 1), array("w" => 1)); // this will throw an exception -$db->foo->insert(array("_id" => 1), array("safe" => true)); +$db->foo->insert(array("_id" => 1), array("w" => 1)); // this is fine, as it is a different collection -$db->bar->insert(array("_id" => 1), array("safe" => true)); +$db->bar->insert(array("_id" => 1), array("w" => 1)); ?> ]]> diff --git a/reference/mongo/writeconcerns.xml b/reference/mongo/writeconcerns.xml index 74645d063d..e5f2d1fc59 100644 --- a/reference/mongo/writeconcerns.xml +++ b/reference/mongo/writeconcerns.xml @@ -36,11 +36,23 @@ + + When using acknowledged writes and the ReplicaSet has failedover, the driver + will automatically 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 primary). + + + When using unacknowledged writes (w=0) and the ReplicaSet has failedover, + there will be no way for the driver to know about the change so it will + continuously and silently fail to write. + The default Write Concern for the MongoClient is 1, acknowledge. + Available Write Concerns @@ -246,6 +258,15 @@ try { + + &reftitle.seealso; + + + MongoDB WriteConcern docs + + + + &reftitle.changelog;