Skip to content

Commit 05034e1

Browse files
ksuarzksuarz
committed
DOCS-6949 wiredtiger upgrade procedures
Documents how to change your MongoDB deployment to use the WiredTiger storage engine for replica sets, sharded clusters, and config servers.
1 parent 8c21d38 commit 05034e1

11 files changed

+443
-26
lines changed

‎config/sphinx_local.yaml

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -12,37 +12,38 @@ theme:
1212
jira: 'DOCS'
1313
sitename: 'MongoDB Docs'
1414
nav_excluded:
15+
- /administration/production-checklist
1516
- /aggregation
17+
- /applications/geospatial-indexes
18+
- /contributors/getting-started
19+
- /core/authorization
20+
- /core/journaling
1621
- /core/map-reduce
17-
- /core/replica-set-members
1822
- /core/replica-set-architectures
1923
- /core/replica-set-high-availability
20-
- /applications/geospatial-indexes
24+
- /core/replica-set-members
2125
- /core/sharded-cluster-components
22-
- /security
23-
- /core/authentication
24-
- /core/authorization
26+
- /core/wiredtiger
2527
- /installation
26-
- /reference/security
27-
- /reference/indexes
28-
- /reference/replication
29-
- /reference/sharding
28+
- /products/bi-connector
3029
- /reference/command
30+
- /reference/indexes
3131
- /reference/method
32-
- /reference/operator/query
33-
- /reference/operator/update
3432
- /reference/operator/aggregation
33+
- /reference/operator/query
3534
- /reference/operator/query-modifier
35+
- /reference/operator/update
36+
- /reference/replication
37+
- /reference/security
38+
- /reference/sharding
3639
- /release-notes/2.4
3740
- /release-notes/2.6
3841
- /release-notes/2.8
3942
- /release-notes/3.0
4043
- /release-notes/3.2
44+
- /security
4145
- /storage
42-
- /administration/production-checklist
43-
- /contributors/getting-started
44-
- /core/journaling
45-
- /products/bi-connector
46+
- /tutorial/change-sharded-cluster-wiredtiger
4647
sidebars:
4748
'**':
4849
- 'pagenav.html'

‎source/core/wiredtiger.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,3 +143,5 @@ on journal compression, see :ref:`storage-wiredtiger-journal`.
143143
:titlesonly:
144144

145145
/tutorial/change-standalone-wiredtiger.txt
146+
/tutorial/change-replica-set-wiredtiger.txt
147+
/tutorial/change-sharded-cluster-wiredtiger.txt

‎source/includes/fact-config-server-storage-engine-mix.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
You may safely **continue** to use :ref:`MMAPv1 <storage-mmapv1>` for
2+
the :term:`config servers <config server>` even if the shards of the
3+
sharded cluster is using the WiredTiger storage engine. If you do choose
4+
to update the config servers to use WiredTiger, you must update **all
5+
three**.

‎source/includes/fact-wiredtiger-minimum-version.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
You must be using MongoDB version 3.0 or greater in order to use the
2+
WiredTiger storage engine. If upgrading from an earlier version of
3+
MongoDB, see the guides on :doc:`Upgrading to MongoDB 3.0
4+
</release-notes/3.0-upgrade>` or :doc:`Upgrading to MongoDB 3.2
5+
</release-notes/3.2-upgrade>` before proceeding with changing your
6+
storage engine.

