MongoDB with drivers
This page documents a mongosh method. To see the equivalent
method in a MongoDB driver, see the corresponding page for your
programming language:
Definition
db.collection.renameCollection(target, dropTarget)Renames a collection. Provides a wrapper for the
renameCollectiondatabase command.ParameterTypeDescriptiontargetstring
The new name of the collection. Enclose the string in quotes. See Naming Restrictions.
dropTargetboolean
Optional. If
true,mongoddrops thetargetofrenameCollectionprior to renaming the collection. The default value isfalse.
Behavior
The db.collection.renameCollection() method operates within a
collection by changing the metadata associated with a given collection.
Refer to the documentation renameCollection for additional
warnings and messages.
Warning
The db.collection.renameCollection() method and
renameCollection command will invalidate open cursors
which interrupts queries that are currently returning data.
For Change Streams, the
db.collection.renameCollection() method and
renameCollection command create an
invalidate Event for any existing
Change Streams opened on the source or target collection.
The method has the following limitations:
db.collection.renameCollection()cannot move a collection between databases. UserenameCollectionfor these rename operations.You cannot rename views.
db.collection.renameCollection()is not supported on time series collections.You cannot rename a collection to itself. If you try to rename a collection to itself an
IllegalOperationerror is thrown.
Resource Locking in Sharded Clusters
Changed in version 5.0.
When renaming a sharded or unsharded collection in a sharded cluster, the source and target collections are exclusively locked on every shard. Subsequent operations on the source and target collections must wait until the rename operation completes.
For more information on locking in MongoDB, see FAQ: Concurrency.
Resource Locking in Replica Sets
renameCollection() obtains an exclusive lock on
the source and target collections for the duration of the operation. All
subsequent operations on the collections must wait until
renameCollection() completes.
Interaction with mongodump
A mongodump started with
--oplog fails if a client issues
db.collection.renameCollection() during the dump process. See
mongodump.--oplog for more information.
Example
Call the db.collection.renameCollection() method on a
collection object. For example:
db.rrecord.renameCollection("record")
This operation will rename the rrecord collection to record. If
the target name (i.e. record) is the name of an existing collection,
then the operation will fail.