DOCSP-46893: Destination-only Write-blocking (#581)

* initial commit..

* little fix

* changes

* release notes

* feedback

* little changes

* feedback

* table first draft

* typo

* de-modify

* small fix

* feedback

Author: mayaraman19

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.