‎source/includes/steps-change-config-server-wiredtiger.yaml

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
title: "Disable the balancer."
2+
ref: change-wt-config-svr-disable-balancer
3+
content: |
4+
Turn off the :ref:`balancer <sharding-balancing-internals>` in the
5+
sharded cluster, as described in
6+
:ref:`sharding-balancing-disable-temporarily`.
7+
action:
8+
language: sh
9+
code: |
10+
sh.disableBalancer()
11+
---
12+
title: "Shut down the **third** config server."
13+
ref: change-wt-config-svr-shutdown-3
14+
content: |
15+
Use the :program:`mongo` shell to shut down the third config server.
16+
17+
The third config server is the last one listed in the
18+
:program:`mongos` :setting:`~sharding.configDB` setting.
19+
action: |
20+
language: sh
21+
code: |
22+
db.shutdownServer()
23+
---
24+
title: "Export the data of the **second** config server with ``mongodump``."
25+
ref: change-wt-config-svr-export-2
26+
pre: |
27+
The second config server is the second server listed in the
28+
:program:`mongos` setting :setting:`~sharding.configDB`.
29+
action:
30+
language: sh
31+
code: |
32+
mongodump --out <exportDataDestination>
33+
post: |
34+
Specify additional options as appropriate, such as username and
35+
password if running with authorization enabled. See
36+
:program:`mongodump` for available options.
37+
---
38+
title: "For the **second** config server, create a data directory for the new ``mongod`` running with WiredTiger."
39+
ref: change-wt-config-svr-create-dir-2
40+
content: |
41+
Create a data directory for the new :program:`mongod` instance that
42+
will run with the WiredTiger storage engine. ``mongod`` must have read
43+
and write permissions for this directory.
44+
45+
``mongod`` with WiredTiger will not start with data files created with
46+
a different storage engine.
47+
---
48+
title: "Start the **second** config server ``mongod`` with WiredTiger."
49+
ref: change-wt-config-svr-restart-w-wiredtiger-2
50+
pre: |
51+
Start :program:`mongod` as a config server, specifying ``wiredTiger``
52+
as the :option:`--storageEngine` and the newly created data directory
53+
for WiredTiger as the :option:`--dbpath`. Specify additional options
54+
as appropriate.
55+
action:
56+
language: sh
57+
code: |
58+
mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
59+
post: |
60+
61+
.. include:: /includes/fact-storage-engine-configuration-file-setting.rst
62+
---
63+
title: "Upload the exported data using ``mongorestore`` to the **second** config server."
64+
ref: change-wt-config-svr-upload-data-2
65+
action:
66+
language: sh
67+
code: |
68+
mongorestore <exportDataDestination>
69+
post: |
70+
Specify additional options as appropriate. See
71+
:program:`mongorestore` for available options.
72+
---
73+
title: "Shut down the **second** config server."
74+
ref: change-wt-config-svr-shutdown-2
75+
pre: |
76+
When the :program:`mongorestore` procedure of the previous step is
77+
complete, use the :program:`mongo` shell to shut down the second
78+
config server. This is necessary to maintain only two active config
79+
servers at once and keep the sharded cluster's metadata read-only.
80+
action:
81+
language: sh
82+
code: |
83+
db.shutdownServer()
84+
---
85+
title: "Restart the **third** config server."
86+
ref: change-wt-config-svr-restart-3
87+
pre: |
88+
Simply restart the third config server with its original startup
89+
options. **Do not** change it to use the WiredTiger storage engine
90+
yet, as that will be done in a later step.
91+
action:
92+
language: sh
93+
code: |
94+
mongod --configsvr
95+
---
96+
title: "Export the data of the **third** config server with ``mongodump``."
97+
ref: change-wt-config-svr-export-3
98+
action:
99+
language: sh
100+
code: |
101+
mongodump --out <exportDataDestination>
102+
post: |
103+
Specify additional options as appropriate, such as username and
104+
password if running with authorization enabled. See
105+
:program:`mongodump` for available options.
106+
---
107+
title: "For the **third** config server, create a data directory for the new ``mongod`` running with WiredTiger."
108+
ref: change-wt-config-svr-create-dir-3
109+
content: |
110+
Create a data directory for the new :program:`mongod` instance that
111+
will run with the WiredTiger storage engine. ``mongod`` must have read
112+
and write permissions for this directory.
113+
114+
``mongod`` with WiredTiger will not start with data files created with
115+
a different storage engine.
116+
---
117+
title: "Start the **third** config server with WiredTiger."
118+
ref: change-wt-config-svr-restart-w-wiredtiger-3
119+
pre: |
120+
Start :program:`mongod` as a config server, specifying ``wiredTiger``
121+
as the :option:`--storageEngine` and the newly created data directory
122+
for WiredTiger as the :option:`--dbpath`. Specify additional options
123+
as appropriate.
124+
action:
125+
language: sh
126+
code: |
127+
mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
128+
post: |
129+
.. include:: /includes/fact-storage-engine-configuration-file-setting.rst
130+
---
131+
title: "Upload the exported data using ``mongorestore`` to the **third** config server."
132+
ref: change-wt-config-svr-upload-data-3
133+
action:
134+
language: sh
135+
code: |
136+
mongorestore <exportDataDestination>
137+
post: |
138+
Specify additional options as appropriate. See
139+
:program:`mongorestore` for available options
140+
---
141+
title: "Export data of the **first** config server with ``mongodump``."
142+
ref: change-wt-config-svr-export-1
143+
action:
144+
language: sh
145+
code: |
146+
mongodump --out <exportDataDestination>
147+
post: |
148+
Specify additional options as appropriate, such as username and
149+
password if running with authorization enabled. See
150+
:program:`mongodump` for available options.
151+
---
152+
title: "For the **first** config server, create a data directory for the new ``mongod`` running with WiredTiger."
153+
ref: change-wt-config-svr-create-dir-1
154+
content: |
155+
Create a data directory for the new :program:`mongod` instance that
156+
will run with the WiredTiger storage engine. ``mongod`` must have read
157+
and write permissions for this directory.
158+
159+
``mongod`` with WiredTiger will not start with data files created with
160+
a different storage engine.
161+
---
162+
title: "Start the **first** config server with WiredTiger."
163+
ref: change-wt-config-svr-restart-w-wiredtiger-1
164+
pre: |
165+
Start :program:`mongod` as a config server, specifying ``wiredTiger``
166+
as the :option:`--storageEngine` and the newly created data directory
167+
for WiredTiger as the :option:`--dbpath`. Specify additional options
168+
as appropriate.
169+
action:
170+
language: sh
171+
code: |
172+
mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
173+
post: |
174+
.. include:: /includes/fact-storage-engine-configuration-file-setting.rst
175+
---
176+
title: "Upload the exported data using ``mongorestore`` to the **first** config server."
177+
ref: change-wt-config-svr-upload-data-1
178+
action:
179+
language: sh
180+
code: |
181+
mongorestore <exportDataDestination>
182+
post: |
183+
Specify additional options as appropriate. See
184+
:program:`mongorestore` for available options
185+
---
186+
title: "Enable writes to the sharded cluster's metadata."
187+
ref: change-wt-config-svr-start-2
188+
pre: |
189+
Restart the **second** config server with the same options as in step
190+
5. Remember to specify WiredTiger as the :option:`--storageEngine` and
191+
the newly created WiredTiger data directory as the :option:`--dbpath`.
192+
action:
193+
language: sh
194+
code: |
195+
mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
196+
post: |
197+
.. include:: /includes/fact-storage-engine-configuration-file-setting.rst
198+
199+
Once all three config servers are up, the sharded cluster's metadata
200+
is available for writes.
201+
---
202+
title: "Re-enable the balancer."
203+
ref: change-wt-config-svr-reenable-balancer
204+
pre: |
205+
Once all three config servers are up and running with WiredTiger,
206+
:ref:`re-enable the balancer <sharding-balancing-enable>`.
207+
action:
208+
language: sh
209+
code: |
210+
sh.startBalancer()
211+
...

