From 764f02e7d6211fe75b69ca681b4fd4ebd565331f Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Mon, 24 Sep 2012 13:52:26 -0400 Subject: [PATCH 1/6] DOCS-540 document dropTarget option of renameCollection --- source/reference/command/renameCollection.txt | 41 +++++++++++++------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index b276cc8f9ce..ac245f2edde 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -4,27 +4,44 @@ renameCollection .. default-domain:: mongodb -.. dbcommand:: renameCollection +.. dbcommand:: renameCollection( source, to: target[, dropTarget=>true]) - The :dbcommand:`renameCollection` command changes the name of an existing - collection. Use the following form to rename the collection - named "things" to "events": + The :dbcommand:`renameCollection` command changes the name of an + existing collection. Use the following form to rename the collection + named ``source`` to ``target``: .. code-block:: javascript - { renameCollection: "store.things", to: "store.events" } + { renameCollection: "source", to: "target" } You must run this command against the admin database. and thus requires you to specify the complete namespace (i.e., database name and collection name.) - .. note:: - - :dbcommand:`renameCollection` will not succeed if you have - existing data, or indexes, in the new collection. - - The shell helper :method:`renameCollection()` provides a more - simple interface for this functionality. The following is + :var source: + + Specifies the name of the collection to be renamed. + + :param string to: + + Specifies the new name of the collection. + + :param dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. + :type dropTarget: true or false + + :raises 10027: + + Exception 10027 is thrown if the ``target`` collection exists + and ``dropTarget`` is either ``false`` or unspecified. + + .. warning:: + + :dbcommand:`renameCollection` will fail if + `target` is the name of an existing collection + and you do not specify ``dropTarget: true``. + + The shell helper :method:`renameCollection()` provides a + simpler interface for this functionality. The following is equivalent to the previous example: .. code-block:: javascript From 2192a6604b34a6197d4321712fec6939f6bde073 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Mon, 24 Sep 2012 14:49:49 -0400 Subject: [PATCH 2/6] DOCS-540 edits for style & substance due to difference in shell helper Shell helper command only operates within databases, not across databases. --- source/reference/command/renameCollection.txt | 43 +++++++++++++------ 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index ac245f2edde..720de3a8f3e 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -6,32 +6,43 @@ renameCollection .. dbcommand:: renameCollection( source, to: target[, dropTarget=>true]) - The :dbcommand:`renameCollection` command changes the name of an - existing collection. Use the following form to rename the collection - named ``source`` to ``target``: + The :dbcommand:`renameCollection` command is an administrative command which + changes the name of an existing collection. + If the ``target`` specifies a collection in a different database, the + ``source`` collection will be copied to the new database and then dropped. + You must issue the + :dbcommand:`renameCollection` + command against the :term:`admin database` in the form: .. code-block:: javascript { renameCollection: "source", to: "target" } - You must run this command against the admin database. and thus - requires you to specify the complete namespace (i.e., database name - and collection name.) + You must specify the complete :term:`namespace` (i.e., database name + and collection name): + + .. code-block:: javascript + + { renameCollection: "source-database.collection-name" to: "target-database.collection-name"} :var source: - Specifies the name of the collection to be renamed. + Specifies the complete namespace of the collection to be renamed. :param string to: - Specifies the new name of the collection. + Specifies the new namespace of the collection. :param dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. :type dropTarget: true or false - :raises 10027: + :exception 10026: - Exception 10027 is thrown if the ``target`` collection exists + Raised if the ``source`` namespace does not exist. + + :exception 10027: + + Raised if the ``target`` namespace exists and ``dropTarget`` is either ``false`` or unspecified. .. warning:: @@ -41,14 +52,18 @@ renameCollection and you do not specify ``dropTarget: true``. The shell helper :method:`renameCollection()` provides a - simpler interface for this functionality. The following is - equivalent to the previous example: + simpler interface to using this command within a database. + The following is equivalent to the previous example: .. code-block:: javascript - db.things.renameCollection( "events" ) + db.source.renameCollection( "target" ) + + The shell helper :method:`renameCollection()` cannot be used to copy + and rename a collection across databases. - :dbcommand:`renameCollection` operates by changing the metadata + :dbcommand:`renameCollection` operates within a collection + by changing the metadata associated with a given collection. The duration of the command is constant and not related to the size of the collection or the indexes; however, the operation will invalidate open cursors which From 8adfea9f5c8800c46e7175d8ebdc6290736f0753 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Tue, 25 Sep 2012 13:44:14 -0400 Subject: [PATCH 3/6] DOCS-540 change source and target to indicate namespaces --- source/reference/command/renameCollection.txt | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index 720de3a8f3e..d5337bed65f 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -4,28 +4,24 @@ renameCollection .. default-domain:: mongodb -.. dbcommand:: renameCollection( source, to: target[, dropTarget=>true]) +.. dbcommand:: renameCollection( source-namespace, to: target-namespace [, dropTarget=>true]) The :dbcommand:`renameCollection` command is an administrative command which changes the name of an existing collection. - If the ``target`` specifies a collection in a different database, the - ``source`` collection will be copied to the new database and then dropped. + If the ``target-namespace`` specifies a collection in a different database, the + ``source-namespace`` collection will be copied to the new database and then dropped. You must issue the :dbcommand:`renameCollection` command against the :term:`admin database` in the form: .. code-block:: javascript - { renameCollection: "source", to: "target" } + { renameCollection: , to: } You must specify the complete :term:`namespace` (i.e., database name - and collection name): + and collection name). - .. code-block:: javascript - - { renameCollection: "source-database.collection-name" to: "target-database.collection-name"} - - :var source: + :var source-namespace: Specifies the complete namespace of the collection to be renamed. @@ -44,6 +40,10 @@ renameCollection Raised if the ``target`` namespace exists and ``dropTarget`` is either ``false`` or unspecified. + + :exception 15967: + + Raised if the ``target`` namespace is an invalid collection name. .. warning:: @@ -57,14 +57,16 @@ renameCollection .. code-block:: javascript - db.source.renameCollection( "target" ) + db.source-namespace.renameCollection( "target" ) The shell helper :method:`renameCollection()` cannot be used to copy - and rename a collection across databases. + and rename a collection across databases. The helper + :method:`renameCollection()` + will prepend the database name to the specified ``target``. - :dbcommand:`renameCollection` operates within a collection - by changing the metadata - associated with a given collection. The duration of the command is + :method:`renameCollection` operates within a collection + by changing the metadata associated with a given collection. + The duration of the command is constant and not related to the size of the collection or the indexes; however, the operation will invalidate open cursors which will interrupt queries that are currently returning data. From b3189d6d222ebc94c9365aef64cd763da3e5fd05 Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Wed, 26 Sep 2012 11:19:49 -0400 Subject: [PATCH 4/6] Updates to command and method from @scotthernandez comments --- source/reference/command/renameCollection.txt | 42 +++++++++---------- .../method/db.collection.renameCollection.txt | 29 ++++++++++--- 2 files changed, 44 insertions(+), 27 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index d5337bed65f..61ac3311816 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -9,7 +9,7 @@ renameCollection The :dbcommand:`renameCollection` command is an administrative command which changes the name of an existing collection. If the ``target-namespace`` specifies a collection in a different database, the - ``source-namespace`` collection will be copied to the new database and then dropped. + ``source-namespace`` collection will be copied to the new database and then dropped. You must issue the :dbcommand:`renameCollection` command against the :term:`admin database` in the form: @@ -29,9 +29,8 @@ renameCollection Specifies the new namespace of the collection. - :param dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. - :type dropTarget: true or false - + :param boolean dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. + :exception 10026: Raised if the ``source`` namespace does not exist. @@ -45,34 +44,33 @@ renameCollection Raised if the ``target`` namespace is an invalid collection name. + You may safely use :dbcommand:`renameCollection` in production + environments. + .. warning:: :dbcommand:`renameCollection` will fail if `target` is the name of an existing collection and you do not specify ``dropTarget: true``. - The shell helper :method:`renameCollection()` provides a + .. warning:: + + You cannot use :dbcommand:`renameCollection` with + sharded collections. + + .. warning:: + + If :dbcommand:`renameCollection` is interrupted prior to completion, + the ``target`` collection and indexes will be left in an inconsistent + state requiring manual intervention to clean up. + + The shell helper :method:`db.collection.renameCollection()` provides a simpler interface to using this command within a database. The following is equivalent to the previous example: .. code-block:: javascript db.source-namespace.renameCollection( "target" ) + + - The shell helper :method:`renameCollection()` cannot be used to copy - and rename a collection across databases. The helper - :method:`renameCollection()` - will prepend the database name to the specified ``target``. - - :method:`renameCollection` operates within a collection - by changing the metadata associated with a given collection. - The duration of the command is - constant and not related to the size of the collection or the - indexes; however, the operation will invalidate open cursors which - will interrupt queries that are currently returning data. - - You may safely use :dbcommand:`renameCollection` in production - environments. - - .. warning:: You cannot use :dbcommand:`renameCollection` with - sharded collections. diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index a6be51119ea..5287636f101 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -4,10 +4,12 @@ db.collection.renameCollection() .. default-domain:: mongodb -.. method:: db.collection.renameCollection() +.. method:: db.collection.renameCollection( target [,dropTarget: true]) :param string name: Specifies the new name of the collection. Enclose the string in quotes. + + :param boolean dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. Call the :method:`db.collection.renameCollection()` method on a collection object, to rename a collection. Specify the new name of the @@ -20,9 +22,26 @@ db.collection.renameCollection() This method renames a collection named ``rrecord`` to ``record``. If the target name (i.e. ``record``) is the name of an existing collection, then the operation will fail. + + The :method:`db.collection.renameCollection()` method cannot be + used to move a collection across databases. + + The :method:`db.collection.renameCollection()` method operates + within a collection by changing the metadata associated with a + given collection. :method:`db.collection.renameCollection()` provides a wrapper around the - :term:`database command` ":dbcommand:`renameCollection`". - - .. warning:: You cannot use :method:`renameCollection() - ` with sharded collections. + :term:`database command` ":dbcommand:`renameCollection`". Please + refer to :dbcommand:`renameCollection` for further warnings and + messages. + + .. warning:: + + The :method:``db.collection.renameCollection()`` method and + :dbcommand:`renameCollection` command will invalidate open + cursors which will interrupt queries that are currently returning data. + + .. warning:: + + You cannot use :method:``db.collection.renameCollection()`` or + :dbcommand:``renameCollection`` with sharded collections. From b7478bc7eaca7609f58b5c9209864a1fc868d22f Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Wed, 26 Sep 2012 13:04:00 -0400 Subject: [PATCH 5/6] formatting cleanup of both command and method --- source/reference/command/renameCollection.txt | 2 +- .../method/db.collection.renameCollection.txt | 13 ++++++------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index 61ac3311816..38e05e4c44e 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -29,7 +29,7 @@ renameCollection Specifies the new namespace of the collection. - :param boolean dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. + :param boolean,optional dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. :exception 10026: diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index 5287636f101..f99bfb71624 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -4,12 +4,11 @@ db.collection.renameCollection() .. default-domain:: mongodb -.. method:: db.collection.renameCollection( target [,dropTarget: true]) +.. method:: db.collection.renameCollection() - :param string name: Specifies the new name of the - collection. Enclose the string in quotes. + :param string target: Specifies the new name of the collection. Enclose the string in quotes. - :param boolean dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. + :param boolean,optional dropTarget: If ``true``, :program:`mongod` will drop the `target` of :dbcommand:`renameCollection` prior to renaming the collection. Call the :method:`db.collection.renameCollection()` method on a collection object, to rename a collection. Specify the new name of the @@ -37,11 +36,11 @@ db.collection.renameCollection() .. warning:: - The :method:``db.collection.renameCollection()`` method and + The :method:`db.collection.renameCollection()` method and :dbcommand:`renameCollection` command will invalidate open cursors which will interrupt queries that are currently returning data. .. warning:: - You cannot use :method:``db.collection.renameCollection()`` or - :dbcommand:``renameCollection`` with sharded collections. + You cannot use :method:`db.collection.renameCollection()` or + :dbcommand:`renameCollection` with sharded collections. From 1071d77be18a11db65ad5e41ab2d41f35bb3e3ec Mon Sep 17 00:00:00 2001 From: Ed Costello Date: Mon, 1 Oct 2012 16:32:00 -0400 Subject: [PATCH 6/6] further warnings per @scotthernandez --- source/reference/command/renameCollection.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index 38e05e4c44e..5e55183ca18 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -52,17 +52,19 @@ renameCollection :dbcommand:`renameCollection` will fail if `target` is the name of an existing collection and you do not specify ``dropTarget: true``. - - .. warning:: You cannot use :dbcommand:`renameCollection` with sharded collections. - - .. warning:: If :dbcommand:`renameCollection` is interrupted prior to completion, the ``target`` collection and indexes will be left in an inconsistent state requiring manual intervention to clean up. + + A copy of a database across collections will impact performance for + the duration of the copy. + + You should not initiate :dbcommand:`renameCollection` while the + source database is being written to. The shell helper :method:`db.collection.renameCollection()` provides a simpler interface to using this command within a database.