Skip to content

Commit 2ee9346

Browse files
kennethdyerkennethdyer
authored
DOCS-13029 Backport to v4.2 (#1134)
1 parent 9b819a3 commit 2ee9346

10 files changed

+929
-0
lines changed

‎source/core/replica-set-arbiter.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,13 @@ Replica Set Protocol Version and Arbiter
6969

7070
.. include:: /includes/extracts/arbiters-and-pvs-with-reference.rst
7171

72+
For more information, see the :dbcommand:`setFeatureCompatibilityVersion` command.
73+
74+
Feature Compatibility Version
75+
-----------------------------
76+
77+
.. include:: /includes/arbiter-fcv.rst
78+
7279
.. _rollbacks-multi-arbiters:
7380

7481
Concerns with Multiple Arbiters

‎source/includes/arbiter-fcv-version.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
For example, an arbiter in a MongoDB |newversion| cluster, has an FCV
3+
value of |oldversion|.

‎source/includes/arbiter-fcv.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
Arbiters do not replicate the :data:`admin.system.version` collection.
3+
Because of this, arbiters always have a Feature Compatibility Version equal
4+
to the downgrade version of the binary, regardless of the FCV value of the
5+
replica set.

‎source/reference/command/setFeatureCompatibilityVersion.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,14 @@ This command must perform writes to an internal system collection. If
141141
for any reason the command does not complete successfully, you can
142142
safely retry the command as the operation is idempotent.
143143

144+
Feature Compatibility in Arbiters
145+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146+
147+
.. include:: /includes/arbiter-fcv.rst
148+
149+
For example, an arbiter in a MongoDB 5.0 cluster, has an FCV
150+
value of 4.4.
151+
144152
Examples
145153
--------
146154

‎source/release-notes/4.2-downgrade-replica-set.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,13 @@ To downgrade the ``featureCompatibilityVersion`` of your replica set:
9090
If any member returns a ``featureCompatibilityVersion`` of ``"4.2"``,
9191
wait for the member to reflect version ``"4.0"`` before proceeding.
9292

93+
.. note::
94+
95+
.. include:: /includes/arbiter-fcv.rst
96+
97+
.. include:: /includes/arbiter-fcv-version.rst
98+
99+
93100
For more information on the returned ``featureCompatibilityVersion``
94101
value, see :ref:`view-fcv`.
95102

‎source/release-notes/4.2-downgrade-sharded-cluster.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,13 @@ cluster:
8686
If any member returns a ``featureCompatibilityVersion`` of ``"4.2"``,
8787
wait for the member to reflect version ``"4.0"`` before proceeding.
8888

89+
.. note::
90+
91+
.. include:: /includes/arbiter-fcv.rst
92+
93+
.. include:: /includes/arbiter-fcv-version.rst
94+
95+
8996
For more information on the returned ``featureCompatibilityVersion``
9097
value, see :ref:`view-fcv`.
9198

‎source/release-notes/4.4-downgrade-replica-set.txt

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
==================================================
2+
Downgrade |newversion| Replica Set to |oldversion|
3+
==================================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
14+
15+
.. include:: /includes/4.4-upgrade-replacements.rst
16+
17+
Before you attempt any downgrade, familiarize yourself with the content
18+
of this document.
19+
20+
.. |downgrading| replace:: downgrading
21+
22+
Downgrade Path
23+
--------------
24+
25+
.. include:: /includes/downgrade-path.rst
26+
27+
.. include:: /includes/extracts/4.4-changes-downgrade-floor.rst
28+
29+
Create Backup
30+
-------------
31+
32+
*Optional but Recommended.* Create a backup of your database.
33+
34+
Access Control
35+
--------------
36+
37+
If your replica set has access control enabled, your downgrade user
38+
privileges must include privileges to list and manage indexes across
39+
databases. A user with :authrole:`root` role has the required
40+
privileges.
41+
42+
Prerequisites
43+
-------------
44+
45+
To downgrade from 4.2 to 4.0, you must remove incompatible features
46+
that are persisted and/or update incompatible configuration settings.
47+
48+
.. |target| replace:: primary
49+
50+
1. Namespace Length
51+
~~~~~~~~~~~~~~~~~~~
52+
53+
Starting in MongoDB 4.4:
54+
55+
.. include:: /includes/fact-collection-namespace-limit.rst
56+
57+
Before downgrading, resolve any collections or views with namespaces
58+
that exceed the 120-byte :limit:`Namespace Length` limit for Feature
59+
Compatibility Version (fCV) 4.2.
60+
61+
To determine if you have any collections or views with namespaces
62+
that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell
63+
to the |target| and run:
64+
65+
.. code-block:: javascript
66+
67+
db.adminCommand("listDatabases").databases.forEach(function(d){
68+
let mdb = db.getSiblingDB(d.name);
69+
70+
mdb.getCollectionInfos( ).forEach(function(c){
71+
namespace = d.name + "." + c.name
72+
namespacelenBytes = encodeURIComponent(namespace).length
73+
74+
if (namespacelenBytes > 120) {
75+
print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace )
76+
}
77+
} )
78+
})
79+
80+
If any collection or view namespace exceeds 120 bytes, then :red:`prior` to
81+
downgrading the fCV:
82+
83+
- Rename the collection using the :dbcommand:`renameCollection` command.
84+
85+
- For views, use :method:`db.createView()` to recreate the view
86+
using a shorter name, then drop the original view.
87+
88+
89+
.. _4.4-downgrade-feature-compatibility-rs:
90+
91+
2. Downgrade Feature Compatibility Version (fCV)
92+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+
.. tip::
95+
96+
- Ensure that no initial sync is in progress. Running
97+
:dbcommand:`setFeatureCompatibilityVersion` command while an
98+
initial sync is in progress will cause the initial sync to restart.
99+
100+
- Ensure that no replica set member is in :replstate:`ROLLBACK` or
101+
:replstate:`RECOVERING` state.
102+
103+
- Downgrading to
104+
:ref:`featureCompatibilityVersion (fCV) : "4.2" <set-fcv>`
105+
implicitly performs a :dbcommand:`replSetReconfig` to remove the
106+
:rsconf:`term` field from the configuration document and blocks
107+
until the new configuration propagates to a majority of replica set
108+
members.
109+
110+
To downgrade the ``featureCompatibilityVersion`` of your replica set:
111+
112+
#. Connect a :binary:`~bin.mongo` shell to the |target|.
113+
114+
#. .. include:: /includes/4.4-downgrade-fcv.rst
115+
116+
#. To ensure that all members of the replica set reflect the updated
117+
``featureCompatibilityVersion``, connect to each replica set member and
118+
check the ``featureCompatibilityVersion``:
119+
120+
.. code-block:: javascript
121+
122+
db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } )
123+
124+
All members should return a result that includes:
125+
126+
.. code-block:: javascript
127+
128+
"featureCompatibilityVersion" : { "version" : "4.2" }
129+
130+
If any member returns a ``featureCompatibilityVersion`` of |newfcv|,
131+
wait for the member to reflect version |oldfcv| before proceeding.
132+
133+
For more information on the returned ``featureCompatibilityVersion``
134+
value, see :ref:`view-fcv`.
135+
136+
.. note::
137+
138+
.. include:: /includes/arbiter-fcv.rst
139+
140+
.. include:: /includes/arbiter-fcv-version.rst
141+
142+
143+
3. Remove FCV |newversion| Persisted Features
144+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
145+
146+
The following steps are necessary only if fCV has ever been set to
147+
|newfcv|.
148+
149+
Remove all persisted |newversion| |features| that are incompatible with
150+
|oldversion|. These include:
151+
152+
Compound Hashed Indexes
153+
Remove all :ref:`compound hashed indexes
154+
<index-type-compound-hashed>`.
155+
156+
Use :method:`db.collection.getIndexes()` to identify
157+
any compound hashed indexes in a collection and use
158+
:method:`db.collection.dropIndex()` to remove those indexes.
159+
160+
.. |binary| replace:: any replica set member
161+
162+
4. Remove |newversion| Features
163+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
164+
165+
Remove all persisted features that use |newversion| features. These
166+
include but are not limited to:
167+
168+
- If any view definitions that include |newversion| operators, such as
169+
:pipeline:`$unionWith` or :expression:`$function`. See also
170+
:ref:`4.4-rel-notes-new-agg-operators`.
171+
172+
- :method:`Unhide <db.collection.unhideIndex()>` or :method:`drop
173+
<db.collection.dropIndex()>` hidden indexes.
174+
175+
Procedure
176+
---------
177+
178+
.. warning::
179+
180+
Before proceeding with the downgrade procedure, ensure that all
181+
replica set members, including delayed replica set members, reflect
182+
the prerequisite changes. That is, check the
183+
``featureCompatibilityVersion`` and the removal of incompatible
184+
features for each node before downgrading.
185+
186+
.. include:: /includes/steps/4.4-downgrade-replica-set.rst
187+
188+

0 commit comments

Comments
 (0)