‎source/includes/steps-change-replica-set-wiredtiger.yaml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
title: "Shut down the secondary member."
2+
ref: change-wt-repl-sync-shutdown-secondary
3+
pre: |
4+
In the :program:`mongo` shell, shut down the secondary :program:`mongod`
5+
instance you wish to upgrade.
6+
action:
7+
language: sh
8+
code: |
9+
db.shutdownServer()
10+
---
11+
title: "Prepare a data directory for the new ``mongod`` running with WiredTiger."
12+
ref: change-wt-repl-sync-wiredtiger-dir
13+
pre: |
14+
Prepare a data directory for the new :program:`mongod` instance that
15+
will run with the WiredTiger storage engine. ``mongod`` must have read
16+
and write permissions for this directory. You can either delete the
17+
contents of the stopped secondary member's current data directory or
18+
create a new directory entirely.
19+
20+
``mongod`` with WiredTiger will not start with data files created with
21+
a different storage engine.
22+
---
23+
title: "Start ``mongod`` with WiredTiger."
24+
ref: change-wt-repl-sync-start-mongod-w-wiredtiger
25+
pre: |
26+
Start :program:`mongod`, specifying ``wiredTiger`` as the
27+
:option:`--storageEngine` and the prepared data directory for
28+
WiredTiger as the :option:`--dbpath`. Specify additional options as
29+
appropriate for this replica set member.
30+
action:
31+
language: sh
32+
code: |
33+
mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName>
34+
post: |
35+
Since no data exists in the ``--dbpath``, the ``mongod`` will perform an
36+
:doc:`initial sync </tutorial/resync-replica-set-member>`. The length of the
37+
initial sync process depends on the size of the database and network
38+
connection between members of the replica set.
39+
40+
.. include:: /includes/fact-storage-engine-configuration-file-setting.rst
41+
---
42+
title: "Repeat the procedure for other replica set secondaries you wish to upgrade."
43+
ref: change-wt-repl-sync-repeat
44+
pre: |
45+
Perform this procedure again for the rest of the :term:`secondary
46+
members <secondary>` of the replica set you wish to use the WiredTiger
47+
storage engine.
48+
...

