DOCS-654 new 2.0 index format

source/release-notes/2.0.txt

@@ -24,8 +24,7 @@ Read through all release notes before upgrading, and ensure that no
 changes will affect your deployment.
 
 If you create new indexes in 2.0, then downgrading to 1.8 is possible
-but you must reindex the new collections. For more information on 2.0
-indexes and on rollback, see :wiki:`Index Versions`.
+but you must reindex the new collections.
 
 :program:`mongoimport` and :program:`mongoexport` now correctly adhere to the CSV spec
 for handling CSV input/output. This may break existing import/export
@@ -130,6 +129,8 @@ swapped out if unused, some operating systems do this slowly enough that
 it might be an issue. The default stack size is lesser of the
 system setting or 1MB.
 
+.. _2.0-new-index-format:
+
 Index Performance Enhancements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -142,8 +143,23 @@ type are realized only if you create a new index or re-index an old one.
 Dates are now signed, and the max index key size has increased slightly
 from 819 to 1024 bytes.
 
+All operations that create a new index will result in a 2.0 index by
+default. For example:
+
+- Reindexing results on an older-version index results in a 2.0 index.
+  However, reindexing on a secondary does *not* work in versions prior
+  to 2.0. Do not reindex on a secondary. For a workaround, see
+  :issue:`SERVER-3866`.
+
+- The :setting:`repair` database command converts indexes to a 2.0
+  indexes.
+
+To convert all indexes for a given collection to the :ref:`2.0 type
+<2.0-new-index-format>`, invoke the :dbcommand:`compact` command.
+
 Once you create new indexes, downgrading to 1.8.x will require a
-re-index of any indexes created using 2.0.
+re-index of any indexes created using 2.0. See
+:doc:`/tutorial/roll-back-to-v18-index`.
 
 Sharding Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~

source/tutorial.txt

@@ -55,6 +55,7 @@ Development Patterns
    tutorial/create-an-auto-incrementing-field
    tutorial/enforce-unique-keys-for-sharded-collections
    tutorial/aggregation-examples
+   tutorial/roll-back-to-v18-index
 
 .. index:: tutorials; application development
 .. index:: application tutorials

source/tutorial/roll-back-to-v18-index.txt

@@ -0,0 +1,53 @@
+=======================
+Build Old Style Indexes
+=======================
+
+.. default-domain:: mongodb
+
+.. important::
+
+   Use this procedure *only* if you must have indexes that are compatible
+   with a version of MongoDB earlier than 2.0.
+
+MongoDB version 2.0 introduced the ``{v:1}`` index format. MongoDB
+versions 2.0 and later support both the ``{v:1}`` format and the
+earlier ``{v:0}`` format.
+
+MongoDB versions prior to 1.8.2, however, support only the ``{v:0}``
+format. If you need to roll back MongoDB to a version prior to 2.0, you
+must *drop* and *re-create* your indexes.
+
+You do so using the :method:`dropIndexes()
+<db.collection.dropIndexes()>` and :method:`ensureIndex()
+<db.collection.ensureIndex()>` methods. You *cannot* simply reindex the
+collection. If you simply reindex, the ``v`` fields in your indexes
+would still hold values of ``1``, even though the indexes would now use
+the ``{v:0}`` format. If you were to upgrade again to version 2.0 or
+later, your indexes would not work.
+
+.. example::
+
+   Suppose you rolled back from MongoDB 2.0 to MongoDB 1.8, and suppose
+   you had the following index on the ``items`` collection:
+
+   .. code-block:: javascript
+
+      { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.items", "name" : "name_1" }
+
+   The ``v`` field tells you the index is a ``{v:1}`` index, which
+   is incompatible with version 1.8.
+
+   To drop the index, issue the following command:
+
+   .. code-block:: javascript
+
+      db.items.dropIndex( { name : 1 } )
+
+   To recreate the index as a ``{v:0}`` index, issue the following
+   command:
+
+   .. code-block:: javascript
+
+      db.foo.ensureIndex( { name : 1 } , { v : 0 } )
+
+.. seealso:: :ref:`2.0-new-index-format`.