Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
mongosh Methods
/
Collections

db.collection.renameCollection()

On this page

  • Definition
  • Compatibility
  • Behavior
  • Example

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:

C#Java SyncNode.jsPyMongoCC++GoJava RSKotlin CoroutineKotlin SyncPHPMongoidRustScala

Definition

db.collection.renameCollection(target, dropTarget)

Renames a collection. Provides a wrapper for the renameCollection database command.

Parameter
Type
Description

target

string

The new name of the collection. Enclose the string in quotes. See Naming Restrictions.

dropTarget

boolean

Optional. If true, mongod drops the target of renameCollection prior to renaming the collection. The default value is false.

Compatibility

This method is available in deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Note

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

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 invalidate open cursors. This creates an invalidate event for any existing change streams opened on the source or target collection, and also interrupts queries that are currently returning data from the renamed collection.

  • The method has the following limitations:

    • db.collection.renameCollection() cannot move a collection between databases. Use renameCollection for 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 IllegalOperation error 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.

Back

db.collection.remove

Next

db.collection.replaceOne