From 48261b5e74ea069ec27dccadce65d916eb7853ca Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 13 Dec 2012 18:08:12 -0500 Subject: [PATCH 1/2] DOCS-654 new 2.0 index format --- source/release-notes/2.0.txt | 27 ++++++++++++- source/tutorial/roll-back-to-v18-index.txt | 46 ++++++++++++++++++++++ 2 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 source/tutorial/roll-back-to-v18-index.txt diff --git a/source/release-notes/2.0.txt b/source/release-notes/2.0.txt index 05d9999b823..03cd62a9d48 100644 --- a/source/release-notes/2.0.txt +++ b/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 @@ -43,6 +42,26 @@ In addition, you may see reduced write throughput. :program:`mongod` instances; however, for best results, upgrade your deployments using the following procedures: +.. _2.0-convert-to-new-index-format: + +Converting an Existing Index to the New Format +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To convert all indexes for a given collection to the +:ref:`2.0 type <2.0-new-index-format>`, invoke the +:doc:`compact ` command. + +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. + .. _2.0-upgrade-standalone: Upgrading a Standalone ``mongod`` @@ -130,6 +149,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -145,6 +166,8 @@ from 819 to 1024 bytes. Once you create new indexes, downgrading to 1.8.x will require a re-index of any indexes created using 2.0. +.. seealso:: :ref:`2.0-convert-to-new-index-format` + Sharding Authentication ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/roll-back-to-v18-index.txt b/source/tutorial/roll-back-to-v18-index.txt new file mode 100644 index 00000000000..1978d390c6a --- /dev/null +++ b/source/tutorial/roll-back-to-v18-index.txt @@ -0,0 +1,46 @@ +================================ +Roll Back to a Version 1.8 Index +================================ + +.. default-domain:: mongodb + + +MongoDB version 2.0 and later supports the old index format. But old versions +will not support the new format. If you need to roll back to an older +version, the server will run, but queries and other operations involving +the newer indexes will log and return an error. Thus, you will need to +re-create any new index you would like to use on an old server. + +Versions prior to 1.8.2, inclusive, are not aware of the index version +field. If you rollback a ``{v:1}`` index to 1.8.2 and re-index it, its +version will still be marked ``{v: 1}``, although it actual is now version ``{v:0}``. +If you upgrade again to 2.0, this index will not work, even though it is +marked as ``{v: 1}`` in ``system.indexes``. If you must roll back to a +version prior to 1.8.2, you must delete the index then create it again +(instead of simply re-indexing). + +Building a {v:0} Index +---------------------- + +You can still create a ``{v:0}`` index with MongoDB version 2.0 or later. To do so, add the +option ``{v:0}`` in the index creation command. For example in the :program:`mongo` +shell: + +.. code-block:: javascript + + // defaults to a v:1 index + db.foo.ensureIndex({name:1}) + db.system.indexes.find() + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" } + { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" } + db.foo.dropIndex({name:1}) + { "nIndexesWas" : 2, "ok" : 1 } + + // create a v:0 index + db.foo.ensureIndex({name:1},{v:0}) + db.system.indexes.find() + { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" } + + { "v" : 0, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" } + +.. seealso:: :ref:`2.0-new-index-format` and :ref:`2.0-convert-to-new-index-format` From 8092b2a9e93b721670ba30f0e93331a564ebe9a8 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 14 Dec 2012 15:19:13 -0500 Subject: [PATCH 2/2] DOCS-654 review edits --- source/release-notes/2.0.txt | 39 ++++------ source/tutorial.txt | 1 + source/tutorial/roll-back-to-v18-index.txt | 91 ++++++++++++---------- 3 files changed, 66 insertions(+), 65 deletions(-) diff --git a/source/release-notes/2.0.txt b/source/release-notes/2.0.txt index 03cd62a9d48..8b16cf7a25c 100644 --- a/source/release-notes/2.0.txt +++ b/source/release-notes/2.0.txt @@ -42,26 +42,6 @@ In addition, you may see reduced write throughput. :program:`mongod` instances; however, for best results, upgrade your deployments using the following procedures: -.. _2.0-convert-to-new-index-format: - -Converting an Existing Index to the New Format -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To convert all indexes for a given collection to the -:ref:`2.0 type <2.0-new-index-format>`, invoke the -:doc:`compact ` command. - -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. - .. _2.0-upgrade-standalone: Upgrading a Standalone ``mongod`` @@ -163,10 +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. -Once you create new indexes, downgrading to 1.8.x will require a -re-index of any indexes created using 2.0. +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`. -.. seealso:: :ref:`2.0-convert-to-new-index-format` +- 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. See +:doc:`/tutorial/roll-back-to-v18-index`. Sharding Authentication ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial.txt b/source/tutorial.txt index 66f9edc9443..c871c0b2dcf 100644 --- a/source/tutorial.txt +++ b/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 diff --git a/source/tutorial/roll-back-to-v18-index.txt b/source/tutorial/roll-back-to-v18-index.txt index 1978d390c6a..46c2a478078 100644 --- a/source/tutorial/roll-back-to-v18-index.txt +++ b/source/tutorial/roll-back-to-v18-index.txt @@ -1,46 +1,53 @@ -================================ -Roll Back to a Version 1.8 Index -================================ +======================= +Build Old Style Indexes +======================= .. default-domain:: mongodb +.. important:: -MongoDB version 2.0 and later supports the old index format. But old versions -will not support the new format. If you need to roll back to an older -version, the server will run, but queries and other operations involving -the newer indexes will log and return an error. Thus, you will need to -re-create any new index you would like to use on an old server. - -Versions prior to 1.8.2, inclusive, are not aware of the index version -field. If you rollback a ``{v:1}`` index to 1.8.2 and re-index it, its -version will still be marked ``{v: 1}``, although it actual is now version ``{v:0}``. -If you upgrade again to 2.0, this index will not work, even though it is -marked as ``{v: 1}`` in ``system.indexes``. If you must roll back to a -version prior to 1.8.2, you must delete the index then create it again -(instead of simply re-indexing). - -Building a {v:0} Index ----------------------- - -You can still create a ``{v:0}`` index with MongoDB version 2.0 or later. To do so, add the -option ``{v:0}`` in the index creation command. For example in the :program:`mongo` -shell: - -.. code-block:: javascript - - // defaults to a v:1 index - db.foo.ensureIndex({name:1}) - db.system.indexes.find() - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" } - { "v" : 1, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" } - db.foo.dropIndex({name:1}) - { "nIndexesWas" : 2, "ok" : 1 } - - // create a v:0 index - db.foo.ensureIndex({name:1},{v:0}) - db.system.indexes.find() - { "v" : 1, "key" : { "_id" : 1 }, "ns" : "mydb.foo", "name" : "_id_" } - - { "v" : 0, "key" : { "name" : 1 }, "ns" : "mydb.foo", "name" : "name_1" } - -.. seealso:: :ref:`2.0-new-index-format` and :ref:`2.0-convert-to-new-index-format` + 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() +` and :method:`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`. \ No newline at end of file