From 78995e1ca07b2d8950fb46f6e817807e6ef4a86e Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 11:26:10 -0500 Subject: [PATCH 01/12] initial commit.. --- source/faq.txt | 3 +- .../fact-older-version-limitations.rst | 4 +-- source/includes/fact-permissions-body.rst | 2 +- .../includes/fact-write-blocking-enable.rst | 26 ++++++++++++----- source/includes/limitations-filtering.rst | 3 ++ source/includes/live-upgrade.rst | 2 +- source/includes/table-permissions-atlas.rst | 5 ++-- .../table-permissions-self-hosted.rst | 2 +- source/reference/api/commit.txt | 10 ++++--- source/reference/api/reverse.txt | 3 +- source/reference/api/start.txt | 29 ++++++++++--------- source/reference/cutover-process.txt | 17 +++++++---- .../mongosync/mongosync-behavior.txt | 9 ++++-- source/reference/permissions.txt | 2 +- source/release-notes/1.11.txt | 24 +++++++++++++++ 15 files changed, 99 insertions(+), 42 deletions(-) create mode 100644 source/release-notes/1.11.txt diff --git a/source/faq.txt b/source/faq.txt index d20c0c26b..a85a96a09 100644 --- a/source/faq.txt +++ b/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 ` 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. diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst index 63f14d446..fd06bb62f 100644 --- a/source/includes/fact-older-version-limitations.rst +++ b/source/includes/fact-older-version-limitations.rst @@ -29,8 +29,8 @@ enable the ``reversible`` option in the :ref:`/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. + request, so destination-only write-blocking is enabled. Ensure that no writes + are made to the source cluster during the migration. - You can't enable the ``createSupportingIndexes`` :ref:`sharding parameter `. Instead, create an index to support your shard key diff --git a/source/includes/fact-permissions-body.rst b/source/includes/fact-permissions-body.rst index 7b8b03c8c..9fbb66219 100644 --- a/source/includes/fact-permissions-body.rst +++ b/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. +dual write-blocking or reverse sync. diff --git a/source/includes/fact-write-blocking-enable.rst b/source/includes/fact-write-blocking-enable.rst index 14be87084..430c32425 100644 --- a/source/includes/fact-write-blocking-enable.rst +++ b/source/includes/fact-write-blocking-enable.rst @@ -1,9 +1,21 @@ -``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. +It unblocks writes right before ``canWrite`` is set to ``true``. -- On the destination cluster during sync. -- On the source cluster when ``commit`` is received. +You can enable dual write-blocking, which blocks +writes on both the source and destination clusters. +If you enable dual write-blocking, ``mongosync`` blocks writes: -To enable write-blocking, use the :ref:`start API ` -to set ``enableUserWriteBlocking`` to ``true``. You cannot enable -write-blocking after the sync starts. +- On the destination cluster during the migration and + unblocks them right before ``canWrite`` is set to ``true`` +- On the source cluster after ``/commit`` is called + +To enable dual write-blocking, use the :ref:`start API ` +to set ``enableUserWriteBlocking`` to ``true``. + +You can also disable write-blocking by using +the :ref:`start API ` +to set ``enableUserWriteBlocking`` to ``false``. + +You cannot enable dual write-blocking or disable +write-blocking after the sync starts. \ No newline at end of file diff --git a/source/includes/limitations-filtering.rst b/source/includes/limitations-filtering.rst index 9208921dc..71474ee80 100644 --- a/source/includes/limitations-filtering.rst +++ b/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 `. It supports destination-only + write-blocking. diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index 19f6a2215..de5f0ccf1 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -1,4 +1,4 @@ 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. +1.7.2 or later. You cannot live upgrade to ``mongosync`` 1.11. diff --git a/source/includes/table-permissions-atlas.rst b/source/includes/table-permissions-atlas.rst index ae44fed69..b1ed3f7c3 100644 --- a/source/includes/table-permissions-atlas.rst +++ b/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 diff --git a/source/includes/table-permissions-self-hosted.rst b/source/includes/table-permissions-self-hosted.rst index 453b5847e..ac3365c7b 100644 --- a/source/includes/table-permissions-self-hosted.rst +++ b/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` diff --git a/source/reference/api/commit.txt b/source/reference/api/commit.txt index a9a9310fb..ed7d0fc01 100644 --- a/source/reference/api/commit.txt +++ b/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 diff --git a/source/reference/api/reverse.txt b/source/reference/api/reverse.txt index 69fd74026..efeb69a91 100644 --- a/source/reference/api/reverse.txt +++ b/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 ` is a + prerequisite for running ``reverse``. You cannot update these options after the sync starts. diff --git a/source/reference/api/start.txt b/source/reference/api/start.txt index b4c358c32..fcd98f998 100644 --- a/source/reference/api/start.txt +++ b/source/reference/api/start.txt @@ -113,19 +113,25 @@ 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`` or ``"true"``, blocks writes on the destination + cluster while the migration is in progress, and unblocks writes right + before ``canWrite`` is ``true``. Blocks writes on the source + cluster after ``mongosync`` calls the :ref:`/commit ` + endpoint. + + If set to ``false`` or ``"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``. To reverse sync, the ``enableUserWriteBlocking`` field must be set - to ``true``. To allow the source cluster to accept writes again, + to ``true`` or ``"true"``. To allow the source cluster to accept writes again, for example after running migration tests, run the following command: @@ -133,7 +139,7 @@ Request Body Parameters db.adminCommand( { setUserWriteBlockMode: 1, global: false } ) - Default value is ``false``. + Default value is ``"destinationOnly"``. * - ``includeNamespaces`` - array @@ -160,7 +166,7 @@ Request Body Parameters reversed. To reverse sync, the ``enableUserWriteBlocking`` field must be set - to ``true``. + to ``true`` or ``"true"``. This option is not supported for the following configurations: @@ -170,10 +176,7 @@ 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. + * Reversible sync with the embedded verifier. :gold:`IMPORTANT:` If you are migrating from a pre-6.0 source cluster, you cannot set ``reversible`` to ``true``. diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 1b0f52aed..c465ad181 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -76,10 +76,16 @@ Steps .. step:: Stop any write operations to the synced collections on the source. - 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``. It blocks writes on the source after it calls + ``/commit``. + - If you start ``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 ``false``, ensure that you disable writes. For example, run the :dbcommand:`setUserWriteBlockMode` command on the source cluster: @@ -120,7 +126,8 @@ Steps to ensure that the ``mongosync`` state is ``COMMITTING`` or ``COMMITTED``. - Once you complete this step, ``mongosync`` blocks writes on the source cluster. + Once you complete this step, if you previously set ``enableUserWriteBlocking`` + to ``true`` then ``mongosync`` blocks writes on the source cluster. .. step:: Wait until you can perform writes on the destination cluster. diff --git a/source/reference/mongosync/mongosync-behavior.txt b/source/reference/mongosync/mongosync-behavior.txt index b2c633771..76af3c15a 100644 --- a/source/reference/mongosync/mongosync-behavior.txt +++ b/source/reference/mongosync/mongosync-behavior.txt @@ -163,7 +163,7 @@ Write Blocking .. include:: /includes/fact-write-blocking-enable.rst -You must enable write-blocking when you start ``mongosync`` if you want +You must enable dual write-blocking when you start ``mongosync`` if you want to use :ref:`reverse synchronization ` later. 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 diff --git a/source/reference/permissions.txt b/source/reference/permissions.txt index 0e0a35117..32e44a3f3 100644 --- a/source/reference/permissions.txt +++ b/source/reference/permissions.txt @@ -36,4 +36,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. diff --git a/source/release-notes/1.11.txt b/source/release-notes/1.11.txt new file mode 100644 index 000000000..021aa0816 --- /dev/null +++ b/source/release-notes/1.11.txt @@ -0,0 +1,24 @@ +.. _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 From 2323724c6da2b4ed8d42956b4fc3507c3ae5276c Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 11:28:41 -0500 Subject: [PATCH 02/12] little fix --- source/includes/fact-older-version-limitations.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst index fd06bb62f..c2746e4fa 100644 --- a/source/includes/fact-older-version-limitations.rst +++ b/source/includes/fact-older-version-limitations.rst @@ -29,8 +29,8 @@ enable the ``reversible`` option in the :ref:`/start ` request. - You can't enable the ``enableUserWriteBlocking`` option in the ``/start`` - request, so destination-only write-blocking is enabled. Ensure that no writes - are made to the source cluster during the migration. + request, so destination-only write-blocking is enabled by default. + Ensure that no writes are made to the destination cluster during the migration. - You can't enable the ``createSupportingIndexes`` :ref:`sharding parameter `. Instead, create an index to support your shard key From dc1282481666f0d3248ba7194d6b6ca8f0e54dd6 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 12:00:23 -0500 Subject: [PATCH 03/12] changes --- source/reference/api/start.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/reference/api/start.txt b/source/reference/api/start.txt index fcd98f998..df56322e7 100644 --- a/source/reference/api/start.txt +++ b/source/reference/api/start.txt @@ -176,8 +176,6 @@ Request Body Parameters * Reversible sync when ``buildIndexes`` is set to ``never``. - * Reversible sync with the embedded verifier. - :gold:`IMPORTANT:` If you are migrating from a pre-6.0 source cluster, you cannot set ``reversible`` to ``true``. From 4d25ce3c6eadb850027dd8eba07bc0679e4fdff4 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 12:26:22 -0500 Subject: [PATCH 04/12] release notes --- source/release-notes.txt | 4 +++- source/release-notes/1.11.txt | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/source/release-notes.txt b/source/release-notes.txt index bbb47e6ec..9fc27463f 100644 --- a/source/release-notes.txt +++ b/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 1.10 1.9 1.8 diff --git a/source/release-notes/1.11.txt b/source/release-notes/1.11.txt index 021aa0816..1798e3f2c 100644 --- a/source/release-notes/1.11.txt +++ b/source/release-notes/1.11.txt @@ -21,4 +21,4 @@ This page describes changes and new features introduced in Destination-Only Write-Blocking ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- .. include:: /includes/fact-write-blocking-enable.rst +.. include:: /includes/fact-write-blocking-enable.rst From 1f2e3f767b99aff6394e797678e3bfd623d46c07 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 15:26:31 -0500 Subject: [PATCH 05/12] feedback --- source/includes/fact-older-version-limitations.rst | 2 +- source/includes/fact-write-blocking-enable.rst | 10 +++++----- source/includes/limitations-filtering.rst | 2 +- source/reference/cutover-process.txt | 7 ++++--- source/reference/mongosync/mongosync-behavior.txt | 6 +++--- 5 files changed, 14 insertions(+), 13 deletions(-) diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst index c2746e4fa..f1722917e 100644 --- a/source/includes/fact-older-version-limitations.rst +++ b/source/includes/fact-older-version-limitations.rst @@ -29,7 +29,7 @@ enable the ``reversible`` option in the :ref:`/start ` request. - You can't enable the ``enableUserWriteBlocking`` option in the ``/start`` - request, so destination-only write-blocking is enabled by default. + request, so ``mongosync`` enables destination-only write-blocking by default. Ensure that no writes are made to the destination cluster during the migration. - You can't enable the ``createSupportingIndexes`` :ref:`sharding parameter diff --git a/source/includes/fact-write-blocking-enable.rst b/source/includes/fact-write-blocking-enable.rst index 430c32425..b7b0610c8 100644 --- a/source/includes/fact-write-blocking-enable.rst +++ b/source/includes/fact-write-blocking-enable.rst @@ -1,19 +1,19 @@ By default, ``mongosync`` enables destination-only write-blocking on the destination cluster. -It unblocks writes right before ``canWrite`` is set to ``true``. +``mongosync`` unblocks writes right before ``canWrite`` is set to ``true``. You can enable dual write-blocking, which blocks writes on both the source and destination clusters. If you enable dual write-blocking, ``mongosync`` blocks writes: -- On the destination cluster during the migration and - unblocks them right before ``canWrite`` is set to ``true`` -- On the source cluster after ``/commit`` is called +- 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 the :ref:`start API ` to set ``enableUserWriteBlocking`` to ``true``. -You can also disable write-blocking by using +You can use the :ref:`start API ` to set ``enableUserWriteBlocking`` to ``false``. diff --git a/source/includes/limitations-filtering.rst b/source/includes/limitations-filtering.rst index 71474ee80..02612a893 100644 --- a/source/includes/limitations-filtering.rst +++ b/source/includes/limitations-filtering.rst @@ -20,6 +20,6 @@ For more information, see :ref:`c2c-filter-with-out`. - Filtering does not support dual :ref:`write - blocking `. It supports destination-only + blocking `. You can use destination-only write-blocking. diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index c465ad181..b72e53aa3 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -78,7 +78,7 @@ Steps - If you start ``mongosync`` with ``enableUserWriteBlocking`` set to ``true``, ``mongosync`` blocks all write operations on the destination cluster and unblocks them right before ``canWrite`` - is set to ``true``. It blocks writes on the source after it calls + is set to ``true``. ``mongosync`` blocks writes on the source after it calls ``/commit``. - If you start ``mongosync`` with ``enableUserWriteBlocking`` set to ``"destinationOnly"``, ``mongosync`` only blocks writes on the @@ -126,8 +126,9 @@ Steps to ensure that the ``mongosync`` state is ``COMMITTING`` or ``COMMITTED``. - Once you complete this step, if you previously set ``enableUserWriteBlocking`` - to ``true`` then ``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. diff --git a/source/reference/mongosync/mongosync-behavior.txt b/source/reference/mongosync/mongosync-behavior.txt index 76af3c15a..406e1220b 100644 --- a/source/reference/mongosync/mongosync-behavior.txt +++ b/source/reference/mongosync/mongosync-behavior.txt @@ -163,8 +163,8 @@ Write Blocking .. include:: /includes/fact-write-blocking-enable.rst -You must enable dual write-blocking when you start ``mongosync`` if you want -to use :ref:`reverse synchronization ` later. +If you want to use :ref:`reverse synchronization ` later, +you must enable dual write-blocking when you start ``mongosync``. User Permissions '''''''''''''''' @@ -263,7 +263,7 @@ synchronization. The original values are restored during the commit process. ``mongosync`` enables destination-only write-blocking by default. - + To learn more, see :ref:`c2c-write-blocking`. * - Capped Collections From a6270061204bf05591da1e1841f0b5cde99aff5e Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 3 Feb 2025 15:29:41 -0500 Subject: [PATCH 06/12] little changes --- source/reference/cutover-process.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index b72e53aa3..f5bae0fb5 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -78,7 +78,7 @@ Steps - If you start ``mongosync`` with ``enableUserWriteBlocking`` 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 it calls + is set to ``true``. ``mongosync`` blocks writes on the source after you call ``/commit``. - If you start ``mongosync`` with ``enableUserWriteBlocking`` set to ``"destinationOnly"``, ``mongosync`` only blocks writes on the From 7d42b1465a8d435e821117c55efe663abbb4b634 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 13:10:17 -0500 Subject: [PATCH 07/12] feedback --- .../fact-older-version-limitations.rst | 4 ++-- source/includes/fact-write-blocking-enable.rst | 11 ++++++++--- source/includes/live-upgrade.rst | 18 ++++++++++++++---- source/reference/api/start.txt | 11 ++++++----- source/reference/permissions.txt | 2 ++ source/reference/versioning.txt | 6 ++++++ source/release-notes/1.11.txt | 13 +++++++++++++ 7 files changed, 51 insertions(+), 14 deletions(-) diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst index f1722917e..dc417daec 100644 --- a/source/includes/fact-older-version-limitations.rst +++ b/source/includes/fact-older-version-limitations.rst @@ -29,8 +29,8 @@ enable the ``reversible`` option in the :ref:`/start ` request. - You can't enable the ``enableUserWriteBlocking`` option in the ``/start`` - request, so ``mongosync`` enables destination-only write-blocking by default. - Ensure that no writes are made to the destination cluster during the migration. + request, so dual write-blocking is not supported. Destination-only + write-blocking is supported. - You can't enable the ``createSupportingIndexes`` :ref:`sharding parameter `. Instead, create an index to support your shard key diff --git a/source/includes/fact-write-blocking-enable.rst b/source/includes/fact-write-blocking-enable.rst index b7b0610c8..337277ceb 100644 --- a/source/includes/fact-write-blocking-enable.rst +++ b/source/includes/fact-write-blocking-enable.rst @@ -1,6 +1,11 @@ By default, ``mongosync`` enables destination-only write-blocking on the destination cluster. -``mongosync`` unblocks writes right before ``canWrite`` is set to ``true``. +``mongosync`` unblocks writes right before the +:ref:`/progress ` endpoint reports +that ``canWrite`` is ``true``. You can explicitly +enable destination-only write-blocking by using +the :ref:`/start ` endpoint to set +``enableUserWriteBlocking`` to ``"destinationOnly"``. You can enable dual write-blocking, which blocks writes on both the source and destination clusters. @@ -10,11 +15,11 @@ If you enable dual write-blocking, ``mongosync`` blocks writes: unblocks writes right before it sets ``canWrite`` to ``true`` - On the source cluster after you call ``/commit`` -To enable dual write-blocking, use the :ref:`start API ` +To enable dual write-blocking, use :ref:`/start ` to set ``enableUserWriteBlocking`` to ``true``. You can use -the :ref:`start API ` +:ref:`/start ` to set ``enableUserWriteBlocking`` to ``false``. You cannot enable dual write-blocking or disable diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index de5f0ccf1..82e30446b 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -1,4 +1,14 @@ -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. You cannot live upgrade to ``mongosync`` 1.11. +.. list-table + :header-rows: 1 + :stub-columns: 1 + + * - Version + - 1.11 + - 1.7.2 and later + - 1.7.0 + + * - Notes + - Live upgrades to 1.11 not supported + - Can only live upgrade to ``mongosync`` + 1.7.3 or later + - Upgrade to any version except 1.11 diff --git a/source/reference/api/start.txt b/source/reference/api/start.txt index df56322e7..13c87f047 100644 --- a/source/reference/api/start.txt +++ b/source/reference/api/start.txt @@ -115,13 +115,14 @@ Request Body Parameters * - ``enableUserWriteBlocking`` - boolean or string - Optional - - If set to ``true`` or ``"true"``, blocks writes on the destination + - If set to ``true``, blocks writes on the destination cluster while the migration is in progress, and unblocks writes right - before ``canWrite`` is ``true``. Blocks writes on the source + before the :ref:`/progress ` endpoint reports + that ``canWrite`` is ``true``. Blocks writes on the source cluster after ``mongosync`` calls the :ref:`/commit ` endpoint. - If set to ``false`` or ``"false"``, no write blocking occurs. + 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 @@ -131,7 +132,7 @@ Request Body Parameters you cannot set ``enableUserWriteBlocking`` to ``true``. To reverse sync, the ``enableUserWriteBlocking`` field must be set - to ``true`` or ``"true"``. To allow the source cluster to accept writes again, + to ``true``. To allow the source cluster to accept writes again, for example after running migration tests, run the following command: @@ -166,7 +167,7 @@ Request Body Parameters reversed. To reverse sync, the ``enableUserWriteBlocking`` field must be set - to ``true`` or ``"true"``. + to ``true``. This option is not supported for the following configurations: diff --git a/source/reference/permissions.txt b/source/reference/permissions.txt index 32e44a3f3..1db1e6195 100644 --- a/source/reference/permissions.txt +++ b/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 -------------- diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt index fc985f801..a8a96cd50 100644 --- a/source/reference/versioning.txt +++ b/source/reference/versioning.txt @@ -65,6 +65,12 @@ Live Upgrade .. versionadded:: 1.7.0 +Starting in ``mongosync`` 1.7.0, you can upgrade ``mongosync`` without +restarting data synchronization operations from the beginning. + +For more information on what versions you can live upgrade to or from, +see the following table: + .. include:: /includes/live-upgrade.rst After the live upgrade, ``mongosync`` continues operations that were in diff --git a/source/release-notes/1.11.txt b/source/release-notes/1.11.txt index 1798e3f2c..69e08ef5a 100644 --- a/source/release-notes/1.11.txt +++ b/source/release-notes/1.11.txt @@ -22,3 +22,16 @@ Destination-Only Write-Blocking ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fact-write-blocking-enable.rst + +Live Upgrades +~~~~~~~~~~~~~ + +:ref:`Live upgrades ` +to version 1.11 are not supported. + +Permissions +~~~~~~~~~~~ + +``mongosync`` requires additional permissions +on Atlas destination clusters for default migrations. +See :ref:`c2c-atlas-permissions`. \ No newline at end of file From 7bf1ca275ad45c8a2eb47af200f0b9e2d3b668c8 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 13:51:29 -0500 Subject: [PATCH 08/12] table first draft --- source/includes/live-upgrade.rst | 37 ++++++++++++++++++++++++-------- source/reference/versioning.txt | 3 +-- 2 files changed, 29 insertions(+), 11 deletions(-) diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index 82e30446b..520bc1fd3 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -2,13 +2,32 @@ :header-rows: 1 :stub-columns: 1 - * - Version - - 1.11 - - 1.7.2 and later - - 1.7.0 + * - + - 1.11 Destination + - 1.7.3 to 1.10 Destination + - 1.7.2 Destination + - 1.7.0 to 1.7.1 Destination - * - Notes - - Live upgrades to 1.11 not supported - - Can only live upgrade to ``mongosync`` - 1.7.3 or later - - Upgrade to any version except 1.11 + * - 1.11 Source + - + - + - + - + + * - 1.7.3 to 1.10 Source + - + - √ + - + - + + * - 1.7.2 Source + - + - √ + - + - + + * - 1.7.0 to 1.7.1 Source + - + - √ + - √ + - \ No newline at end of file diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt index a8a96cd50..2318cf4fd 100644 --- a/source/reference/versioning.txt +++ b/source/reference/versioning.txt @@ -68,8 +68,7 @@ Live Upgrade Starting in ``mongosync`` 1.7.0, you can upgrade ``mongosync`` without restarting data synchronization operations from the beginning. -For more information on what versions you can live upgrade to or from, -see the following table: +``mongosync`` supports live upgrades between the following versions: .. include:: /includes/live-upgrade.rst From 117a5ce5379276b3f1d4cb82101a3b3f35444593 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 14:01:31 -0500 Subject: [PATCH 09/12] typo --- source/includes/live-upgrade.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index 520bc1fd3..be10dc441 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -1,4 +1,4 @@ -.. list-table +.. list-table:: :header-rows: 1 :stub-columns: 1 From 13e238bdfccaf75bc8a5b3c8acc2ae1b7119862e Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 15:28:03 -0500 Subject: [PATCH 10/12] de-modify --- source/includes/live-upgrade.rst | 37 ++++---------------------------- source/reference/versioning.txt | 4 ++-- 2 files changed, 6 insertions(+), 35 deletions(-) diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index be10dc441..71da7c2a0 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -1,33 +1,4 @@ -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - - * - - - 1.11 Destination - - 1.7.3 to 1.10 Destination - - 1.7.2 Destination - - 1.7.0 to 1.7.1 Destination - - * - 1.11 Source - - - - - - - - - - * - 1.7.3 to 1.10 Source - - - - √ - - - - - - * - 1.7.2 Source - - - - √ - - - - - - * - 1.7.0 to 1.7.1 Source - - - - √ - - √ - - \ No newline at end of file +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. \ No newline at end of file diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt index 2318cf4fd..432aa0ac5 100644 --- a/source/reference/versioning.txt +++ b/source/reference/versioning.txt @@ -68,9 +68,9 @@ Live Upgrade Starting in ``mongosync`` 1.7.0, you can upgrade ``mongosync`` without restarting data synchronization operations from the beginning. -``mongosync`` supports live upgrades between the following versions: +.. important:: -.. include:: /includes/live-upgrade.rst + ``mongosync`` does not support upgrades to version 1.11. After the live upgrade, ``mongosync`` continues operations that were in progress before the upgrade. From 5768117dc4920fd38af85f443d92a95583c9d27c Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 16:30:35 -0500 Subject: [PATCH 11/12] small fix --- source/reference/versioning.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt index 432aa0ac5..b526aedb8 100644 --- a/source/reference/versioning.txt +++ b/source/reference/versioning.txt @@ -70,7 +70,7 @@ restarting data synchronization operations from the beginning. .. important:: - ``mongosync`` does not support upgrades to version 1.11. + ``mongosync`` does not support live upgrades to version 1.11. After the live upgrade, ``mongosync`` continues operations that were in progress before the upgrade. From 50af2f12ae4e812197cb91a32f5ac38f45476549 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 4 Feb 2025 16:57:26 -0500 Subject: [PATCH 12/12] feedback --- source/includes/fact-older-version-limitations.rst | 7 ++++--- source/includes/fact-permissions-body.rst | 4 ++-- source/includes/fact-write-blocking-enable.rst | 3 +-- source/includes/live-upgrade.rst | 6 +++++- source/reference/cutover-process.txt | 10 ++++++---- 5 files changed, 18 insertions(+), 12 deletions(-) diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst index dc417daec..65cbb3d21 100644 --- a/source/includes/fact-older-version-limitations.rst +++ b/source/includes/fact-older-version-limitations.rst @@ -28,9 +28,10 @@ - :ref:`/reverse ` endpoint is not supported. You can't enable the ``reversible`` option in the :ref:`/start ` request. -- You can't enable the ``enableUserWriteBlocking`` option in the ``/start`` - request, so dual write-blocking is not supported. Destination-only - write-blocking is supported. +- 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 `. Instead, create an index to support your shard key diff --git a/source/includes/fact-permissions-body.rst b/source/includes/fact-permissions-body.rst index 9fbb66219..6ab11098e 100644 --- a/source/includes/fact-permissions-body.rst +++ b/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 -dual write-blocking or reverse sync. +permissions vary depending on your environment and if you want to +modify write-blocking settings or use reverse sync. diff --git a/source/includes/fact-write-blocking-enable.rst b/source/includes/fact-write-blocking-enable.rst index 337277ceb..8c2d22aef 100644 --- a/source/includes/fact-write-blocking-enable.rst +++ b/source/includes/fact-write-blocking-enable.rst @@ -7,8 +7,7 @@ enable destination-only write-blocking by using the :ref:`/start ` endpoint to set ``enableUserWriteBlocking`` to ``"destinationOnly"``. -You can enable dual write-blocking, which blocks -writes on both the source and destination clusters. +You can enable dual write-blocking. If you enable dual write-blocking, ``mongosync`` blocks writes: - On the destination cluster during the migration. ``mongosync`` diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index 71da7c2a0..761acbf71 100644 --- a/source/includes/live-upgrade.rst +++ b/source/includes/live-upgrade.rst @@ -1,4 +1,8 @@ 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. \ No newline at end of file +1.7.2 or later. + +.. important:: + + ``mongosync`` does not support live upgrades to version 1.11. diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index f5bae0fb5..c2950c849 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -75,15 +75,17 @@ 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 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 ``"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 ``false``, ensure that you disable writes. For example, run the :dbcommand:`setUserWriteBlockMode` command on the