DOCS-8329 3.4 downgrade

Author: kay-kim

source/includes/3.4-downgrade-path.rst

@@ -0,0 +1,2 @@
+Once upgraded to 3.4, you cannot downgrade to a 3.2.7 or earlier
+version. You can only downgrade to a 3.2.8 or later version.

source/includes/3.4-upgrade-enable-features.rst

@@ -2,10 +2,16 @@ At this point, you can run the |newversion| binaries without the
 |newversion| :ref:`features that are incompatible
 <3.4-compatibility-enabled>` with |oldversion|.
 
-To complete the upgrade and enable these |newversion| features, you must set the 
-feature compatibility version to |newversion|.
+To enable these |newversion| features, set the feature compatibility
+version to |newversion|.
 
-.. important::
-   Enabling these backwards-incompatible features can complicate the
-   downgrade process. Only enable these features when you are confident
-   that the likelihood of downgrade is minimal.
+.. warning::
+
+   Enabling these backwards-incompatible features can :ref:`complicate
+   the downgrade process <3.4-downgrade-features-prereq>`. For details,
+   see :ref:`3.4-downgrade-features-prereq`.
+
+   It is recommended that after upgrading, you allow your deployment to
+   run without enabling these features for a burn-in period to ensure
+   the likelihood of downgrade is minimal. When you are confident that
+   the likelihood of downgrade is minimal, enable these features.

source/includes/extracts-3.4-downgrade.yaml

@@ -0,0 +1,113 @@
+ref: 3.4-downgrade-feature-compatibility
+content: |
+
+   Downgrade the ``featureCompatibilityVersion`` to ``"3.2"``.
+
+   .. code-block:: javascript
+
+      db.adminCommand({setFeatureCompatibilityVersion: "3.2"})
+
+   This command must perform writes to an internal system collection.
+   If for any reason the command does not complete successfully, you
+   can safely retry the command on the |target| as the operation is
+   idempotent.
+---
+ref: 3.4-downgrade-views
+content: |
+
+   To find views, you can run the following in the :program:`mongo` shell:
+
+   .. code-block:: javascript
+
+      db.adminCommand("listDatabases").databases.forEach(function(d){ 
+         let mdb = db.getSiblingDB(d.name); 
+         mdb.getCollectionInfos({type: "view"}).forEach(function(c){
+            print(mdb[c.name]); 
+         });
+      });
+
+   In each database that contains views, drop the ``system.views``
+   collection to drop all views in that database.
+    
+---
+ref: 3.4-downgrade-collation-collections
+content: |
+
+   To find collections with collation specifications, you can run the
+   following in the :program:`mongo` shell:
+
+   .. code-block:: javascript
+
+      db.adminCommand("listDatabases").databases.forEach(function(d){
+         let mdb = db.getSiblingDB(d.name);
+         mdb.getCollectionInfos( { "options.collation": { $exists: true } } ).forEach(function(c){
+            print(mdb[c.name]); 
+         });
+      });
+
+   You can migrate the content of the collection to a new collection
+   without the collation specification (one way is via the
+   aggregation pipeline stage :pipeline:`$out`).
+---
+ref: 3.4-downgrade-collation-indexes
+content: |
+   
+   To find indexes with collation specification, you can run the
+   following in the :program:`mongo` shell:
+
+   .. code-block:: javascript
+
+      db.adminCommand("listDatabases").databases.forEach(function(d){ 
+         let mdb = db.getSiblingDB(d.name);
+         mdb.getCollectionInfos().forEach(function(c){
+            let currentCollection = mdb.getCollection(c.name);
+            currentCollection.getIndexes().forEach(function(i){
+               if (i.collation){
+                  printjson(i);
+               }
+            });
+         });
+      });
+
+   Drop the indexes with a collation specification. After the downgrade,
+   recreate the dropped indexes.
+---
+ref: 3.4-downgrade-v2-indexes
+content: |
+
+   To find indexes with ``v: 2``, you can run the following in the
+   :program:`mongo` shell:
+
+   .. code-block:: javascript
+
+      db.adminCommand("listDatabases").databases.forEach(function(d){ 
+         let mdb = db.getSiblingDB(d.name);
+         mdb.getCollectionInfos().forEach(function(c){
+            let currentCollection = mdb.getCollection(c.name);
+            currentCollection.getIndexes().forEach(function(i){
+               if (i.v === 2){
+                  printjson(i);
+               }
+            });
+         });
+      });
+         
+---
+ref: 3.4-downgrade-decimal
+content: |
+
+   Convert any data of :ref:`decimal <3.4-decimal>` type. In versions
+   of MongoDB earlier than 3.4, operations against documents that
+   contain :ref:`decimal <3.4-decimal>` type may fail. For some
+   possible conversion options, see
+   :doc:`/tutorial/model-monetary-data`.
+
+   To detect the presence of decimal, you can run
+   :method:`db.collection.validate(true) <db.collection.validate()>`
+   against the collections which may contain decimal data.
+
+   :method:`db.collection.validate(true) <db.collection.validate()>`
+   reports on decimal data only when ``featureCompatibilityVersion`` is
+   ``"3.2"``.
+
+...

