diff --git a/snooty.toml b/snooty.toml index e73491c02..313d38d34 100644 --- a/snooty.toml +++ b/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] diff --git a/source/reference/c2c-migrate-pqs.txt b/source/reference/c2c-migrate-pqs.txt new file mode 100644 index 000000000..3ad288f73 --- /dev/null +++ b/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 +`. 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. + diff --git a/source/reference/cutover-process.txt b/source/reference/cutover-process.txt index 1b0f52aed..6f033e437 100644 --- a/source/reference/cutover-process.txt +++ b/source/reference/cutover-process.txt @@ -120,7 +120,15 @@ 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, ``mongosync`` blocks writes on the source + cluster. + + If your source cluster contains Persistant Query Settings (PQS), you must + :ref:`manually 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. .. step:: Wait until you can perform writes on the destination cluster. @@ -221,3 +229,8 @@ Learn More - :ref:`c2c-api-progress` - :ref:`c2c-states` +.. toctree:: + :titlesonly: + + Migrate Persistent Query Settings +