DOCSP-46893: Destination-only Write-blocking

source/faq.txt

@@ -33,7 +33,8 @@ As a result, the destination is not guaranteed to match the source at any point
 For consistent reads, wait for the migration to :ref:`c2c-api-commit`. To learn more, see :ref:`mongosync-considerations`. 
 
 Performing writes to your destination cluster during synchronization results in undefined behavior. 
-To block writes on the destination cluster during sync, enable :ref:`write blocking <c2c-write-blocking>` when you :ref:`c2c-api-start` ``mongosync``.
+``mongosync`` blocks writes on the destination cluster by default. To learn
+more about write-blocking, see :ref:`c2c-write-blocking` and :ref:`c2c-api-start`.
 
 Upon commit, it is only safe to write to the destination cluster when ``canWrite`` is ``true``. 
 To check the value of ``canWrite``, run the :ref:`c2c-api-progress` endpoint.

source/includes/fact-older-version-limitations.rst

@@ -28,9 +28,10 @@
 - :ref:`/reverse <c2c-api-reverse>` endpoint is not supported. You can't 
   enable the ``reversible`` option in the :ref:`/start <c2c-api-start>` request.
 
-- You can't enable the ``enableUserWriteBlocking`` option in the ``/start`` 
-  request. Ensure that no writes are made to the source or destination cluster 
-  during the migration.
+- You can't set the ``enableUserWriteBlocking`` option to ``true``
+  in the ``/start`` request, so dual write-blocking is not supported. 
+  Destination-only write-blocking is supported. Ensure that no writes are 
+  made to the source cluster after you call the ``/commit`` endpoint.
 
 - You can't enable the ``createSupportingIndexes`` :ref:`sharding parameter 
   <c2c-api-start-sharding>`. Instead, create an index to support your shard key 

source/includes/fact-permissions-body.rst

@@ -1,5 +1,5 @@
 The user specified in the ``mongosync`` connection string must have the
 required permissions on the source and destination clusters. The
-permissions vary depending on your environment and if you want to run a
-write-blocking or reverse sync.
+permissions vary depending on your environment and if you want to 
+modify write-blocking settings or use reverse sync.
 

source/includes/fact-write-blocking-enable.rst

@@ -1,9 +1,25 @@
-``mongosync`` does not enable write-blocking by default. If you enable
-write-blocking, ``mongosync`` blocks writes:
+By default, ``mongosync`` enables destination-only 
+write-blocking on the destination cluster. 
+``mongosync`` unblocks writes right before the 
+:ref:`/progress <c2c-api-progress>` endpoint reports 
+that ``canWrite`` is ``true``. You can explicitly
+enable destination-only write-blocking by using
+the :ref:`/start <c2c-api-start>` endpoint to set
+``enableUserWriteBlocking`` to ``"destinationOnly"``.
 
-- On the destination cluster during sync.
-- On the source cluster when ``commit`` is received.
+You can enable dual write-blocking. 
+If you enable dual write-blocking, ``mongosync`` blocks writes:
 
-To enable write-blocking, use the :ref:`start API <c2c-api-start>`
-to set ``enableUserWriteBlocking`` to ``true``. You cannot enable
-write-blocking after the sync starts.
+- On the destination cluster during the migration. ``mongosync``
+  unblocks writes right before it sets ``canWrite`` to ``true``
+- On the source cluster after you call ``/commit``
+
+To enable dual write-blocking, use :ref:`/start <c2c-api-start>`
+to set ``enableUserWriteBlocking`` to ``true``.
+
+You can use
+:ref:`/start <c2c-api-start>`
+to set ``enableUserWriteBlocking`` to ``false``.
+
+You cannot enable dual write-blocking or disable
+write-blocking after the sync starts.

source/includes/limitations-filtering.rst

@@ -19,4 +19,7 @@
   You cannot limit the filter to collections within the database.
 
   For more information, see :ref:`c2c-filter-with-out`.
+- Filtering does not support dual :ref:`write 
+  blocking <c2c-write-blocking>`. You can use destination-only
+  write-blocking. 
 

source/includes/live-upgrade.rst

@@ -2,3 +2,7 @@ Starting in ``mongosync`` 1.7.0, you can upgrade ``mongosync`` without
 restarting data synchronization operations from the beginning. You can 
 only live upgrade to ``mongosync`` 1.7.3 or later from ``mongosync`` 
 1.7.2 or later.
+
+.. important::
+
+   ``mongosync`` does not support live upgrades to version 1.11.

source/includes/table-permissions-atlas.rst

@@ -13,8 +13,9 @@
    * - default
      - - atlasAdmin
      - - atlasAdmin
-
-   * - write-blocking, reversing, or multiple reversals
+       - bypassWriteBlockMode privilege
+
+   * - dual write-blocking, reversing, or multiple reversals
      - - atlasAdmin
        - bypassWriteBlockMode privilege
      - - atlasAdmin

source/includes/table-permissions-self-hosted.rst

@@ -21,7 +21,7 @@
        - :authrole:`readWriteAnyDatabase`
        - :authrole:`restore`
 
-   * - Write-blocking
+   * - Dual Write-Blocking
      - - :authrole:`backup`
        - :authrole:`clusterManager`
        - :authrole:`clusterMonitor`

source/reference/api/commit.txt

@@ -168,13 +168,15 @@ characteristics that ``mongosync`` alters during the synchronization process.
        replicated as non-hidden on the destination cluster.
 
    * - Write Blocking
-     - If you enable write-blocking, ``mongosync`` blocks writes: 
-       
+     - If you enable dual write-blocking, ``mongosync`` blocks writes: 
+
        - On the destination cluster during sync.
        - On the source cluster when ``commit`` is received.
 
-       See also:
-       :ref:`c2c-write-blocking`
+       ``mongosync`` enables destination-only write-blocking
+       by default.
+
+       To learn more, see :ref:`c2c-write-blocking`.
 
    * - Capped Collections
      - ``commit`` resets the required maximum size of capped collections

source/reference/api/reverse.txt

@@ -49,7 +49,8 @@ To use the ``reverse`` endpoint:
 
 .. note::
 
-   :ref:`c2c-write-blocking` is a prerequisite for running ``reverse``.
+   :ref:`Dual write-blocking <c2c-write-blocking>` is a 
+   prerequisite for running ``reverse``.
 
 You cannot update these options after the sync starts. 
 

source/reference/api/start.txt

@@ -113,13 +113,20 @@ Request Body Parameters
        .. versionadded:: 1.3.0
 
    * - ``enableUserWriteBlocking``
-     - boolean
+     - boolean or string
      - Optional
-     - If set to ``true``, blocks writes on the destination cluster
-       while the synchronization is in progress. After the
-       synchronization is committed to the destination cluster, the
-       original source cluster blocks writes and the destination cluster
-       accepts writes.
+     - If set to ``true``, blocks writes on the destination 
+       cluster while the migration is in progress, and unblocks writes right
+       before the :ref:`/progress <c2c-api-progress>` endpoint reports 
+       that ``canWrite`` is ``true``.  Blocks writes on the source
+       cluster after ``mongosync`` calls the :ref:`/commit <c2c-api-commit>`
+       endpoint.
+
+       If set to ``false``, no write blocking occurs.
+
+       If set to ``"destinationOnly"``, blocks writes on the destination
+       cluster while migration is in progress, and unblocks writes right
+       before ``canWrite`` is ``true``.
 
        :gold:`IMPORTANT:` If you are migrating from a pre-6.0 source cluster, 
        you cannot set ``enableUserWriteBlocking`` to ``true``.
@@ -133,7 +140,7 @@ Request Body Parameters
 
           db.adminCommand( { setUserWriteBlockMode: 1, global: false } )
 
-       Default value is ``false``.
+       Default value is ``"destinationOnly"``.
 
    * - ``includeNamespaces``
      - array
@@ -170,11 +177,6 @@ Request Body Parameters
 
        * Reversible sync when ``buildIndexes`` is set to ``never``.
 
-       * Reversible sync with the embedded verifier. The
-         verifier supports the initial forward direction of
-         reversible sync. When you call the ``/reverse``
-         endpoint it disables the verifier.
-
        :gold:`IMPORTANT:` If you are migrating from a pre-6.0 source cluster, 
        you cannot set ``reversible`` to ``true``.
 

source/reference/cutover-process.txt

@@ -75,11 +75,19 @@ Steps
 
    .. step:: Stop any write operations to the synced collections on the source.
 
+      - ``mongosync`` enables destination-only write-blocking by default. 
+        You can explicitly enable it by starting ``mongosync`` with
+        ``enableUserWriteBlocking`` set to ``"destinationOnly"``.
+        ``mongosync`` only blocks writes on the 
+        destination and unblocks them right before ``canWrite`` is
+        set to ``true``.
       - If you start ``mongosync`` with ``enableUserWriteBlocking``
-        set to ``true``, ``mongosync`` blocks all write operations on
-        the entire source cluster during the commit (step 4) for you.
-      - If you didn't start ``mongosync`` with
-        ``enableUserWriteBlocking``, ensure that you disable writes.
+        set to ``true``, ``mongosync`` blocks all write operations
+        on the destination cluster and unblocks them right before ``canWrite``
+        is set to ``true``. ``mongosync`` blocks writes on the source after you call
+        ``/commit``.
+      - If you start ``mongosync`` with ``enableUserWriteBlocking`` set
+        to ``false``, ensure that you disable writes.
         For example, run the :dbcommand:`setUserWriteBlockMode` command on the
         source cluster:
 
@@ -120,7 +128,9 @@ Steps
          to ensure that the ``mongosync`` state is ``COMMITTING`` or
          ``COMMITTED``.
 
-      Once you complete this step, ``mongosync`` blocks writes on the source cluster.
+      If you previously set ``enableUserWriteBlocking``
+      to ``true``, ``mongosync`` blocks writes on the source cluster
+      once you complete this step.
 
    .. step:: Wait until you can perform writes on the destination cluster.
 

source/reference/mongosync/mongosync-behavior.txt

@@ -163,8 +163,8 @@ Write Blocking
 
 .. include:: /includes/fact-write-blocking-enable.rst
 
-You must enable write-blocking when you start ``mongosync`` if you want
-to use :ref:`reverse synchronization <c2c-api-reverse>` later.
+If you want to use :ref:`reverse synchronization <c2c-api-reverse>` later,
+you must enable dual write-blocking when you start ``mongosync``.
 
 User Permissions
 ''''''''''''''''
@@ -256,11 +256,14 @@ synchronization. The original values are restored during the commit process.
      - Synchronization replicates hidden indexes as non-hidden.
 
    * - Write Blocking
-     - If you enable write-blocking, ``mongosync`` blocks writes: 
+     - If you enable dual write-blocking, ``mongosync`` blocks writes: 
 
        - On the destination cluster during sync.
        - On the source cluster when ``commit`` is received.
-
+
+       ``mongosync`` enables destination-only write-blocking
+       by default.
+
        To learn more, see :ref:`c2c-write-blocking`.
 
    * - Capped Collections

source/reference/permissions.txt

@@ -21,6 +21,8 @@ The self-managed permissions are:
 
 .. include:: /includes/table-permissions-self-hosted.rst
 
+.. _c2c-atlas-permissions:
+
 Atlas Clusters
 --------------
 
@@ -36,4 +38,4 @@ Pre-6.0 Migrations
 - When migrating from a 4.4 source cluster, you must have 
   :authrole:`clusterManager` permissions on the source cluster.
 
-- Write blocking and reverse sync are not supported.
+- Dual write-blocking and reverse sync are not supported.

source/reference/versioning.txt

@@ -65,7 +65,12 @@ Live Upgrade
 
 .. versionadded:: 1.7.0
 
-.. include:: /includes/live-upgrade.rst
+Starting in ``mongosync`` 1.7.0, you can upgrade ``mongosync`` without
+restarting data synchronization operations from the beginning.
+
+.. important::
+
+   ``mongosync`` does not support live upgrades to version 1.11.
 
 After the live upgrade, ``mongosync`` continues operations that were in
 progress before the upgrade.

source/release-notes.txt

@@ -14,11 +14,12 @@ release notes.
 Current Stable Release
 ~~~~~~~~~~~~~~~~~~~~~~
 
-- :ref:`c2c-release-notes-1.10`
+- :ref:`c2c-release-notes-1.11`
 
 Previous Releases
 ~~~~~~~~~~~~~~~~~
 
+- :ref:`c2c-release-notes-1.10`
 - :ref:`c2c-release-notes-1.9`
 - :ref:`c2c-release-notes-1.8`
 - :ref:`c2c-release-notes-1.7`
@@ -36,6 +37,7 @@ Previous Releases
 .. toctree::
    :titlesonly: 
 
+   1.11 </release-notes/1.11>
    1.10 </release-notes/1.10>
    1.9 </release-notes/1.9>
    1.8 </release-notes/1.8>

source/release-notes/1.11.txt

@@ -0,0 +1,37 @@
+.. _c2c-release-notes-1.11:
+
+================================
+Release Notes for mongosync 1.11
+================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+This page describes changes and new features introduced in  
+{+c2c-full-product-name+} 1.11.
+
+.. _1.11.0-c2c-release-notes:
+
+1.11.0 Release
+--------------
+
+Destination-Only Write-Blocking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/fact-write-blocking-enable.rst
+
+Live Upgrades
+~~~~~~~~~~~~~
+
+:ref:`Live upgrades <c2c-versioning-live-upgrade>` 
+to version 1.11 are not supported.
+
+Permissions
+~~~~~~~~~~~
+
+``mongosync`` requires additional permissions
+on Atlas destination clusters for default migrations.
+See :ref:`c2c-atlas-permissions`.