From f27b4392aba1465f1906307e636cc73795ac9834 Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 18 Mar 2013 18:39:40 -0400 Subject: [PATCH] DOCS-1251, DOCS-1244, and some of Rassi's comments for DOCS-1188 --- .../fact-upgrade-sharded-cluster-prereq.rst | 5 ++ source/release-notes/2.4-index-types.txt | 10 +-- source/release-notes/2.4-upgrade.txt | 77 +++++++++++++------ source/release-notes/2.4.txt | 2 +- 4 files changed, 63 insertions(+), 31 deletions(-) create mode 100644 source/includes/fact-upgrade-sharded-cluster-prereq.rst diff --git a/source/includes/fact-upgrade-sharded-cluster-prereq.rst b/source/includes/fact-upgrade-sharded-cluster-prereq.rst new file mode 100644 index 00000000000..418889e1f1f --- /dev/null +++ b/source/includes/fact-upgrade-sharded-cluster-prereq.rst @@ -0,0 +1,5 @@ +Before you start the upgrade, ensure that the amount of free space on +the filesystem for the :doc:`config database +` is 4 to 5 times the amount of space +currently used by the :doc:`config database +` data files. diff --git a/source/release-notes/2.4-index-types.txt b/source/release-notes/2.4-index-types.txt index 53101e8cf8f..89743ccb6d1 100644 --- a/source/release-notes/2.4-index-types.txt +++ b/source/release-notes/2.4-index-types.txt @@ -41,9 +41,9 @@ creating any invalid index will result in an error. Furthermore, you cannot create a ``2dsphere`` or ``text`` index if your databases have any invalid index types. [#grandfathered-indexes]_ -.. [#grandfathered-indexes] In 2.4 indexes that specify a type of +.. [#grandfathered-indexes] In 2.4, indexes that specify a type of ``"1"`` or ``"-1"``(the strings ``"1"`` and ``"-1"``) will continue - to exist and can co-exist with ``2dsphere`` and ``text``, despite a - warning on start-up. **However**, a :term:`secondary` in a replica - set cannot complete initial sync from a primary that has a ``"1"`` - or ``"-1"`` index. Avoid all indexes with invalid types. + to exist, despite a warning on start-up. **However**, a + :term:`secondary` in a replica set cannot complete an initial sync + from a primary that has a ``"1"`` or ``"-1"`` index. Avoid all + indexes with invalid types. diff --git a/source/release-notes/2.4-upgrade.txt b/source/release-notes/2.4-upgrade.txt index 5a5d7ca329f..ae2d250d0fe 100644 --- a/source/release-notes/2.4-upgrade.txt +++ b/source/release-notes/2.4-upgrade.txt @@ -28,8 +28,8 @@ following procedures. Upgrade a Sharded Cluster from MongoDB 2.2 to MongoDB 2.4 --------------------------------------------------------- -.. important:: Only upgrade sharded clusters to 2.4 if all members of - the cluster are currently running instances of 2.2. The only +.. important:: Only upgrade sharded clusters to 2.4 if **all** members + of the cluster are currently running instances of 2.2. The only supported upgrade path for sharded clusters running 2.0 is via 2.2. Upgrading a :term:`sharded cluster` from MongoDB version 2.2 to 2.4 @@ -44,17 +44,38 @@ are capable of handling epochs, even though 2.2 did not require them. This procedure applies only to upgrades from version 2.2. Earlier versions of MongoDB do not correctly handle epochs. -While the upgrade is in progress, you cannot make changes to the -collection metadata. For example, you cannot perform operations that -add shards, drop databases, or drop collections, or modify the -metadata in any other way. - .. warning:: - Once you upgrade to 2.4 and complete the upgrade procedure **do - not** use 2.0 :program:`mongod` and :program:`mongos` processes in - your cluster. 2.0 process may re-introduce old metadata formats - into cluster metadata. + - .. include:: /includes/fact-upgrade-sharded-cluster-prereq.rst + + - While the upgrade is in progress, you cannot make changes to the + collection metadata. For example, during the upgrade, do **not** + perform: + + - :method:`sh.enableSharding()`, + + - :method:`sh.shardCollection()`, + + - :method:`sh.addShard()`, + + - :method:`db.createCollection()`, + + - :method:`db.collection.drop()`, + + - :method:`db.dropDatabase()`, + + - any operation that creates a database, or + + - any other operation that modifies the cluster metadata in any + way. See :doc:`/reference/sharding-commands` for a complete list + of sharding commands. Note, however, that not all commands on + the :doc:`/reference/sharding-commands` page modifies the + cluster metadata. + + - Once you upgrade to 2.4 and complete the upgrade procedure **do + not** use 2.0 :program:`mongod` and :program:`mongos` processes in + your cluster. 2.0 process may re-introduce old metadata formats + into cluster metadata. .. note:: @@ -71,9 +92,12 @@ Sharded Cluster Upgrade Procedure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Do not perform operations that modify metadata while performing this -procedure. +procedure. See :ref:`2.4-upgrade-cluster` for examples of prohibited +operations. -1. Turn off the :ref:`balancer ` in the +#. .. include:: /includes/fact-upgrade-sharded-cluster-prereq.rst + +#. Turn off the :ref:`balancer ` in the :term:`sharded cluster`, as described in :ref:`sharding-balancing-disable-temporally`. @@ -305,7 +329,7 @@ these indexes. For example: .. code-block:: javascript db.records.dropIndex( { loc: "2dsphere" } ) - db.records.dropIndex( { records: "text" } ) + db.records.dropIndex( { "records_text" } ) db.records.ensureIndex( { loc: "2dsphere" } ) db.records.ensureIndex( { records: "text" } ) @@ -315,19 +339,22 @@ these indexes. For example: Downgrade MongoDB from 2.4 to Previous Versions ----------------------------------------------- -For some cases the on-disk format of data files used by 2.4 -and 2.2 :program:`mongod` is compatible, and you can upgrade and -downgrade if needed. However, several new features in 2.4 require -additional attention. These features are: +For some cases the on-disk format of data files used by 2.4 and 2.2 +:program:`mongod` is compatible, and you can upgrade and downgrade if +needed. However, several new features in 2.4 are incompatible with +previous versions: -- ``2dsphere`` indexes on 2.2 and earlier :program:`mongod` instances. +- ``2dsphere`` indexes are incompatible with 2.2 and earlier + :program:`mongod` instances. -- ``text`` indexes on 2.2 and earlier :program:`mongod` instances. +- ``text`` indexes are incompatible with 2.2 and earlier + :program:`mongod` instances. -- using a ``hashed`` index as a shard key with 2.2 and earlier - :program:`mongos` instances +- using a ``hashed`` index as a shard key are incompatible with 2.2 and + earlier :program:`mongos` instances -- ``hashed`` indexes on 2.0 and earlier :program:`mongod` instances. +- ``hashed`` indexes are incompatible with 2.0 and earlier + :program:`mongod` instances. .. note:: @@ -413,11 +440,11 @@ indexes using :method:`db.collection.dropIndex()`, for example: .. code-block:: javascript db.records.dropIndex( { loc: "2dsphere" } ) - db.records.dropIndex( { records: "text" } ) + db.records.dropIndex( { "records_text" } ) .. warning:: - :option:`--upgrade ` will run + :option:`--upgrade ` will run :dbcommand:`repairDatabase` on any database where you have created a ``2dsphere`` or ``text`` index, which will rebuild *all* indexes. diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt index 708ba170be0..57f60990675 100644 --- a/source/release-notes/2.4.txt +++ b/source/release-notes/2.4.txt @@ -353,7 +353,7 @@ Before 2.4, :program:`mongod` would create an ascending scalar index that did not exist. Creating an index of an invalid index type will generate an error in 2.4. -See :doc:`/release-notes/2.4-index-types.txt` for more information. +See :doc:`/release-notes/2.4-index-types` for more information. Interface Changes +++++++++++++++++