diff --git a/reference/mongo/manual.xml b/reference/mongo/manual.xml
index cc1b9fd9fa..6bca62521c 100644
--- a/reference/mongo/manual.xml
+++ b/reference/mongo/manual.xml
@@ -13,9 +13,10 @@
&reference.mongo.tutorial;
+ &reference.mongo.readpreferences;
+ &reference.mongo.writeconcerns;
&reference.mongo.sqltomongo;
&reference.mongo.connecting;
- &reference.mongo.readpreferences;
&reference.mongo.writes;
&reference.mongo.queries;
&reference.mongo.updates;
diff --git a/reference/mongo/writeconcerns.xml b/reference/mongo/writeconcerns.xml
new file mode 100644
index 0000000000..74645d063d
--- /dev/null
+++ b/reference/mongo/writeconcerns.xml
@@ -0,0 +1,303 @@
+
+
+
+
+ Write Concerns
+
+
+ MongoDB provides several different ways of selecting how durable a write to
+ the database should be. These ways are called Write
+ Concerns and span everything from completely ignoring all errors,
+ to specifically targetting which servers are required to confirm the write
+ before returning the operation.
+
+
+ When a write (such as with MongoCollection::insert,
+ MongoCollection::update, and
+ MongoCollection::remove) is given a Write Concern
+ option ("w") the driver will send the query to MongoDB
+ and then followup with a getLastError command
+ (GLE) with the Write Concern option which will be blocked
+ until the Write Concern condition is verified to be fullfilled, or the query
+ times out (controlled with the "wtimeout" option, no
+ timeout by default).
+
+
+
+
+ Even though a getLastError command times out the data
+ will most likely have been written to the primary server and will be
+ replicated to all the secondaries once they have cought up.
+
+
+ The typical reasons for a timeout to happen is if you specify a Write
+ Concern which requires confirmation from more servers then you currently
+ have available.
+
+
+
+
+ The default Write Concern for the MongoClient is
+ 1, acknowledge.
+
+
+
+
+ Available Write Concerns
+
+
+
+ Write Concern
+ Meaning
+ Description
+
+
+
+
+ w=-1
+ Errors ignored
+ No errors, including network errors, will be checked at all
+
+
+ w=0
+ Unacknowledged
+ A write will not be followed up with a GLE call, and therefore not checked ("fire and forget")
+
+
+ w=1
+ Acknowledged
+ The write will be acknowledged by the server (the primary on ReplicaSet configuration)
+
+
+ w=N
+ ReplicaSet Acknowledged
+ The write will be acknowledged by the primary server, and
+ replicated to N-1 secondaries.
+
+
+ w=majority
+ Majority Acknowledged
+ The write will be acknowledged by the majority of the ReplicaSet (including the primary). This is a special reserved string.
+
+
+ w=<tag set>
+ ReplicaSet TagSet Acknowledged
+ The write will be acknowledged by members of the entire TagSet
+
+
+ j=true
+ Journaled
+ The write will be acknowledged by primary and the journal flushed to disk
+
+
+
+
+
+
+
+
+ Unacknowledged Writes
+
+ By not requiring the server to acknowledge writes means that writes can be performed
+ extremely quickly, but you don't know whether or not they actually succeeded.
+ Writes can fail for a number of reasons: if there are network problems, if a
+ database server goes down, or if the write was simply invalid (e.g., writing
+ to a system collection).
+
+
+ While developing, you should always use safe writes (to protect against
+ inadvertent mistakes, such as syntax errors, invalid operators, duplicate key errors and so on). In
+ production, unsafe writes can be used for "unimportant" data. Unimportant
+ data varies on application, but it's generally automatically (instead of user
+ generated) data, such as click tracking or GPS locations, where you can get
+ thousands of records per second.
+
+
+ It is strongly recommended that you do a acknowledged write at the end of
+ series of unacknowledged writes. Doing so will not incurr in too large
+ performance penalty, but still allow you to catch any errors that may have
+ occurred.
+
+
+ Unacknowledged WriteConcern, followed with Acknowledged Write
+
+insert($someDoc, array("w" => 0));
+$collection->update($criteria, $newObj, array("w" => 0));
+$collection->insert($somethingElse, array("w" => 0));
+try {
+ $collection->remove($something, array("w" => 1));
+} catch(MongoCursorException $e) {
+ /* Handle the exception.. */
+ /* Here we should issue find() queries on the IDs generated for
+ $somethingElse and $someDoc to verify they got written to the database and
+ attempt to figureout where in the chain something happened. */
+}
+?>
+]]>
+
+
+ If the last write throws an exception, you know that there's a problem
+ with your database.
+
+
+
+
+
+ Acknowledged Writes
+
+ These type of write operations will make sure that the
+ database has the write before returning success. If the write failed, it
+ will throw a MongoCursorException with an explanation of
+ the failure. The MongoClient default behaviour is to
+ acknowledge the write (w=1).
+
+
+ It is possible to specify how many members of an ReplicaSet have to
+ acknowledge the write (i.e. have it replicated) before the write is deemed
+ acknowledged and the operation returns.
+
+ Acknowledged Writes
+
+insert($doc, array("w" => 1));
+// Force acknowledgement from the primary, and one other member of the ReplicaSet
+$collection->insert($doc, array("w" => 2));
+// Force acknowledgement from the primary, and six other member of the ReplicaSet
+// (You probably never ever want to do this :)
+$collection->insert($doc, array("w" => 7));
+]]>
+
+
+ Keep in mind to select your Write Concern carefully. If you have a
+ ReplicaSet with 5 members, and you select WriteConcern of
+ 4 you will risk the write blocking forever when one
+ member of the ReplicaSet goes down for maintenance or a temporary network
+ outage happens.
+
+
+
+
+
+ Passing in a string value for WriteConcern has a specific meaning
+ (ReplicaSet TagSet Acknowledged). Please be careful of
+ NOT using string values for numbers (i.e.
+ array("w" => "1")) as it will be treated as a TagSet
+ name.
+
+
+
+
+
+ Majority Acknowledged Writes
+
+ Using the special majority Write Concern option is the
+ recommended way for writes that are required to survive the apocalypse, as
+ it will ensure the majority of your ReplicaSet will have the write and will
+ therefore be guaranteed to survive all usual suspect outage scenarios.
+
+
+ Majority Acknowledged Write
+
+insert($someDoc, array("w" => "majority"));
+?>
+]]>
+
+
+
+
+
+
+
+ Journaled Writes
+
+ When connecting to a ReplicaSet the default WriteConcern is only to have
+ the primary server acknowledge the write, but there is a 100ms window until
+ the write gets journaled and flushed to disk. It is possible to force the
+ write to be journaled before acknowledging the write by setting the
+ j option:
+
+ Acknowledged and Journaled Write
+ Forcing journal flush
+
+ 1,
+ "j" => true,
+);
+try {
+ $collection->insert($document, $options);
+} catch(MongoCursorException $e) {
+ /* handle the exception */
+}
+]]>
+
+
+
+
+
+
+ &reftitle.changelog;
+
+
+
+
+ &Version;
+ &Description;
+
+
+
+
+ 1.3.0
+
+ MongoClient was introduced and defaults to
+ acknowledged writes.
+ The deprecated Mongo defaults to unacknowledged
+ writes.
+
+
+
+ 1.3.0
+
+ The "safe" write option has been deprecated and not
+ available with the new MongoClient class.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/reference/mongo/writes.xml b/reference/mongo/writes.xml
index 9698827ad0..9c93207ede 100644
--- a/reference/mongo/writes.xml
+++ b/reference/mongo/writes.xml
@@ -3,78 +3,6 @@
Writes
-
-
- Safe Operations
-
- By default, the driver does not wait for a database response to writes
- (inserts, updates, and deletes). This means that writes can be performed
- extremely quickly, but you don't know whether or not they actually succeeded.
- Writes can fail for a number of reasons: if there are network problems, if a
- database server goes down, or if the write was simply invalid (e.g., writing
- to a system collection).
-
-
- To get a response from the database, use the safe option,
- available for all types of writes. This option will make sure that the
- database has the write before returning success. If the write failed, it
- will throw a MongoCursorException with an explanation of
- the failure.
-
-
- While developing, you should always use safe writes (to protect against
- inadvertent mistakes, such as duplicate key errors and similar). In
- production, unsafe writes can be used for "unimportant" data. Unimportant
- data varies on application, but it's generally automatically (instead of user
- generated) data, such as click tracking or GPS locations, where you can get
- thousands of records per second.
-
-
- To safely perform writes without incurring too large a performance penalty,
- it is recommended that you do a safe write at the end of a series of writes.
- For example:
-
-
-insert($someDoc);
-$collection->update($criteria, $newObj);
-$collection->insert($somethingElse);
-$collection->remove($something, array("safe" => true));
-?>
-]]>
-
-
- Then, if the last write throws an exception, you know that there's a problem
- with your database.
-
-
- There are a few other options available to ensure the safety of writes. You
- can specify "fsync" => true to force the database to
- fsync all writes up to this point to disk (by default, MongoDB fsyncs writes
- once per minute).
-
-
- The safest way of doing a write is to use replication and specify the number
- of servers that must have this write before returning success. (You should
- always use replication in production, see the Connecting section for more
- information on replica sets.)
-
-
-insert($someDoc, array("safe" => 3));
-?>
-]]>
-
-
- 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 primary and
- two secondaries must acknowledge the write.
-
-
-
Updating Nested Objects
@@ -136,6 +64,7 @@ $blog->update(
]]>
+