‎source/includes/steps-change-standalone-wiredtiger.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ content: |
2121
will run with the WiredTiger storage engine. ``mongod`` must have read
2222
and write permissions for this directory.
2323
24-
:program:`mongod` with WiredTiger will not start with data files
25-
created with a different storage engine.
24+
``mongod`` with WiredTiger will not start with data files created with
25+
a different storage engine.
2626
---
2727
title: "Start ``mongod`` with WiredTiger."
2828
ref: change-wt-standalone-start-mongod-w-wiredtiger

‎source/tutorial/change-config-server-wiredtiger.txt

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
===================================
2+
Change Config Servers to WiredTiger
3+
===================================
4+
5+
.. default-domain:: mongodb
6+
7+
.. versionadded:: 3.0
8+
The WiredTiger storage engine is available.
9+
10+
.. versionchanged:: 3.2
11+
WiredTiger is the new default storage engine for MongoDB.
12+
13+
This tutorial gives an overview of changing the storage engine of the
14+
:term:`config servers <config server>` in a :term:`sharded cluster` to
15+
:ref:`WiredTiger <storage-wiredtiger>`.
16+
17+
Considerations
18+
--------------
19+
20+
.. include:: /includes/fact-config-server-storage-engine-mix.rst
21+
22+
.. include:: /includes/fact-wiredtiger-minimum-version.rst
23+
24+
Procedure
25+
---------
26+
27+
This tutorial assumes that you have three config servers for this
28+
sharded cluster. The three servers are named **first**, **second**, and
29+
**third**, based on their position in the :program:`mongos`
30+
:setting:`~sharding.configDB` setting.
31+
32+
.. note::
33+
34+
During this process, only two config servers will be running at any
35+
given time to ensure that the sharded cluster's metadata is
36+
**read-only**.
37+
38+
.. include:: /includes/steps/change-config-server-wiredtiger.rst

0 commit comments

Comments
 (0)