fsync

Definition

• fsync
• Forces the mongod process to flush all pending writesfrom the storage layer to disk and locks the entiremongod instance to prevent additional writes until theuser releases the lock with a correspondingfsyncUnlock. Optionally, you can use fsyncto lock the mongod instance and block write operationsfor the purpose of capturing backups.

As applications write data, MongoDB records the data in the storagelayer and then writes the data to disk within the syncPeriodSecsinterval, which is 60 seconds by default. Run fsync whenyou want to flush writes to disk ahead of that interval.

The fsync command has the following syntax:

{ fsync: 1, async: <Boolean>, lock: <Boolean> }

The fsync command has the following fields:

FieldTypeDescriptionfsyncintegerEnter “1” to apply fsync.asyncbooleanOptional. Runs fsync asynchronously. By default, thefsync operation is synchronous.lockbooleanOptional. Takes a lock on the mongod instance and blocks allwrite operations. Each fsync with lock operationtakes a lock.

To run the fsync command, use thedb.adminCommand() method:

db.adminCommand( { fsync: 1, ... } )

Considerations

fsync command with the lock option ensures that the data files are safe to copyusing low-level backup utilities such as cp, scp, ortar. A mongod started using the copiedfiles contains user-written data that is indistinguishable from theuser-written data on the locked mongod.

The data files of a locked mongod may change due tooperations such as journaling syncs orWiredTiger snapshots. Whilethis has no affect on the logical data (e.g. data accessed byclients), some backup utilities may detect these changes and emitwarnings or fail with errors. For more information on MongoDB-recommended backup utilities and procedures, seeMongoDB Backup Methods.

Impact on Larger Deployments

An fsync lock is only possible on individualmongod instances of asharded cluster, not on the entire cluster. To back up an entire shardedcluster, please see Backup and Restore Sharded Clusters formore information.

Alternatives with Journaling

If your mongod has journaling enabled,please use file system or volume/block level snapshot tool to create abackup of the data set and the journal together as a single unit.

fsync with lock: true

Changed in version 3.4: The { fsync: 1, lock: true } command now returns a lockCountin the return document.

After { fsync: 1, lock: true } runs on a mongod, allwrite operations will block. The mongo shell provides ahelper method db.fsyncLock().

Note

The { fsync: 1, lock: true } operation maintain a lock count.Each { fsync: 1, lock: true } operation increments the lockcount.

To unlock a mongod instance for writes, the lock countmust be zero. That is, for a given number of { fsync: 1, lock:true } operation, you must issue a corresponding number of unlockoperations in order to unlock the instance for writes. To unlock,see db.fsyncUnlock().

Examples

Run Asynchronously

The fsync operation is synchronous by default. To runfsync asynchronously, use the async field set totrue:

db.adminCommand( { fsync: 1, async: true } )

The operation returns immediately. To view the status of thefsync operation, check the output ofdb.currentOp().

Lock mongod Instance

Note

fsync command with the lock option ensures that the data files are safe to copyusing low-level backup utilities such as cp, scp, ortar. A mongod started using the copiedfiles contains user-written data that is indistinguishable from theuser-written data on the locked mongod.

The data files of a locked mongod may change due tooperations such as journaling syncs orWiredTiger snapshots. Whilethis has no affect on the logical data (e.g. data accessed byclients), some backup utilities may detect these changes and emitwarnings or fail with errors. For more information on MongoDB-recommended backup utilities and procedures, seeMongoDB Backup Methods.

The primary use of fsync is to lock the mongodinstance in order to back up the files within mongod’s dbPath.The operation flushes all data to the storage layer andblocks all write operations until you unlock the mongod instance.

To lock the database, use the lock field set to true:

db.adminCommand( { fsync: 1, lock: true } )

The operation returns a document that includes the status of theoperation and the lockCount:

{
   "info" : "now locked against writes, use db.fsyncUnlock() to unlock",
   "lockCount" : NumberLong(1),
   "seeAlso" : "http://dochub.mongodb.org/core/fsynccommand",
   "ok" : 1
}

You may continue to perform read operations on a mongod instance that has afsync lock. However, after the first write operation allsubsequent read operations wait until you unlock the mongod instance.

Important

The { fsync: 1, lock: true } operation maintain a lock count.

To unlock a mongod instance for writes, the lock countmust be zero. That is, for a given number of { fsync: 1, lock:true } operation, you must issue a corresponding number of unlockoperations in order to unlock the instance for writes.

Unlock mongod Instance

To unlock the mongod, use db.fsyncUnlock():

db.fsyncUnlock();

Repeat the db.fsyncUnlock() to reduce the lock count to zeroto unlock the instance for writes.

Check Lock Status

To check the state of the fsync lock, use db.currentOp(). Usethe following JavaScript function in the shell to test if mongod instance iscurrently locked:

serverIsLocked = function () {
                     var co = db.currentOp();
                     if (co && co.fsyncLock) {
                         return true;
                     }
                     return false;
                 }

After loading this function into your mongo shell sessioncall it, with the following syntax:

serverIsLocked()

This function will return true if the mongod instance iscurrently locked and false if the mongod is not locked.