DOCSP-46854-migrate-pqs-tutorial

snooty.toml

@@ -23,7 +23,8 @@ toc_landing_pages = ["/quickstart",
                      "/faq",
                      "/reference/collection-level-filtering",
                      "/reference/verification",
-                     "/reference/mongosync"
+                     "/reference/mongosync",
+                     "/reference/cutover-process"
                     ]
 
 [constants]

source/reference/c2c-migrate-pqs.txt

@@ -0,0 +1,49 @@
+.. _c2c-migrate-pqs:
+
+================================= 
+Migrate Persistent Query Settings
+=================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+If your source cluster uses Persistent Query Settings (PQS), you must manually
+migrate those settings to your destination cluster to finalize sync. 
+
+``mongosync`` checks for PQS during initialization and the :ref:`cutover process
+<c2c-cutover-process>`. If ``mongosync`` finds PQS on the source cluster during
+cutover, {+c2c-product-name+} shows a warning. Use the following procedure to
+address the warning and migrate your PQS to your destination cluster.
+
+Steps 
+-----
+
+.. procedure::
+   :style: normal
+
+   .. step:: Export your Persistent Query Settings.
+
+      Run the following code block to output your query settings into an array:
+
+      .. code-block:: shell
+
+         mongosh --eval
+         'console.log(db.aggregate([{$querySettings:{}}]).toArray())'
+
+   .. step:: Import your PQS to the destination cluster.
+
+      For each query setting that you want to migrate, use
+      :dbcommand:`setQuerySettings` to apply that setting to your destination
+      cluster. 
+
+      If the query setting includes a ``representativeQuery`` field value, use
+      that field value as the ``setQuerySettings`` value. 
+
+      Otherwise, use the ``queryShapeHash`` field value from the
+      ``querySettings`` array as the ``setQuerySettings`` value. 
+

source/reference/cutover-process.txt

@@ -128,6 +128,12 @@ Steps
          to ensure that the ``mongosync`` state is ``COMMITTING`` or
          ``COMMITTED``.
 
+      Once you complete this step, ``mongosync`` blocks writes on the source
+      cluster.
+
+      If your source cluster contains Persistant Query Settings (PQS), you must
+      :ref:`manually migrate PQS <c2c-migrate-pqs>` to your destination cluster.
+
       If you previously set ``enableUserWriteBlocking``
       to ``true``, ``mongosync`` blocks writes on the source cluster
       once you complete this step.
@@ -231,3 +237,8 @@ Learn More
 - :ref:`c2c-api-progress`
 - :ref:`c2c-states`
 
+.. toctree::
+   :titlesonly: 
+
+   Migrate Persistent Query Settings </reference/c2c-migrate-pqs>
+