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..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. 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 `. 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..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 -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 14be87084..8c2d22aef 100644 --- a/source/includes/fact-write-blocking-enable.rst +++ b/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 ` 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"``. -- 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 ` -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 ` +to set ``enableUserWriteBlocking`` to ``true``. + +You can use +:ref:`/start ` +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..02612a893 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 `. You can use destination-only + write-blocking. diff --git a/source/includes/live-upgrade.rst b/source/includes/live-upgrade.rst index 19f6a2215..761acbf71 100644 --- a/source/includes/live-upgrade.rst +++ b/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. 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..13c87f047 100644 --- a/source/reference/api/start.txt +++ b/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 ` endpoint reports + that ``canWrite`` is ``true``. Blocks writes on the source + cluster after ``mongosync`` calls the :ref:`/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``. diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 1b0f52aed..c2950c849 100644 --- a/source/reference/cutover-process.txt +++ b/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. diff --git a/source/reference/mongosync/mongosync-behavior.txt b/source/reference/mongosync/mongosync-behavior.txt index b2c633771..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 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 '''''''''''''''' @@ -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..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 -------------- @@ -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. diff --git a/source/reference/versioning.txt b/source/reference/versioning.txt index fc985f801..b526aedb8 100644 --- a/source/reference/versioning.txt +++ b/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. 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 new file mode 100644 index 000000000..69e08ef5a --- /dev/null +++ b/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 ` +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