diff --git a/config/sphinx_local.yaml b/config/sphinx_local.yaml index 75c0c2adf76..b62ffa67c3e 100644 --- a/config/sphinx_local.yaml +++ b/config/sphinx_local.yaml @@ -12,37 +12,38 @@ theme: jira: 'DOCS' sitename: 'MongoDB Docs' nav_excluded: + - /administration/production-checklist - /aggregation + - /applications/geospatial-indexes + - /contributors/getting-started + - /core/authorization + - /core/journaling - /core/map-reduce - - /core/replica-set-members - /core/replica-set-architectures - /core/replica-set-high-availability - - /applications/geospatial-indexes + - /core/replica-set-members - /core/sharded-cluster-components - - /security - - /core/authentication - - /core/authorization + - /core/wiredtiger - /installation - - /reference/security - - /reference/indexes - - /reference/replication - - /reference/sharding + - /products/bi-connector - /reference/command + - /reference/indexes - /reference/method - - /reference/operator/query - - /reference/operator/update - /reference/operator/aggregation + - /reference/operator/query - /reference/operator/query-modifier + - /reference/operator/update + - /reference/replication + - /reference/security + - /reference/sharding - /release-notes/2.4 - /release-notes/2.6 - /release-notes/2.8 - /release-notes/3.0 - /release-notes/3.2 + - /security - /storage - - /administration/production-checklist - - /contributors/getting-started - - /core/journaling - - /products/bi-connector + - /tutorial/change-sharded-cluster-wiredtiger sidebars: '**': - 'pagenav.html' diff --git a/source/core/wiredtiger.txt b/source/core/wiredtiger.txt index 87e84efb499..7d993b34792 100644 --- a/source/core/wiredtiger.txt +++ b/source/core/wiredtiger.txt @@ -136,3 +136,12 @@ The WiredTiger journal is also compressed by default. For information on journal compression, see :ref:`storage-wiredtiger-journal`. .. seealso:: ``_ + +.. class:: hidden + + .. toctree:: + :titlesonly: + + /tutorial/change-standalone-wiredtiger.txt + /tutorial/change-replica-set-wiredtiger.txt + /tutorial/change-sharded-cluster-wiredtiger.txt diff --git a/source/includes/fact-config-server-storage-engine-mix.rst b/source/includes/fact-config-server-storage-engine-mix.rst new file mode 100644 index 00000000000..81383fd8f82 --- /dev/null +++ b/source/includes/fact-config-server-storage-engine-mix.rst @@ -0,0 +1,5 @@ +You may safely **continue** to use :ref:`MMAPv1 ` for +the :term:`config servers ` even if the shards of the +sharded cluster is using the WiredTiger storage engine. If you do choose +to update the config servers to use WiredTiger, you must update **all +three**. diff --git a/source/includes/fact-storage-engine-configuration-file-setting.rst b/source/includes/fact-storage-engine-configuration-file-setting.rst index 527f20963af..0df8a04b033 100644 --- a/source/includes/fact-storage-engine-configuration-file-setting.rst +++ b/source/includes/fact-storage-engine-configuration-file-setting.rst @@ -1,3 +1,3 @@ You can also specify the options in a :doc:`configuration file `. To specify the storage engine, use -the new :setting:`storage.engine` setting. +the :setting:`storage.engine` setting. diff --git a/source/includes/fact-wiredtiger-minimum-version.rst b/source/includes/fact-wiredtiger-minimum-version.rst new file mode 100644 index 00000000000..467da42bddc --- /dev/null +++ b/source/includes/fact-wiredtiger-minimum-version.rst @@ -0,0 +1,6 @@ +You must be using MongoDB version 3.0 or greater in order to use the +WiredTiger storage engine. If upgrading from an earlier version of +MongoDB, see the guides on :doc:`Upgrading to MongoDB 3.0 +` or :doc:`Upgrading to MongoDB 3.2 +` before proceeding with changing your +storage engine. diff --git a/source/includes/steps-change-config-server-wiredtiger.yaml b/source/includes/steps-change-config-server-wiredtiger.yaml new file mode 100644 index 00000000000..6d73848c63f --- /dev/null +++ b/source/includes/steps-change-config-server-wiredtiger.yaml @@ -0,0 +1,211 @@ +title: "Disable the balancer." +ref: change-wt-config-svr-disable-balancer +content: | + Turn off the :ref:`balancer ` in the + sharded cluster, as described in + :ref:`sharding-balancing-disable-temporarily`. +action: + language: sh + code: | + sh.disableBalancer() +--- +title: "Shut down the **third** config server." +ref: change-wt-config-svr-shutdown-3 +content: | + Use the :program:`mongo` shell to shut down the third config server. + + The third config server is the last one listed in the + :program:`mongos` :setting:`~sharding.configDB` setting. +action: | + language: sh + code: | + db.shutdownServer() +--- +title: "Export the data of the **second** config server with ``mongodump``." +ref: change-wt-config-svr-export-2 +pre: | + The second config server is the second server listed in the + :program:`mongos` setting :setting:`~sharding.configDB`. +action: + language: sh + code: | + mongodump --out +post: | + Specify additional options as appropriate, such as username and + password if running with authorization enabled. See + :program:`mongodump` for available options. +--- +title: "For the **second** config server, create a data directory for the new ``mongod`` running with WiredTiger." +ref: change-wt-config-svr-create-dir-2 +content: | + Create a data directory for the new :program:`mongod` instance that + will run with the WiredTiger storage engine. ``mongod`` must have read + and write permissions for this directory. + + ``mongod`` with WiredTiger will not start with data files created with + a different storage engine. +--- +title: "Start the **second** config server ``mongod`` with WiredTiger." +ref: change-wt-config-svr-restart-w-wiredtiger-2 +pre: | + Start :program:`mongod` as a config server, specifying ``wiredTiger`` + as the :option:`--storageEngine` and the newly created data directory + for WiredTiger as the :option:`--dbpath`. Specify additional options + as appropriate. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath --configsvr +post: | + + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst +--- +title: "Upload the exported data using ``mongorestore`` to the **second** config server." +ref: change-wt-config-svr-upload-data-2 +action: + language: sh + code: | + mongorestore +post: | + Specify additional options as appropriate. See + :program:`mongorestore` for available options. +--- +title: "Shut down the **second** config server." +ref: change-wt-config-svr-shutdown-2 +pre: | + When the :program:`mongorestore` procedure of the previous step is + complete, use the :program:`mongo` shell to shut down the second + config server. This is necessary to maintain only two active config + servers at once and keep the sharded cluster's metadata read-only. +action: + language: sh + code: | + db.shutdownServer() +--- +title: "Restart the **third** config server." +ref: change-wt-config-svr-restart-3 +pre: | + Simply restart the third config server with its original startup + options. **Do not** change it to use the WiredTiger storage engine + yet, as that will be done in a later step. +action: + language: sh + code: | + mongod --configsvr +--- +title: "Export the data of the **third** config server with ``mongodump``." +ref: change-wt-config-svr-export-3 +action: + language: sh + code: | + mongodump --out +post: | + Specify additional options as appropriate, such as username and + password if running with authorization enabled. See + :program:`mongodump` for available options. +--- +title: "For the **third** config server, create a data directory for the new ``mongod`` running with WiredTiger." +ref: change-wt-config-svr-create-dir-3 +content: | + Create a data directory for the new :program:`mongod` instance that + will run with the WiredTiger storage engine. ``mongod`` must have read + and write permissions for this directory. + + ``mongod`` with WiredTiger will not start with data files created with + a different storage engine. +--- +title: "Start the **third** config server with WiredTiger." +ref: change-wt-config-svr-restart-w-wiredtiger-3 +pre: | + Start :program:`mongod` as a config server, specifying ``wiredTiger`` + as the :option:`--storageEngine` and the newly created data directory + for WiredTiger as the :option:`--dbpath`. Specify additional options + as appropriate. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath --configsvr +post: | + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst +--- +title: "Upload the exported data using ``mongorestore`` to the **third** config server." +ref: change-wt-config-svr-upload-data-3 +action: + language: sh + code: | + mongorestore +post: | + Specify additional options as appropriate. See + :program:`mongorestore` for available options +--- +title: "Export data of the **first** config server with ``mongodump``." +ref: change-wt-config-svr-export-1 +action: + language: sh + code: | + mongodump --out +post: | + Specify additional options as appropriate, such as username and + password if running with authorization enabled. See + :program:`mongodump` for available options. +--- +title: "For the **first** config server, create a data directory for the new ``mongod`` running with WiredTiger." +ref: change-wt-config-svr-create-dir-1 +content: | + Create a data directory for the new :program:`mongod` instance that + will run with the WiredTiger storage engine. ``mongod`` must have read + and write permissions for this directory. + + ``mongod`` with WiredTiger will not start with data files created with + a different storage engine. +--- +title: "Start the **first** config server with WiredTiger." +ref: change-wt-config-svr-restart-w-wiredtiger-1 +pre: | + Start :program:`mongod` as a config server, specifying ``wiredTiger`` + as the :option:`--storageEngine` and the newly created data directory + for WiredTiger as the :option:`--dbpath`. Specify additional options + as appropriate. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath --configsvr +post: | + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst +--- +title: "Upload the exported data using ``mongorestore`` to the **first** config server." +ref: change-wt-config-svr-upload-data-1 +action: + language: sh + code: | + mongorestore +post: | + Specify additional options as appropriate. See + :program:`mongorestore` for available options +--- +title: "Enable writes to the sharded cluster's metadata." +ref: change-wt-config-svr-start-2 +pre: | + Restart the **second** config server with the same options as in step + 5. Remember to specify WiredTiger as the :option:`--storageEngine` and + the newly created WiredTiger data directory as the :option:`--dbpath`. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath --configsvr +post: | + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst + + Once all three config servers are up, the sharded cluster's metadata + is available for writes. +--- +title: "Re-enable the balancer." +ref: change-wt-config-svr-reenable-balancer +pre: | + Once all three config servers are up and running with WiredTiger, + :ref:`re-enable the balancer `. +action: + language: sh + code: | + sh.startBalancer() +... diff --git a/source/includes/steps-change-replica-set-wiredtiger.yaml b/source/includes/steps-change-replica-set-wiredtiger.yaml new file mode 100644 index 00000000000..224fbc9f255 --- /dev/null +++ b/source/includes/steps-change-replica-set-wiredtiger.yaml @@ -0,0 +1,48 @@ +title: "Shut down the secondary member." +ref: change-wt-repl-sync-shutdown-secondary +pre: | + In the :program:`mongo` shell, shut down the secondary :program:`mongod` + instance you wish to upgrade. +action: + language: sh + code: | + db.shutdownServer() +--- +title: "Prepare a data directory for the new ``mongod`` running with WiredTiger." +ref: change-wt-repl-sync-wiredtiger-dir +pre: | + Prepare a data directory for the new :program:`mongod` instance that + will run with the WiredTiger storage engine. ``mongod`` must have read + and write permissions for this directory. You can either delete the + contents of the stopped secondary member's current data directory or + create a new directory entirely. + + ``mongod`` with WiredTiger will not start with data files created with + a different storage engine. +--- +title: "Start ``mongod`` with WiredTiger." +ref: change-wt-repl-sync-start-mongod-w-wiredtiger +pre: | + Start :program:`mongod`, specifying ``wiredTiger`` as the + :option:`--storageEngine` and the prepared data directory for + WiredTiger as the :option:`--dbpath`. Specify additional options as + appropriate for this replica set member. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath --replSet +post: | + Since no data exists in the ``--dbpath``, the ``mongod`` will perform an + :doc:`initial sync `. The length of the + initial sync process depends on the size of the database and network + connection between members of the replica set. + + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst +--- +title: "Repeat the procedure for other replica set secondaries you wish to upgrade." +ref: change-wt-repl-sync-repeat +pre: | + Perform this procedure again for the rest of the :term:`secondary + members ` of the replica set you wish to use the WiredTiger + storage engine. +... diff --git a/source/includes/steps-change-standalone-wiredtiger.yaml b/source/includes/steps-change-standalone-wiredtiger.yaml new file mode 100644 index 00000000000..e0692a6d4e0 --- /dev/null +++ b/source/includes/steps-change-standalone-wiredtiger.yaml @@ -0,0 +1,50 @@ +title: "Start the ``mongod`` you wish to change to WiredTiger." +ref: change-wt-standalone-start +content: | + If :program:`mongod` is already running, you can skip this step. +--- +title: "Export data using ``mongodump``." +ref: change-wt-standalone-export-data +action: + language: sh + code: | + mongodump --out +post: | + Specify additional options as appropriate, such as username and + password if running with authorization enabled. See + :program:`mongodump` for available options. +--- +title: "Create a data directory for the new ``mongod`` running with WiredTiger." +ref: change-wt-standalone-create-wiredtiger-dir +content: | + Create a data directory for the new :program:`mongod` instance that + will run with the WiredTiger storage engine. ``mongod`` must have read + and write permissions for this directory. + + ``mongod`` with WiredTiger will not start with data files created with + a different storage engine. +--- +title: "Start ``mongod`` with WiredTiger." +ref: change-wt-standalone-start-mongod-w-wiredtiger +pre: | + Start :program:`mongod`, specifying ``wiredTiger`` as the + :option:`--storageEngine` and the newly created data directory for + WiredTiger as the :option:`--dbpath`. Specify additional options as + appropriate. +action: + language: sh + code: | + mongod --storageEngine wiredTiger --dbpath +post: | + .. include:: /includes/fact-storage-engine-configuration-file-setting.rst +--- +title: "Upload the exported data using ``mongorestore``." +ref: change-wt-standalone-upload-data +action: + language: sh + code: | + mongorestore +post: | + Specify additional options as appropriate. See + :program:`mongorestore` for available options. +... diff --git a/source/tutorial/change-config-server-wiredtiger.txt b/source/tutorial/change-config-server-wiredtiger.txt new file mode 100644 index 00000000000..700f81ae356 --- /dev/null +++ b/source/tutorial/change-config-server-wiredtiger.txt @@ -0,0 +1,38 @@ +=================================== +Change Config Servers to WiredTiger +=================================== + +.. default-domain:: mongodb + +.. versionadded:: 3.0 + The WiredTiger storage engine is available. + +.. versionchanged:: 3.2 + WiredTiger is the new default storage engine for MongoDB. + +This tutorial gives an overview of changing the storage engine of the +:term:`config servers ` in a :term:`sharded cluster` to +:ref:`WiredTiger `. + +Considerations +-------------- + +.. include:: /includes/fact-config-server-storage-engine-mix.rst + +.. include:: /includes/fact-wiredtiger-minimum-version.rst + +Procedure +--------- + +This tutorial assumes that you have three config servers for this +sharded cluster. The three servers are named **first**, **second**, and +**third**, based on their position in the :program:`mongos` +:setting:`~sharding.configDB` setting. + +.. note:: + + During this process, only two config servers will be running at any + given time to ensure that the sharded cluster's metadata is + **read-only**. + +.. include:: /includes/steps/change-config-server-wiredtiger.rst diff --git a/source/tutorial/change-replica-set-wiredtiger.txt b/source/tutorial/change-replica-set-wiredtiger.txt new file mode 100644 index 00000000000..0da6762dfe3 --- /dev/null +++ b/source/tutorial/change-replica-set-wiredtiger.txt @@ -0,0 +1,42 @@ +================================ +Change Replica Set to WiredTiger +================================ + +.. default-domain:: mongodb + +.. versionadded:: 3.0 + The WiredTiger storage engine is available. Also, replica sets may + have members with different storage engines. + +.. versionchanged:: 3.2 + WiredTiger is the new default storage engine for MongoDB. + +This tutorial gives an overview of changing the storage engine of a +member of a :term:`replica set` to :ref:`WiredTiger +`. + +Considerations +-------------- + +Replica sets can have members with different storage engines. As such, +you can update members to use the WiredTiger storage engine in a rolling +fashion. Before changing all the members to use WiredTiger, you may +prefer to run with mixed storage engines for some period. However, +performance can vary according to workload. + +.. include:: /includes/fact-wiredtiger-minimum-version.rst + +.. include:: /includes/2.6-3.0-mixed-version-wiredTiger-restriction.rst + +Procedure +--------- + +This procedure completely removes a :term:`secondary` replica set +member's data, starts :program:`mongod` with WiredTiger, and performs an +:doc:`initial sync `. + +To update all members of the replica set to use WiredTiger, update the +:term:`secondary` members first. Then step down the :term:`primary`, and +update the stepped-down member. + +.. include:: /includes/steps/change-replica-set-wiredtiger.rst diff --git a/source/tutorial/change-sharded-cluster-wiredtiger.txt b/source/tutorial/change-sharded-cluster-wiredtiger.txt new file mode 100644 index 00000000000..d5b75760e81 --- /dev/null +++ b/source/tutorial/change-sharded-cluster-wiredtiger.txt @@ -0,0 +1,63 @@ +==================================== +Change Sharded Cluster to WiredTiger +==================================== + +.. default-domain:: mongodb + +.. versionadded:: 3.0 + The WiredTiger storage engine is available. Also, sharded clusters + may have individual shards with different storage engine + configurations. + +.. versionchanged:: 3.2 + WiredTiger is the new default storage engine for MongoDB. + +This tutorial gives an overview of changing the storage engines of a +component of a :term:`sharded cluster` to :ref:`WiredTiger +`. + +Considerations +-------------- + +This procedure may involve downtime, especially if one or more of your +shards is a :term:`standalone`. If you change the host or port of any +:term:`shard`, you must update the shard configuration as well. + +.. include:: /includes/fact-wiredtiger-minimum-version.rst + +.. include:: /includes/2.6-3.0-mixed-version-wiredTiger-restriction.rst + +Change Shards to WiredTiger +--------------------------- + +.. note:: + + A sharded cluster **can** have mixed storage engines for its + individual :term:`shards `. + +To change the storage engine for the :term:`shards ` to +WiredTiger, refer to the appropriate procedure for each shard: + +- If the shard is a :term:`standalone`, see + :doc:`/tutorial/change-standalone-wiredtiger`. + +- If the shard is a :term:`replica set`, see + :doc:`/tutorial/change-replica-set-wiredtiger`. + +Change Config Servers to WiredTiger +----------------------------------- + +To change the storage engines of the :term:`config servers ` of a sharded cluster, see +:doc:`/tutorial/change-config-server-wiredtiger`. + +.. include:: /includes/fact-config-server-storage-engine-mix.rst + +.. seealso:: :doc:`/tutorial/change-config-server-wiredtiger` + +.. class:: hidden + + .. toctree:: + :titlesonly: + + /tutorial/change-config-server-wiredtiger.txt diff --git a/source/tutorial/change-standalone-wiredtiger.txt b/source/tutorial/change-standalone-wiredtiger.txt new file mode 100644 index 00000000000..a125fe07c13 --- /dev/null +++ b/source/tutorial/change-standalone-wiredtiger.txt @@ -0,0 +1,32 @@ +=============================== +Change Standalone to WiredTiger +=============================== + +.. default-domain:: mongodb + +.. versionadded:: 3.0 + The WiredTiger storage engine is available. + +.. versionchanged:: 3.2 + WiredTiger is the new default storage engine for MongoDB. + +This tutorial gives an overview of changing the storage engine of a +:term:`standalone` MongoDB instance to :ref:`WiredTiger +`. + +Considerations +-------------- + +This tutorial uses the :program:`mongodump` and :program:`mongorestore` +utilities to export and import data. Ensure that these MongoDB package +components are installed and updated on your system. In addition, make +sure you have sufficient drive space available for the +:program:`mongodump` export file and the data files of your new +:program:`mongod` instance running with WiredTiger. + +.. include:: /includes/fact-wiredtiger-minimum-version.rst + +Procedure +--------- + +.. include:: /includes/steps/change-standalone-wiredtiger.rst