source/includes/steps-3.4-downgrade-mongod.yaml

@@ -0,0 +1,19 @@
+title: "Download the latest 3.2 binaries."
+level: 4
+ref: 3.4-downgrade-binaries-mongod
+content: |
+  
+  Using either a package manager or a manual download, get the latest
+  release in the 3.2 series. If using a package manager, add a new
+  repository for the 3.2 binaries, then perform the actual downgrade
+  process.
+
+  .. include:: /includes/3.4-downgrade-path.rst
+---
+title: "Restart with the latest 3.2 ``mongod`` instance."
+level: 4
+ref: 3.4-downgrade-restart-instance
+content: |
+  Shut down your :program:`mongod` instance. Replace the existing
+  binary with the downloaded :program:`mongod` binary and restart.
+...

source/includes/steps-3.4-downgrade-replica-set.yaml

@@ -0,0 +1,52 @@
+title: "Download the latest 3.2 binaries."
+level: 4
+ref: 3.4-downgrade-binaries-rs
+content: |
+  Using either a package manager or a manual download, get the latest
+  release in the 3.2 series. If using a package manager, add a new
+  repository for the 3.2 binaries, then perform the actual downgrade
+  process.
+
+  .. include:: /includes/3.4-downgrade-path.rst
+---
+title: "Downgrade secondary members of the replica set."
+level: 4
+ref: downgrade-secondaries
+content: |
+
+  Downgrade each :term:`secondary` member of the replica set, one at a
+  time:
+
+  a. Shut down the :program:`mongod`. See :ref:`terminate-mongod-processes` for instructions on safely terminating :program:`mongod` processes.
+
+  #. Replace the 3.4 binary with the 3.2 binary and restart.
+
+  #. Wait for the member to recover to ``SECONDARY`` state
+     before downgrading the next secondary. To check the member's state,
+     use the :method:`rs.status()` method in the :program:`mongo` shell.
+
+---
+title: Step down the primary.
+level: 4
+ref: step-down-primary
+pre: |
+  Use :method:`rs.stepDown()` in the :program:`mongo` shell to
+  step down the :term:`primary` and force the normal :ref:`failover
+  <replica-set-failover>` procedure.
+action:
+  language: javascript
+  code:
+    rs.stepDown()
+post: |
+  :method:`rs.stepDown()` expedites the failover procedure and is
+  preferable to shutting down the primary directly.
+---
+title: "Replace and restart former primary ``mongod``."
+level: 4
+ref: downgrade-primary
+content: |
+  When :method:`rs.status()` shows that the primary has stepped down
+  and another member has assumed ``PRIMARY`` state, shut down the
+  previous primary and replace the :program:`mongod` binary with
+  the 3.2 binary and start the new instance.
+...