Docs4dev
Docs
mongodb / v3.6 / reference / reference-command-fsync.html

fsync

On this page

Definition

fsync

Forces the mongod process to flush all pending writes from the storage layer to disk and locks the entire mongod instance to prevent additional writes until the user releases the lock with a corresponding fsyncUnlock. Optionally, you can use fsync to lock the mongod instance and block write operations for the purpose of capturing backups.

As applications write data, MongoDB records the data in the storage layer and then writes the data to disk within the syncPeriodSecs interval, which is 60 seconds by default. Run fsync when you 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:

Field Type Description
fsync integer Enter “1” to apply fsync.
async boolean Optional. Runs fsync asynchronously. By default, the fsync operation is synchronous.
lock boolean Optional. Takes a lock on the mongod instance and blocks all write operations. Each fsync with lock operation takes a lock.

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

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

Considerations

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

The data files of a locked mongod may change due to operations such as journaling syncs or WiredTiger snapshots. While this has no affect on the logical data (e.g. data accessed by clients), some backup utilities may detect these changes and emit warnings or fail with errors. For more information on MongoDB- recommended backup utilities and procedures, see MongoDB Backup Methods.

Impact on Larger Deployments

An fsync lock is only possible on individual mongod instances of a sharded cluster, not on the entire cluster. To back up an entire sharded cluster, please see Backup and Restore Sharded Clusters for more information.

Alternatives with Journaling

If your mongod has journaling enabled, please use file system or volume/block level snapshot tool to create a backup 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 lockCount in the return document.

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

Note

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

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

Examples

Run Asynchronously

The fsync operation is synchronous by default. To run fsync asynchronously, use the async field set to true:

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

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

Lock mongod Instance

Note

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

The data files of a locked mongod may change due to operations such as journaling syncs or WiredTiger snapshots. While this has no affect on the logical data (e.g. data accessed by clients), some backup utilities may detect these changes and emit warnings or fail with errors. For more information on MongoDB- recommended backup utilities and procedures, see MongoDB Backup Methods.

The primary use of fsync is to lock the mongod instance in order to back up the files within mongod’s dbPath. The operation flushes all data to the storage layer and blocks 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 the operation 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 a fsync lock. However, after the first write operation all subsequent 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 count must be zero. That is, for a given number of { fsync: 1, lock: true } operation, you must issue a corresponding number of unlock operations 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 zero to unlock the instance for writes.

Check Lock Status

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

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

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

serverIsLocked()

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