From aa418bfcb6304941682344b0618b9fee02fc4e65 Mon Sep 17 00:00:00 2001 From: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:17:54 -0800 Subject: [PATCH 1/8] DOCSP-45860-older-version-limitations (#522) * DOCSP-45860-older-version-limitations * * * JA feedback * * * * * * * AV feedback * MvK feedback --- .../fact-older-version-limitations.rst | 46 +++++++++++++++++++ source/reference/limitations.txt | 12 ++++- 2 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 source/includes/fact-older-version-limitations.rst 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/reference/limitations.txt b/source/reference/limitations.txt index 51004bded..f44222f54 100644 --- a/source/reference/limitations.txt +++ b/source/reference/limitations.txt @@ -115,7 +115,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:: @@ -198,3 +198,13 @@ cluster. .. include:: /includes/fact-verifier-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 From 809958272fc41440e411575bbe5156f8401a4b2c Mon Sep 17 00:00:00 2001 From: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:27:11 -0800 Subject: [PATCH 2/8] DOCSP-45859 Version Compatibility (#518) * DOCSP-45859 Version Compatibility * * * * * * * AV feedback * swap list order * MvK feedback --- source/includes/cross-version-sync.rst | 6 -- source/includes/fact-minimum-fcv.rst | 2 - .../includes/fact-version-compatibility.rst | 2 + source/reference/mongosync.txt | 10 --- source/reference/supported-server-version.txt | 61 +++++++++++++++---- source/release-notes/1.10.txt | 9 ++- 6 files changed, 60 insertions(+), 30 deletions(-) delete mode 100644 source/includes/fact-minimum-fcv.rst create mode 100644 source/includes/fact-version-compatibility.rst 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-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/reference/mongosync.txt b/source/reference/mongosync.txt index 9bace82c5..43ecdf87b 100644 --- a/source/reference/mongosync.txt +++ b/source/reference/mongosync.txt @@ -38,16 +38,6 @@ Compatibility ------------- - .. include:: /includes/fact-no-8.0-support.rst - -- .. include:: /includes/fact-minimum-server-version-support.rst - - You can migrate data on clusters (source) with versions of MongoDB - lower than 6.0 to an Atlas cluster (destination). Migration from clusters with - lower version requires additional preparation and configuration in - the clusters with the lower version. `Contact - `__ your account team to inquire about - Professional Services. - - ``mongosync`` supports replica sets and sharded clusters. - Standalone MongoDB instances are not supported. :ref:`Convert the standalone instance ` to a diff --git a/source/reference/supported-server-version.txt b/source/reference/supported-server-version.txt index 1ebb36a8b..c0817a596 100644 --- a/source/reference/supported-server-version.txt +++ b/source/reference/supported-server-version.txt @@ -17,23 +17,54 @@ version limitations and requirements: - .. include:: /includes/fact-no-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 -.. include:: /includes/fact-minimum-versions.rst + * - 5.0 + - 5.0.29 + - 5.0 + * - 6.0 + - 6.0.16 + - 6.0 + + * - 7.0 + - 7.0.9 + - 6.0 Synchronize Data Between Clusters with Different MongoDB Server Major Versions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------------------------------ .. include:: /includes/cross-version-sync.rst +Starting in version 1.10.0, ``mongosync`` supports migrations from pre-6.0 +source clusters. + +.. important:: + + ``mongosync`` does not support migrations to pre-6.0 destination clusters. + ``mongosync`` supports syncs between the following source and destination MongoDB server versions. @@ -42,15 +73,23 @@ destination MongoDB server versions. :stub-columns: 1 :widths: 40 30 30 - * - - - **6.0** Destination - - **7.0** Destination + * - + - **6.0 Destination** + - **7.0 Destination** + + * - **4.4 Source** + - √ + - + + * - **5.0 Source** + - √ + - √ - * - **6.0** Source + * - **6.0 Source** - √ - √ - * - **7.0** Source + * - **7.0 Source** - - √ diff --git a/source/release-notes/1.10.txt b/source/release-notes/1.10.txt index 58842d615..667f7a33d 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -17,4 +17,11 @@ Release Notes for mongosync 1.10 .. _1.10.0-c2c-release-notes: This page describes changes and new features introduced in -{+c2c-full-product-name+} 1.10 and the {+c2c-full-beta-program+}. \ No newline at end of file +{+c2c-full-product-name+} 1.10. + +Minimum Supported Version +------------------------- + +.. include:: /includes/fact-version-compatibility.rst + +.. include:: /includes/migration-upgrade-recommendation.rst From 3b3657adf3d430c76cdada686c8dc6a2bd8c3116 Mon Sep 17 00:00:00 2001 From: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Date: Mon, 13 Jan 2025 13:34:58 -0500 Subject: [PATCH 3/8] DOCSP-45861 Older Version Support Task Page (#533) * DOCSP-45861 Older Version Support Task Page * add prerequisites & limitations * * * * * procedures * * * rn * * * remove extra step * nit * AV feedback * remove task page * * * * * * --- source/includes/fact-pre-6.0-migration.rst | 2 ++ .../includes/table-pre-6.0-compatibility.rst | 24 +++++++++++++ source/reference/limitations.txt | 2 ++ source/reference/supported-server-version.txt | 34 +++++-------------- source/release-notes/1.10.txt | 15 ++++++++ 5 files changed, 51 insertions(+), 26 deletions(-) create mode 100644 source/includes/fact-pre-6.0-migration.rst create mode 100644 source/includes/table-pre-6.0-compatibility.rst 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/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/limitations.txt b/source/reference/limitations.txt index f44222f54..476e0c2ac 100644 --- a/source/reference/limitations.txt +++ b/source/reference/limitations.txt @@ -198,6 +198,8 @@ cluster. .. include:: /includes/fact-verifier-limitations +.. _c2c-older-version-limitations: + Pre-6.0 Migrations ------------------ diff --git a/source/reference/supported-server-version.txt b/source/reference/supported-server-version.txt index c0817a596..d7cb687d6 100644 --- a/source/reference/supported-server-version.txt +++ b/source/reference/supported-server-version.txt @@ -53,45 +53,27 @@ clusters: - 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 -Starting in version 1.10.0, ``mongosync`` supports migrations from pre-6.0 -source clusters. +.. include:: /includes/fact-pre-6.0-migration.rst .. important:: ``mongosync`` does not support migrations to pre-6.0 destination clusters. ``mongosync`` supports syncs between the following source and -destination MongoDB server versions. - -.. list-table:: - :header-rows: 1 - :stub-columns: 1 - :widths: 40 30 30 - - * - - - **6.0 Destination** - - **7.0 Destination** +destination MongoDB server versions: - * - **4.4 Source** - - √ - - +.. include:: /includes/table-pre-6.0-compatibility.rst - * - **5.0 Source** - - √ - - √ - - * - **6.0 Source** - - √ - - √ - - * - **7.0 Source** - - - - √ +.. seealso:: + + :ref:`c2c-older-version-limitations`. .. _c2c-server-pre-8.0-to-8.0: diff --git a/source/release-notes/1.10.txt b/source/release-notes/1.10.txt index 667f7a33d..5070f33d1 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -19,6 +19,21 @@ Release Notes for mongosync 1.10 This page describes changes and new features introduced in {+c2c-full-product-name+} 1.10. +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:`c2c-sync-different-versions`. + Minimum Supported Version ------------------------- From f56ae2fc38d2bf7d821cef6e180af3df32ea068d Mon Sep 17 00:00:00 2001 From: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Date: Mon, 27 Jan 2025 15:23:34 -0500 Subject: [PATCH 4/8] DOCSP-45862 User permissions older version (#552) * DOCSP-45862-user-permissions * * * JD feedback * AV feedback --- source/reference/api/reverse.txt | 6 ++++-- source/reference/api/start.txt | 6 ++++++ source/reference/permissions.txt | 9 +++++++++ source/release-notes/1.10.txt | 3 +++ source/reverse-sync.txt | 4 ++++ 5 files changed, 26 insertions(+), 2 deletions(-) diff --git a/source/reference/api/reverse.txt b/source/reference/api/reverse.txt index e2923b2d3..14e57e897 100644 --- a/source/reference/api/reverse.txt +++ b/source/reference/api/reverse.txt @@ -174,5 +174,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 1a2d785b2..6e7f321c6 100644 --- a/source/reference/api/start.txt +++ b/source/reference/api/start.txt @@ -132,6 +132,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 @@ -194,6 +197,9 @@ Request Body Parameters 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/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/release-notes/1.10.txt b/source/release-notes/1.10.txt index 5070f33d1..068b04349 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -19,6 +19,8 @@ Release Notes for mongosync 1.10 This page describes changes and new features introduced in {+c2c-full-product-name+} 1.10. +.. _c2c-older-version-support: + Older Version Support --------------------- @@ -32,6 +34,7 @@ destination MongoDB server versions: To learn more, see: - :ref:`Pre-6.0 Migration Limitations `. +- :ref:`Pre-6.0 Migration Permissions `. - :ref:`c2c-sync-different-versions`. Minimum Supported Version 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 ----- From 59070e0eb08aa8a7b938e47c83324b986de89650 Mon Sep 17 00:00:00 2001 From: Alison Huh <112565127+ajhuh-mdb@users.noreply.github.com> Date: Tue, 28 Jan 2025 11:11:43 -0500 Subject: [PATCH 5/8] DOCSP-45863-embedded-verifier-migrations (#557) * DOCSP-45863-embedded-verifier-migrations * * * * * AV feedback * wording * add ddl limitation * * * RS feedback --- source/includes/fact-verifier-limitations.rst | 10 ++++++++++ source/reference/verification/embedded.txt | 12 +++++++++--- 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/source/includes/fact-verifier-limitations.rst b/source/includes/fact-verifier-limitations.rst index 7b5bf6bf2..0bd40393a 100644 --- a/source/includes/fact-verifier-limitations.rst +++ b/source/includes/fact-verifier-limitations.rst @@ -37,6 +37,16 @@ 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 + `. + Unsupported Beta Features ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/verification/embedded.txt b/source/reference/verification/embedded.txt index fdeb1e20e..bd87fc62a 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 From ed9703e06d5a5f71543a5049886087820656864b Mon Sep 17 00:00:00 2001 From: Alison Huh Date: Tue, 28 Jan 2025 13:02:04 -0500 Subject: [PATCH 6/8] * --- source/release-notes/1.10.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/release-notes/1.10.txt b/source/release-notes/1.10.txt index 99e2f5117..8858bb98a 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -38,9 +38,9 @@ To learn more, see: - :ref:`c2c-sync-different-versions`. Upgrades to Embedded Verifier -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- -- .. include:: /includes/verify-reversible-migrations.rst +.. include:: /includes/verify-reversible-migrations.rst Minimum Supported Version ------------------------- From d49f6909dd25510eca22efc4fac0c2540965a802 Mon Sep 17 00:00:00 2001 From: Alison Huh Date: Tue, 28 Jan 2025 13:02:44 -0500 Subject: [PATCH 7/8] remove merge conflict artifact --- source/release-notes/1.10.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/release-notes/1.10.txt b/source/release-notes/1.10.txt index 8858bb98a..1494b40c7 100644 --- a/source/release-notes/1.10.txt +++ b/source/release-notes/1.10.txt @@ -48,5 +48,3 @@ Minimum Supported Version .. include:: /includes/fact-version-compatibility.rst .. include:: /includes/migration-upgrade-recommendation.rst - -{+c2c-full-product-name+} 1.10. From 9851a55eb46505d692f2e6ac6a20c16a0b8c2a00 Mon Sep 17 00:00:00 2001 From: Alison Huh Date: Tue, 28 Jan 2025 13:06:14 -0500 Subject: [PATCH 8/8] fix link title --- source/reference/supported-server-version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/reference/supported-server-version.txt b/source/reference/supported-server-version.txt index 04f490cae..6aaf8b850 100644 --- a/source/reference/supported-server-version.txt +++ b/source/reference/supported-server-version.txt @@ -73,7 +73,7 @@ destination MongoDB server versions: .. seealso:: - :ref:`c2c-older-version-limitations`. + :ref:`Pre-6.0 Migration Limitations ` .. _c2c-server-8.0-to-8.0: