- Importantmongosh Method
This is a
mongoshmethod. This is not the documentation for
Node.jsor other programming language specific driver methods.
For the legacy
mongoshell documentation, refer to the documentation for the corresponding MongoDB Server release:
For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
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.
The method has the following limitations:
db.collection.renameCollection()cannot move a collection between databases. Use
renameCollectionfor these rename operations.
db.collection.renameCollection()is not supported on sharded collections.
- 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¶
Changed in version 4.2.
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. Prior to MongoDB
4.2, renaming a collection within the same database with
renameCollection required obtaining an exclusive database
db.collection.renameCollection() method on a
collection object. For example:
This operation will rename the
rrecord collection to
the target name (i.e.
record) is the name of an existing collection,
then the operation will fail.