OPTIONS

Write Concern for Replica Sets

MongoDB’s built-in write concern confirms the success of write operations to a replica set’s primary. Write concern uses the getLastError command after write operations to return an object with error information or confirmation that there are no errors.

From the perspective of a client application, whether a MongoDB instance is running as a single server (i.e. “standalone”) or a replica set is transparent. However, replica sets offer some configuration options for write and read operations. [1]

[1]Sharded clusters where the shards are also replica sets provide the same configuration options with regards to write and read operations.

Verify Write Operations

The default write concern confirms write operations only on the primary. You can configure write concern to confirm write operations to additional replica set members as well by issuing the getLastError command with the w option.

The w option confirms that write operations have replicated to the specified number of replica set members, including the primary. You can either specify a number or specify majority, which ensures the write propagates to a majority of set members.

Write operation to a replica set with write concern level of ``w:2`` or write to the primary and at least one secondary.

If you specify a w value greater than the number of members that hold a copy of the data (i.e., greater than the number of non-arbiter members), the operation blocks until those members become available. This can cause the operation to block forever. To specify a timeout threshold for the getLastError operation, use the wtimeout argument. A wtimeout value of 0 means that the operation will never time out.

See getLastError Examples for example invocations.

Modify Default Write Concern

You can configure your own “default” getLastError behavior for a replica set. Use the getLastErrorDefaults setting in the replica set configuration. The following sequence of commands creates a configuration that waits for the write operation to complete on a majority of the set members before returning:

cfg = rs.conf()
cfg.settings = {}
cfg.settings.getLastErrorDefaults = {w: "majority"}
rs.reconfig(cfg)

The getLastErrorDefaults setting affects only those getLastError commands that have no other arguments.

Note

Use of insufficient write concern can lead to rollbacks in the case of replica set failover. Always ensure that your operations have specified the required write concern for your application.

Custom Write Concerns

You can use replica set tags to create custom write concerns using the getLastErrorDefaults and getLastErrorModes replica set settings.

Note

Custom write concern modes specify the field name and a number of distinct values for that field. By contrast, read preferences use the value of fields in the tag document to direct read operations.

In some cases, you may be able to use the same tags for read preferences and write concerns; however, you may need to create additional tags for write concerns depending on the requirements of your application.

Single Tag Write Concerns

Consider a five member replica set, where each member has one of the following tag sets:

{ "use": "reporting" }
{ "use": "backup" }
{ "use": "application" }
{ "use": "application" }
{ "use": "application" }

You could create a custom write concern mode that will ensure that applicable write operations will not return until members with two different values of the use tag have acknowledged the write operation. Create the mode with the following sequence of operations in the mongo shell:

cfg = rs.conf()
cfg.settings = { getLastErrorModes: { use2: { "use": 2 } } }
rs.reconfig(cfg)

To use this mode pass the string use2 to the w option of getLastError as follows:

db.runCommand( { getLastError: 1, w: "use2" } )

Specific Custom Write Concerns

If you have a three member replica with the following tag sets:

{ "disk": "ssd" }
{ "disk": "san" }
{ "disk": "spinning" }

You cannot specify a custom getLastErrorModes value to ensure that the write propagates to the san before returning. However, you may implement this write concern policy by creating the following additional tags, so that the set resembles the following:

{ "disk": "ssd" }
{ "disk": "san", "disk.san": "san" }
{ "disk": "spinning" }

Then, create a custom getLastErrorModes value, as follows:

cfg = rs.conf()
cfg.settings = { getLastErrorModes: { san: { "disk.san": 1 } } }
rs.reconfig(cfg)

To use this mode pass the string san to the w option of getLastError as follows:

db.runCommand( { getLastError: 1, w: "san" } )

This operation will not return until a replica set member with the tag disk.san returns.

You may set a custom write concern mode as the default write concern mode using getLastErrorDefaults replica set as in the following setting:

cfg = rs.conf()
cfg.settings.getLastErrorDefaults = { ssd: 1 }
rs.reconfig(cfg)

See also

Configure Replica Set Tag Sets for further information about replica set reconfiguration and tag sets.