diff --git a/source/includes/cross-version-sync.rst b/source/includes/cross-version-sync.rst index af84c63a5..646a8aa8b 100644 --- a/source/includes/cross-version-sync.rst +++ b/source/includes/cross-version-sync.rst @@ -1,9 +1,3 @@ Starting in 1.7.0, ``mongosync`` can perform version migration from certain lower major version source clusters to certain higher major version destination clusters. - -Cross-version migration requires additional preparation and -configuration when migrating from a pre-6.0 release. To perform a cross-version -migration from a pre-6.0 version of the MongoDB Server using -``mongosync``, please `contact `__ your -account team to inquire about Professional Services. diff --git a/source/includes/fact-minimum-fcv.rst b/source/includes/fact-minimum-fcv.rst deleted file mode 100644 index 4cbdd41d5..000000000 --- a/source/includes/fact-minimum-fcv.rst +++ /dev/null @@ -1,2 +0,0 @@ -The minimum supported server :ref:`feature compatibility version ` -is 6.0. diff --git a/source/includes/fact-older-version-limitations.rst b/source/includes/fact-older-version-limitations.rst new file mode 100644 index 000000000..63f14d446 --- /dev/null +++ b/source/includes/fact-older-version-limitations.rst @@ -0,0 +1,46 @@ +- Writes that produce :term:`DDL ` events cannot + occur on the source cluster during the migration. The following events cannot + occur: + + - ``collMod`` + - ``create`` + - ``createIndexes`` + - ``drop`` + - ``dropDatabase`` + - ``dropIndexes`` + - ``refineCollectionShardKey`` + - ``rename`` + - ``reshardCollection`` + - ``shardCollection`` + + This includes operations that may create new collections such as + :dbcommand:`mapReduce`, :pipeline:`$out`, and :pipeline:`$merge`. This also + includes collections created implicitly from inserts. Only writes that produce + CRUD events can occur during the migration. + + .. note:: + + Writes that produce DDL events on source collections outside of the + :ref:`namespace filter ` are allowed. + +- ``geoHaystack`` indexes are not supported. + +- :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 enable the ``createSupportingIndexes`` :ref:`sharding parameter + `. Instead, create an index to support your shard key + on the source cluster. + +- If there are any indexes with inconsistent specs or that are missing + ``mongosync`` returns an error. To check for index inconsistencies, see + :ref:`manage-indexes-find-inconsistent-indexes`. + +- For source clusters running MongoDB 4.4, :ref:`SRV connection strings + ` are not supported. You must use a + :ref:`standard connection string + `. diff --git a/source/includes/fact-pre-6.0-migration.rst b/source/includes/fact-pre-6.0-migration.rst new file mode 100644 index 000000000..492862c99 --- /dev/null +++ b/source/includes/fact-pre-6.0-migration.rst @@ -0,0 +1,2 @@ +Starting in version 1.10.0, ``mongosync`` supports migrations from pre-6.0 +source clusters. diff --git a/source/includes/fact-verifier-limitations.rst b/source/includes/fact-verifier-limitations.rst index 646e36a38..8d44186ba 100644 --- a/source/includes/fact-verifier-limitations.rst +++ b/source/includes/fact-verifier-limitations.rst @@ -28,3 +28,13 @@ Unsupported Verification Checks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/fact-verifier-unsupported + +.. note:: + + Starting in version 1.10, the verifier checks for data inconsistencies from + a :ref:`DDL event ` that occurred on the + pre-6.0 source cluster during migration. This is because pre-6.0 migrations + do not support DDL events. + + To learn more, see :ref:`Pre-6.0 Migration Limitations + `. diff --git a/source/includes/fact-version-compatibility.rst b/source/includes/fact-version-compatibility.rst new file mode 100644 index 000000000..eeed144f5 --- /dev/null +++ b/source/includes/fact-version-compatibility.rst @@ -0,0 +1,2 @@ +For information on minimum supported versions, see +:ref:`c2c-server-version-compatibility`. diff --git a/source/includes/table-pre-6.0-compatibility.rst b/source/includes/table-pre-6.0-compatibility.rst new file mode 100644 index 000000000..2fd3ca213 --- /dev/null +++ b/source/includes/table-pre-6.0-compatibility.rst @@ -0,0 +1,24 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :widths: 40 30 30 + + * - + - **6.0 Destination** + - **7.0 Destination** + + * - **4.4 Source** + - √ + - + + * - **5.0 Source** + - √ + - √ + + * - **6.0 Source** + - √ + - √ + + * - **7.0 Source** + - + - √ diff --git a/source/reference/api/reverse.txt b/source/reference/api/reverse.txt index 0e52e8b4a..69fd74026 100644 --- a/source/reference/api/reverse.txt +++ b/source/reference/api/reverse.txt @@ -170,5 +170,7 @@ Endpoint Protection Limitations ~~~~~~~~~~~ -The ``reverse`` endpoint does not support :ref:`filtered sync -`. +The ``reverse`` endpoint does not support: + +- :ref:`filtered sync `. +- migrations from :ref:`pre-6.0 source clusters `. diff --git a/source/reference/api/start.txt b/source/reference/api/start.txt index b28e2678c..b4c358c32 100644 --- a/source/reference/api/start.txt +++ b/source/reference/api/start.txt @@ -121,6 +121,9 @@ Request Body Parameters original source cluster blocks writes and the destination cluster accepts writes. + :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, for example after running migration tests, run the following @@ -167,6 +170,14 @@ 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``. + For more information, see the :ref:`reverse ` endpoint. Default value is ``false``. diff --git a/source/reference/limitations.txt b/source/reference/limitations.txt index 80403972c..55784bfca 100644 --- a/source/reference/limitations.txt +++ b/source/reference/limitations.txt @@ -117,7 +117,7 @@ Sharded Clusters - Shards cannot be added or removed while syncing. - ``mongosync`` only syncs indexes that exist on all shards. - ``mongosync`` only syncs indexes that have consistent index - specifications on all shards. + specifications on all shards. .. note:: @@ -200,3 +200,15 @@ cluster. .. include:: /includes/fact-verifier-limitations +.. _c2c-older-version-limitations: + +Pre-6.0 Migrations +------------------ + +Starting in 1.10, ``mongosync`` supports migrations from source clusters running +MongoDB server versions older than 6.0. For information on supported migration +paths, see :ref:`c2c-server-version-compatibility`. + +The following limitations apply to pre-6.0 migrations: + +.. include:: /includes/fact-older-version-limitations.rst diff --git a/source/reference/permissions.txt b/source/reference/permissions.txt index 59727db00..0e0a35117 100644 --- a/source/reference/permissions.txt +++ b/source/reference/permissions.txt @@ -28,3 +28,12 @@ The Atlas permissions are: .. include:: /includes/table-permissions-atlas.rst +.. _c2c-older-version-permissions: + +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. diff --git a/source/reference/supported-server-version.txt b/source/reference/supported-server-version.txt index 6d8b5aa9b..6aaf8b850 100644 --- a/source/reference/supported-server-version.txt +++ b/source/reference/supported-server-version.txt @@ -17,42 +17,63 @@ version limitations and requirements: - .. include:: /includes/fact-partial-8.0-support.rst -- .. include:: /includes/fact-minimum-server-version-support.rst +- Your source cluster must run one of the following major supported versions: + + - 4.4 (*New in version 1.10.0*) + - 5.0 (*New in version 1.10.0*) + - 6.0 + - 7.0 - ``mongosync`` doesn't support MongoDB rapid releases, such as 6.1 or 6.2. -- .. include:: /includes/fact-minimum-fcv.rst +The following table lists the minimum MongoDB server version requirements for +clusters: -Synchronize Data Between Clusters Running Older MongoDB Server Versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. list-table:: + :header-rows: 1 + :class: compatibility + + * - Major Version + - Patch Version + - Minimum Feature Compatibility Version + + * - 4.4 + - 4.4.23 + - 4.4 + + * - 5.0 + - 5.0.29 + - 5.0 -.. include:: /includes/fact-minimum-versions.rst + * - 6.0 + - 6.0.16 + - 6.0 + * - 7.0 + - 7.0.9 + - 6.0 + +.. _c2c-sync-different-versions: Synchronize Data Between Clusters with Different MongoDB Server Major Versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------------------------------ .. include:: /includes/cross-version-sync.rst -``mongosync`` supports syncs between the following source and -destination MongoDB server versions. +.. include:: /includes/fact-pre-6.0-migration.rst -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 40 30 30 +.. important:: + + ``mongosync`` does not support migrations to pre-6.0 destination clusters. - * - - - **6.0** Destination - - **7.0** Destination +``mongosync`` supports syncs between the following source and +destination MongoDB server versions: - * - **6.0** Source - - √ - - √ +.. include:: /includes/table-pre-6.0-compatibility.rst - * - **7.0** Source - - - - √ +.. seealso:: + + :ref:`Pre-6.0 Migration Limitations ` .. _c2c-server-8.0-to-8.0: diff --git a/source/reference/verification/embedded.txt b/source/reference/verification/embedded.txt index 9e7e877da..bf743847d 100644 --- a/source/reference/verification/embedded.txt +++ b/source/reference/verification/embedded.txt @@ -22,9 +22,15 @@ Verify with Embedded Verifier of checks on the destination cluster to verify the sync of supported collections. -.. important:: - - .. include:: /includes/fact-verifier-unsupported +.. note:: + + ``mongosync`` reads using :readmode:`primary` read preference, so it + preserves document field order from the source cluster's primary node. The + embedded verifier also checks documents based on the source cluster’s primary + node, but at a different time from when ``mongosync`` reads them. Because of + this, in rare cases, discrepancies in document field order between the source + cluster’s nodes can cause the embedded verifier to fail the migration, even + if ``mongosync`` copied the documents correctly. .. versionadded:: 1.9 diff --git a/source/release-notes/1.10.txt b/source/release-notes/1.10.txt index 084000f82..1494b40c7 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -19,10 +19,32 @@ Release Notes for mongosync 1.10 This page describes changes and new features introduced in {+c2c-full-product-name+} 1.10. -1.10.0 Release --------------- +.. _c2c-older-version-support: + +Older Version Support +--------------------- + +.. include:: /includes/fact-pre-6.0-migration.rst + +``mongosync`` now supports syncs between the following source and +destination MongoDB server versions: + +.. include:: /includes/table-pre-6.0-compatibility.rst + +To learn more, see: + +- :ref:`Pre-6.0 Migration Limitations `. +- :ref:`Pre-6.0 Migration Permissions `. +- :ref:`c2c-sync-different-versions`. Upgrades to Embedded Verifier -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- + +.. include:: /includes/verify-reversible-migrations.rst + +Minimum Supported Version +------------------------- + +.. include:: /includes/fact-version-compatibility.rst -- .. include:: /includes/verify-reversible-migrations.rst +.. include:: /includes/migration-upgrade-recommendation.rst diff --git a/source/reverse-sync.txt b/source/reverse-sync.txt index bf4a3d3c6..762f51184 100644 --- a/source/reverse-sync.txt +++ b/source/reverse-sync.txt @@ -35,6 +35,10 @@ following parameters: For more information on limitations and requirements of reversing sync, see :ref:`c2c-api-reverse`. +.. important:: + + If you are migrating from a pre-6.0 source cluster, you cannot reverse sync. + Steps -----