Fixed information for fsync and also added section to release notes, NODE-131

Author: christkv

docs/articles/AnIntroductionTo1_4_and_2_6.md

@@ -220,4 +220,11 @@ Buffered Max Entries allow for more fine grained control on how many operations
 db.close();
 });
 
-This example disables the command buffering completely and errors out the moment there is no connection available. The default value (for backward compatibility) is to buffer until memory runs out. Be aware that by setting a very low value you can cause some problems in failover scenarios in Replicasets as it might take a little but of time before f.ex a new Primary is elected and steps up to accept writes. Setting **bufferMaxEntries** to 0 in this case will cause the driver to error out instead of falling over correctly.
+This example disables the command buffering completely and errors out the moment there is no connection available. The default value (for backward compatibility) is to buffer until memory runs out. Be aware that by setting a very low value you can cause some problems in failover scenarios in Replicasets as it might take a little but of time before f.ex a new Primary is elected and steps up to accept writes. Setting **bufferMaxEntries** to 0 in this case will cause the driver to error out instead of falling over correctly.
+
+## Fsync and journal Write Concerns note
+
+MongoDB from version 2.6 and higher disallows the combination of **journal** and **fsync**. Combining them will cause an error while on 2.4 **fsync** was ignored when provided with **journal**. The following semantics apply.
+
+* j: If true block until write operations have been committed to the journal. Cannot be used in combination with `fsync`. Prior to MongoDB 2.6 this option was ignored if the server was running without journaling. Starting with MongoDB 2.6 write operations will fail with an exception if this option is used when the server is running without journaling.
+* fsync: If true and the server is running without journaling, blocks until the server has synced all data files to disk. If the server is running with journaling, this acts the same as the `j` option, blocking until write operations have been committed to the journal. Cannot be used in combination with `j`.

lib/mongodb/collection.js

@@ -69,8 +69,8 @@ function Collection (db, collectionName, pkFactory, options) {
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **continueOnError/keepGoing** {Boolean, default:false}, keep inserting documents even if one document has an error, *mongodb 1.9.1 >*.
  * - **serializeFunctions** {Boolean, default:false}, serialize functions on the document.
  * - **forceServerObjectId** {Boolean, default:false}, let server assign ObjectId instead of the driver
@@ -93,8 +93,8 @@ Collection.prototype.insert = function() { return core.insert; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **single** {Boolean, default:false}, removes the first document found.
  * 
  * Deprecated Options 
@@ -129,8 +129,8 @@ Collection.prototype.rename = function() { return commands.rename; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * 
  * Deprecated Options 
  * - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.
@@ -149,8 +149,8 @@ Collection.prototype.save = function() { return core.save; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **upsert** {Boolean, default:false}, perform an upsert operation.
  * - **multi** {Boolean, default:false}, update all documents matching the selector.
  * - **serializeFunctions** {Boolean, default:false}, serialize functions on the document.
@@ -216,8 +216,8 @@ Collection.prototype.drop = function drop(callback) {
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **remove** {Boolean, default:false}, set to true to remove the object before returning.
  * - **upsert** {Boolean, default:false}, perform an upsert operation.
  * - **new** {Boolean, default:false}, set to true if you want to return the modified object rather than the original. Ignored for remove.
@@ -241,8 +241,8 @@ Collection.prototype.findAndModify = function() { return core.findAndModify; }()
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * 
  * Deprecated Options 
  * - **safe** {true | {w:n, wtimeout:n} | {fsync:true}, default:false}, executes with a getLastError command returning the results of the command on MongoDB.
@@ -352,8 +352,8 @@ Collection.prototype.findOne = function() { return query.findOne; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **unique** {Boolean, default:false}, creates an unique index.
  * - **sparse** {Boolean, default:false}, creates a sparse index.
  * - **background** {Boolean, default:false}, creates the index in the background, yielding whenever possible.
@@ -381,8 +381,8 @@ Collection.prototype.createIndex = function() { return index.createIndex; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  * - **unique** {Boolean, default:false}, creates an unique index.
  * - **sparse** {Boolean, default:false}, creates a sparse index.
  * - **background** {Boolean, default:false}, creates the index in the background, yielding whenever possible.
@@ -621,8 +621,8 @@ Collection.prototype.stats = function() { return commands.stats; }();
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @param {Objects} [options] options for the initializeUnorderedBatch 
  * @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. The second argument will be a UnorderedBulkOperation object.
@@ -637,8 +637,8 @@ Collection.prototype.initializeUnorderedBulkOp = function() { return unordered.i
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @param {Objects} [options] options for the initializeOrderedBulkOp 
  * @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. The second argument will be a OrderedBulkOperation object.

lib/mongodb/collection/batch/ordered.js

@@ -14,8 +14,8 @@ var shared = require('../shared')
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @class Represents a OrderedBulkOperation
  * @param {Object} collection collection instance.
@@ -476,8 +476,8 @@ function OrderedBulkOperation (collection, options) {
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @param {Object} [options] additional options during update.
  * @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from from the ordered bulk operation.

lib/mongodb/collection/batch/unordered.js

@@ -14,8 +14,8 @@ var shared = require('../shared')
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @class Represents a UnorderedBulkOperation
  * @param {Object} collection collection instance.
@@ -344,8 +344,8 @@ var UnorderedBulkOperation = function(collection, options) {
  * Options
  * - **w**, {Number/String, > -1 || 'majority' || tag name} the write concern for the operation where < 1 is no acknowlegement of write and w >= 1, w = 'majority' or tag acknowledges the write
  * - **wtimeout**, {Number, 0} set the timeout for waiting for write concern to finish (combines with w option)
- * - **fsync**, (Boolean, default:false) write waits for fsync before returning
- * - **journal**, (Boolean, default:false) write waits for journal sync before returning
+ * - **fsync**, (Boolean, default:false) write waits for fsync before returning, from MongoDB 2.6 on, fsync cannot be combined with journal
+ * - **j**, (Boolean, default:false) write waits for journal sync before returning
  *
  * @param {Object} [options] additional options during update.
  * @param {Function} callback this will be called after executing this method. The first parameter will contain the Error object if an error occured, or null otherwise. While the second parameter will contain the results from from the unordered bulk operation.