diff --git a/source/includes/apiargs-dbcommand-fsync-field.yaml b/source/includes/apiargs-dbcommand-fsync-field.yaml index c5d61b3ccf3..9d0e16510a5 100644 --- a/source/includes/apiargs-dbcommand-fsync-field.yaml +++ b/source/includes/apiargs-dbcommand-fsync-field.yaml @@ -21,7 +21,11 @@ type: boolean --- arg_name: field description: | - Locks :binary:`~bin.mongod` instance and blocks all write operations. + + Takes a lock on the :binary:`~bin.mongod` instance and blocks all + write operations. Each :dbcommand:`fsync` with ``lock`` operation + takes a lock. + interface: dbcommand name: lock operation: fsync diff --git a/source/includes/ref-toc-command-administration.yaml b/source/includes/ref-toc-command-administration.yaml index 1ad44f8476a..f2abe0332c0 100644 --- a/source/includes/ref-toc-command-administration.yaml +++ b/source/includes/ref-toc-command-administration.yaml @@ -66,6 +66,10 @@ name: ":dbcommand:`fsync`" file: /reference/command/fsync description: "Flushes pending writes to the storage layer and locks the database to allow backups." --- +name: ":dbcommand:`fsyncUnlock`" +file: /reference/command/fsyncUnlock +description: "Unlocks one fsync lock." +--- name: ":dbcommand:`getParameter`" file: /reference/command/getParameter description: "Retrieves configuration options." diff --git a/source/includes/steps-backup-sharded-cluster-with-snapshots.yaml b/source/includes/steps-backup-sharded-cluster-with-snapshots.yaml index ccb1f216287..dbb5bac6ec0 100644 --- a/source/includes/steps-backup-sharded-cluster-with-snapshots.yaml +++ b/source/includes/steps-backup-sharded-cluster-with-snapshots.yaml @@ -45,10 +45,7 @@ action: language: javascript code: | db.fsyncLock() - post: | - When calling :method:`db.fsyncLock()`, ensure that the connection - is kept open to allow a subsequent call to - :method:`db.fsyncUnlock()`. + - heading: Lock config server replica set secondary. pre: | If locking a secondary of the CSRS, confirm that the member has @@ -98,9 +95,6 @@ action: language: javascript code: | db.fsyncLock() - post: | - When calling :method:`db.fsyncLock()`, ensure that the connection is - kept open to allow a subsequent call to :method:`db.fsyncUnlock()`. --- title: Back up one of the config servers. stepnum: 3 @@ -136,8 +130,7 @@ pre: | unlock them. To unlock the replica set members, use :method:`db.fsyncUnlock()` - method in the :binary:`~bin.mongo` shell. For each locked member, use the - same :binary:`~bin.mongo` shell used to lock the instance. + method in the :binary:`~bin.mongo` shell. action: language: javascript code: | diff --git a/source/includes/steps-backup-sharded-clusters-dumps.yaml b/source/includes/steps-backup-sharded-clusters-dumps.yaml index b4a7c172ae2..370322055cd 100644 --- a/source/includes/steps-backup-sharded-clusters-dumps.yaml +++ b/source/includes/steps-backup-sharded-clusters-dumps.yaml @@ -39,10 +39,7 @@ action: language: javascript code: | db.fsyncLock() - post: | - When calling :method:`db.fsyncLock()`, ensure that the connection - is kept open to allow a subsequent call to - :method:`db.fsyncUnlock()`. + - heading: Lock config server replica set secondary. pre: | If locking a secondary of the CSRS, confirm that the member has @@ -92,9 +89,7 @@ action: language: javascript code: | db.fsyncLock() - post: | - When calling :method:`db.fsyncLock()`, ensure that the connection is - kept open to allow a subsequent call to :method:`db.fsyncUnlock()`. + --- title: Backup one config server. stepnum: 3 @@ -116,7 +111,7 @@ action: If your deployment uses CSRS config servers, unlock the config server node before proceeding to the next step. To unlock the CSRS member, use :method:`db.fsyncUnlock()` method in - the :binary:`~bin.mongo` shell used to lock the instance. + the :binary:`~bin.mongo` shell. language: javascript code: | db.fsyncUnlock() @@ -139,8 +134,7 @@ stepnum: 5 ref: restart-replica-set-members pre: | To unlock the replica set members, use :method:`db.fsyncUnlock()` - method in the :binary:`~bin.mongo` shell. For each locked member, use the - same :binary:`~bin.mongo` shell used to lock the instance. + method in the :binary:`~bin.mongo` shell. action: language: javascript code: | diff --git a/source/reference/command/fsync.txt b/source/reference/command/fsync.txt index e4c8b743159..8a12b1f8a2b 100644 --- a/source/reference/command/fsync.txt +++ b/source/reference/command/fsync.txt @@ -10,6 +10,10 @@ fsync :depth: 1 :class: singlecol +.. meta:: + :description: fsync, fsynclock, fsync lock, lock + :keywords: fsync, fsynclock, fsync lock, lock + Definition ---------- @@ -24,6 +28,7 @@ Definition layer and then writes the data to disk within the :setting:`~storage.syncPeriodSecs` interval, which is 60 seconds by default. Run :dbcommand:`fsync` when you want to flush writes to disk ahead of that interval. + The :dbcommand:`fsync` command has the following syntax: @@ -35,6 +40,15 @@ Definition .. include:: /includes/apiargs/dbcommand-fsync-field.rst + To run the :dbcommand:`fsync` command, use the + :method:`db.adminCommand()` method: + + .. code-block:: javascript + + db.adminCommand( { fsync: 1, ... } ) + + + Considerations -------------- @@ -59,28 +73,30 @@ If your :binary:`~bin.mongod` has :term:`journaling ` enabled, please use :ref:`file system or volume/block level snapshot tool ` to create a backup of the data set and the journal together as a single unit. -Impact on Read Operations -~~~~~~~~~~~~~~~~~~~~~~~~~ -After :dbcommand:`fsync` with the ``lock`` option runs on a -:binary:`~bin.mongod`, all write operations will block until a subsequent -unlock. Read operations *may* also block. As a result, :dbcommand:`fsync` -with lock is not a reliable mechanism for making a :binary:`~bin.mongod` -instance operate in a read-only mode. +``fsync`` with ``lock: true`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. important:: +.. versionchanged:: 3.4 + + The ``{ fsync: 1, lock: true }`` command now returns a ``lockCount`` + in the return document. - Blocked read operations prevent verification of authentication. - Such reads are necessary to establish new connections - to a :binary:`~bin.mongod` that enforces authorization checks. +After ``{ fsync: 1, lock: true }`` runs on a :binary:`~bin.mongod`, all +write operations will block. -.. warning:: - When calling :dbcommand:`fsync` with the ``lock`` option, ensure that - the connection remains open to allow a subsequent call to - :method:`db.fsyncUnlock()`. +.. note:: + + The ``{ fsync: 1, lock: true }`` operation maintain a lock count. + Each ``{ fsync: 1, lock: true }`` operation increments the lock + count. - Closing the connection may make it difficult to release the lock. + To unlock a :binary:`~bin.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 :method:`db.fsyncUnlock()`. Examples -------- @@ -94,7 +110,7 @@ The :dbcommand:`fsync` operation is synchronous by default. To run .. code-block:: javascript - { fsync: 1, async: true } + db.adminCommand( { fsync: 1, async: true } ) The operation returns immediately. To view the status of the :dbcommand:`fsync` operation, check the output of @@ -116,12 +132,33 @@ To lock the database, use the ``lock`` field set to ``true``: .. code-block:: javascript - { fsync: 1, lock: true } + db.adminCommand( { fsync: 1, lock: true } ) + +The operation returns a document that includes the status of the +operation and the ``lockCount``: + +.. code-block:: javascript + + { + "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 :binary:`~bin.mongod` instance that has a :dbcommand:`fsync` lock. However, after the first write operation all subsequent read operations wait until you unlock the :binary:`~bin.mongod` instance. +.. important:: + + The ``{ fsync: 1, lock: true }`` operation maintain a lock count. + + To unlock a :binary:`~bin.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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -131,6 +168,8 @@ To unlock the :binary:`~bin.mongod`, use :method:`db.fsyncUnlock()`: db.fsyncUnlock(); +Repeat the :method:`db.fsyncUnlock()` to reduce the lock count to zero +to unlock the instance for writes. Check Lock Status ~~~~~~~~~~~~~~~~~ diff --git a/source/reference/command/fsyncUnlock.txt b/source/reference/command/fsyncUnlock.txt new file mode 100644 index 00000000000..dc76e6734e8 --- /dev/null +++ b/source/reference/command/fsyncUnlock.txt @@ -0,0 +1,100 @@ +=========== +fsyncUnlock +=========== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. meta:: + :description: fsync, fsyncUnlock, fsync unlock, unlock + :keywords: fsync, fsyncUnlock, fsync unlock, unlock + +Definition +---------- + +.. dbcommand:: fsyncUnlock + + Reduces the lock taken by :dbcommand:`fsync` (with the lock option) + on a :binary:`~bin.mongod` instance by 1. + + .. important:: + + The :dbcommand:`fsync` lock and :dbcommand:`fsyncUnlock` + operations maintain a lock count. Each :dbcommand:`fsync` lock + opeartion increments the lock count, and :dbcommand:`fsyncUnlock` + decrements the lock count. + + To unlock a :binary:`~bin.mongod` instance for writes, the lock count + must be zero. That is, for a given number of :dbcommand:`fsync` + lock operations, you must issue a corresponding number of + :dbcommand:`fsyncUnlock` operations to unlock the instance for + writes. + + :dbcommand:`fsyncUnlock` is an administrative operation. Typically + you will use :dbcommand:`fsyncUnlock` following a database + :doc:`backup operation `. + + To run the :dbcommand:`fsyncUnlock` command, use the + :method:`db.adminCommand()` method: + + .. code-block:: javascript + + db.adminCommand( { fsyncUnlock: 1 } ) + + The operation returns a document with the following fields: + + .. list-table:: + + * - ``info`` + - information on the status of the operation + + * - ``lockCount`` + - The number of locks remaining on the instance after the operation. + + .. versionadded:: 3.4 + + * - ``ok`` + - The status code. + + .. tip:: + + The :binary:`~bin.mongo` shell provides the helper method + :method:`db.fsyncUnlock()`. + +Examples +-------- + +Consider a situation where :method:`db.fsyncLock()` has been issued two +times. The following :dbcommand:`fsyncUnlock` operation reduces the +locks taken by :method:`db.fsyncLock()` by 1: + +.. code-block:: javascript + + db.adminCommand( { fsyncUnlock: 1 } ) + +The operation returns the following document: + +.. code-block:: javascript + + { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(1), "ok" : 1 } + +As the ``lockCount`` is greater than 0, the :binary:`~bin.mongod` instance +is locked against writes. To unlock the instance for writes, run the +unlock operation again: + +.. code-block:: javascript + + db.adminCommand( { fsyncUnlock: 1 } ) + +The operation returns the following document: + +.. code-block:: javascript + + { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(0), "ok" : 1 } + +The :binary:`~bin.mongod` instance is unlocked for writes. diff --git a/source/reference/method/db.fsyncLock.txt b/source/reference/method/db.fsyncLock.txt index 4d30374c9f7..b9f1a08c13d 100644 --- a/source/reference/method/db.fsyncLock.txt +++ b/source/reference/method/db.fsyncLock.txt @@ -10,6 +10,10 @@ db.fsyncLock() :depth: 1 :class: singlecol +.. meta:: + :description: fsync, fsynclock, fsync lock, lock + :keywords: fsync, fsynclock, fsync lock, lock + Definition ---------- @@ -17,21 +21,49 @@ Definition Forces the :binary:`~bin.mongod` to flush all pending write operations to disk and locks the *entire* :binary:`~bin.mongod` instance to prevent - additional writes until the user releases the lock with the - :method:`db.fsyncUnlock()` command. :method:`db.fsyncLock()` is an - administrative command. + additional writes until the user releases the lock with a corresponding + :method:`db.fsyncUnlock()` command. + + .. important:: + + The :method:`db.fsyncLock()` and :method:`db.fsyncUnlock()` + operations maintain a lock count. :method:`db.fsyncLock()` + increments the lock count, and :method:`db.fsyncUnlock()` + decrements the lock count. - This command provides a simple wrapper around a - :dbcommand:`fsync` database command with the following - syntax: + To unlock a :binary:`~bin.mongod` instance for writes, the lock count + must be zero. That is, for a given number of + :method:`db.fsyncLock()` operations, you must issue a + corresponding number of :method:`db.fsyncUnlock()` operations to + unlock the instance for writes. + + :method:`db.fsyncLock()` has the syntax: .. code-block:: javascript - { fsync: 1, lock: true } + db.fsyncLock() - This function locks the database and creates a window for - :doc:`backup operations `. + The operation returns a document with the following fields: + - ``info`` - Information on the status of the operation + + - ``lockCount`` (*New in version 3.4*)- The number of locks currently on the instance. + + - ``seeAlso`` - Link to the :dbcommand:`fsync` command documentation. + + - ``ok`` - The status code. + + + This command provides a simple wrapper around a :dbcommand:`fsync` + database command with the following syntax: + + .. code-block:: javascript + + { fsync: 1, lock: true } + + :method:`db.fsyncLock()` is an administrative command. You can use + this operation to locks the database and create a window for + :doc:`backup operations `. Behavior -------- @@ -41,19 +73,38 @@ Compatibility with WiredTiger .. include:: /includes/extracts/wt-fsync-lock-compatibility.rst -Impact on Read Operations -~~~~~~~~~~~~~~~~~~~~~~~~~ +Example +------- + +The following operation runs :method:`db.fsyncLock()`: + +.. code-block:: javascript + + db.fsyncLock() + +The operation returns the following status document that includes the +``lockCount``: + +.. code-block:: javascript + + { + "info" : "now locked against writes, use db.fsyncUnlock() to unlock", + "lockCount" : NumberLong(1), + "seeAlso" : "http://dochub.mongodb.org/core/fsynccommand", + "ok" : 1 + } -:method:`db.fsyncLock()` *may* block reads, including those necessary to -verify authentication. -Such reads are necessary to establish new connections to a -:binary:`~bin.mongod` that enforces authorization checks. +If you run :method:`db.fsyncLock()` again, the operation increments the +``lockCount``: -Connection -~~~~~~~~~~ +.. code-block:: javascript -When calling :method:`db.fsyncLock()`, ensure that the connection -is kept open to allow a subsequent call to :method:`db.fsyncUnlock()`. + { + "info" : "now locked against writes, use db.fsyncUnlock() to unlock", + "lockCount" : NumberLong(2), + "seeAlso" : "http://dochub.mongodb.org/core/fsynccommand", + "ok" : 1 + } -Closing the connection may make it difficult to release the -lock. +To unlock the instance for writes, you must run +:method:`db.fsyncUnlock()` twice to reduce the ``lockCount`` to 0. diff --git a/source/reference/method/db.fsyncUnlock.txt b/source/reference/method/db.fsyncUnlock.txt index d1405b64182..7315d66f35c 100644 --- a/source/reference/method/db.fsyncUnlock.txt +++ b/source/reference/method/db.fsyncUnlock.txt @@ -10,19 +10,86 @@ db.fsyncUnlock() :depth: 1 :class: singlecol +.. meta:: + :description: fsync, fsyncUnlock, fsync unlock, unlock + :keywords: fsync, fsyncUnlock, fsync unlock, unlock + Definition ---------- .. method:: db.fsyncUnlock() - Unlocks a :binary:`~bin.mongod` instance to allow writes and reverses the - operation of a :method:`db.fsyncLock()` operation. Typically you will - use :method:`db.fsyncUnlock()` following a database :doc:`backup - operation `. + Reduces the lock taken by :method:`db.fsyncLock()` on a + :binary:`~bin.mongod` instance by 1. - :method:`db.fsyncUnlock()` is an administrative operation. + .. important:: + + The :method:`db.fsyncLock()` and :method:`db.fsyncUnlock()` + operations maintain a lock count. :method:`db.fsyncLock()` + increments the lock count, and :method:`db.fsyncUnlock()` + decrements the lock count. + + To unlock a :binary:`~bin.mongod` instance for writes, the lock count + must be zero. That is, for a given number of + :method:`db.fsyncLock()` operations, you must issue a + corresponding number of :method:`db.fsyncUnlock()` operations to + unlock the instance for writes. + + :method:`db.fsyncUnlock()` is an administrative operation. Typically + you will use :method:`db.fsyncUnlock()` following a database + :doc:`backup operation `. + + :method:`db.fsyncUnlock()` has the syntax: + + .. code-block:: javascript + + db.fsyncUnlock() + + The operation returns a document with the following fields: + + - ``info`` - Information on the status of the operation + + - ``lockCount`` (*New in version 3.4*) - The number of locks remaining on the instance after the operation. + + - ``ok`` - The status code. + + The :method:`db.fsyncUnlock()` method wraps the + :dbcommand:`fsyncUnlock` command. Compatibility with WiredTiger ----------------------------- .. include:: /includes/extracts/wt-fsync-lock-compatibility.rst + +Example +------- + +Consider a situation where :method:`db.fsyncLock()` has been issued two +times. The following :method:`db.fsyncUnlock()` operation reduces the +locks taken by :method:`db.fsyncLock()` by 1: + +.. code-block:: javascript + + db.fsyncUnlock() + +The operation returns the following document: + +.. code-block:: javascript + + { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(1), "ok" : 1 } + +As the ``lockCount`` is greater than 0, the :binary:`~bin.mongod` instance +is locked against writes. To unlock the instance for writes, run +:method:`db.fsyncLock()` again: + +.. code-block:: javascript + + db.fsyncUnlock() + +The operation returns the following document: + +.. code-block:: javascript + + { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(0), "ok" : 1 } + +The :program:`mongod` instance is unlocked for writes. diff --git a/source/tutorial/backup-with-filesystem-snapshots.txt b/source/tutorial/backup-with-filesystem-snapshots.txt index 7d3cdb5ad17..8cc16fc6070 100644 --- a/source/tutorial/backup-with-filesystem-snapshots.txt +++ b/source/tutorial/backup-with-filesystem-snapshots.txt @@ -334,14 +334,4 @@ backup process. If you have a :term:`replica set` configuration, then for your backup use a :term:`secondary` which is not receiving reads (i.e. :term:`hidden member`). -.. important:: - - In the following procedure to create backups, you **must** issue the - :method:`db.fsyncLock()` and :method:`db.fsyncUnlock()` operations - on the same connection. The client that issues - :method:`db.fsyncLock()` is solely responsible for issuing a - :method:`db.fsyncUnlock()` operation and must be able to handle - potential error conditions so that it can perform the - :method:`db.fsyncUnlock()` before terminating the connection. - .. include:: /includes/steps/backup-without-journaling.rst