> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# renameCollection (database command)

## Definition

Changes the name of an existing collection. Specify collection names to `renameCollection` in the form of a complete [namespace](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-namespace) (`<database>.<collection>`).

**Tip:**

In [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh), this command can also be run through the [`renameCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) helper method.

Helper methods are convenient for [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#std-program-mongosh) users, but they may not return the same level of information as database commands.  In cases where the convenience is not needed or the additional return fields are required, use the database command.

Issue the `renameCollection` command against the [admin database.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-admin-database)

## Compatibility

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

- [MongoDB Atlas](https://www.mongodb.com/docs/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.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

### Stable API Support

Starting in MongoDB 8.1, `renameCollection` is included in [Stable API](https://www.mongodb.com/docs/manual/reference/stable-api.md#std-label-stable-api) V1. To use `renameCollection` in the Stable API, you must connect your driver to a deployment that is running MongoDB 8.1 or greater.

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
   {
     renameCollection: "<source_namespace>",
     to: "<target_namespace>",
     dropTarget: <true|false>,
     writeConcern: <document>,
     comment: <any>
   }
)
```

## Command Fields

The command contains the following fields:

| Field | Type | Description |
| --- | --- | --- |
| `renameCollection` | string | The [namespace](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-namespace) of the collection to rename. The namespace is a combination of the database name and the name of the collection. |
| `to` | string | The new namespace of the collection. If the new namespace specifies a different database, the `renameCollection` command copies the collection to the new database and drops the source collection. See [Naming Restrictions.](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-restrictions-on-db-names) |
| `dropTarget` | boolean | Optional. If `true`, [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) will drop the `target` of `renameCollection` prior to renaming the collection. The default value is `false`. |
| `writeConcern` | document | Optional. A document that expresses the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) for the operation. Omit to use the default write concern. When issued on a sharded cluster, [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) converts the [write concern](https://www.mongodb.com/docs/manual/reference/write-concern.md#std-label-write-concern) of the [`renameCollection`](https://www.mongodb.com/docs/manual/reference/command/renamecollection.md#mongodb-dbcommand-dbcmd.renameCollection) command and its helper [`db.collection.renameCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) to [`"majority"`.](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-majority-) |
| `comment` | any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: [mongod log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentop.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). |

## Behavior

### Sharded Collections

You can use the `renameCollection` command to change the name of a sharded collection. The target database must be the same as the source database. This operation preserves all indexes.

### Unsharded Collections

You can use `renameCollection` to rename an unsharded collection in a sharded cluster as long as the source and target databases have the same primary shard. If you run `renameCollection` to rename a collection in the same database, the operation preserves collection data and indexes. If you run `renameCollection` against a different database, the operation rewrites collection data and indexes to new files.

### Time Series Collections

Starting in MongoDB 9.0, you can rename time series collections with [`renameCollection`.](https://www.mongodb.com/docs/manual/reference/command/renamecollection.md#mongodb-dbcommand-dbcmd.renameCollection)

### Existing Target Collection

`renameCollection` fails if `target` is the name of an existing collection *and* you do not specify `dropTarget: true`.

### In-Progress Index Builds

The rename operation fails with a `BackgroundOperationInProgressForNamespace` error if an index build is in progress on the source collection. The operation also fails if an index build is in progress on the target collection and you specify `dropTarget: true`.

To rename the collection, wait for the index build to finish and then retry the operation. To check for in-progress index builds, use the [`db.currentOp()`](https://www.mongodb.com/docs/manual/reference/method/db.currentop.md#mongodb-method-db.currentOp) method.

### Performance

`renameCollection` has different performance implications depending on the target [namespace.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-namespace)

If the target database is the same as the source database, `renameCollection` simply changes the namespace. This is a quick operation.

If the target database differs from the source database, `renameCollection` copies all documents from the source collection to the target collection. Depending on the size of the collection, this may take longer to complete.

### 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.](https://www.mongodb.com/docs/manual/faq/concurrency.md)

### Resource Locking in Replica Sets

When you rename a collection within the same database, `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.

Starting in MongoDB 9.0, when you rename a collection between different databases, `renameCollection` obtains an exclusive lock on the source and target collections for the duration of the operation. [DDL operations](https://www.mongodb.com/docs/manual/reference/ddl-operations.md#std-label-ddl-operations) and writes on the source and target collections must wait until `renameCollection` completes. Most read operations use [lock-free reads](https://www.mongodb.com/docs/manual/faq/concurrency.md#std-label-faq-concurrency-lock-free-read-operations) and are not blocked.

In versions earlier than 9.0, during a cross-database rename, `renameCollection` held only a shared (S) lock on the source collection during the copy phase, and released the lock before completing the rename.

The locking change affects replica sets only. Sharded clusters already lock both collections for the duration of the rename, as described earlier on this page.

For more information on locking in MongoDB, see [FAQ: Concurrency.](https://www.mongodb.com/docs/manual/faq/concurrency.md)

### `local` Database

- You cannot rename a collection from a replicated database to the `local` database, which is not replicated.

- You cannot rename a collection from the `local` database, which is not replicated, to a replicated database.

### Open Cursors and Change Streams

**Warning:**

The [`db.collection.renameCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) method and [`renameCollection`](https://www.mongodb.com/docs/manual/reference/command/renamecollection.md#mongodb-dbcommand-dbcmd.renameCollection) command invalidate open cursors. This creates an [invalidate event](https://www.mongodb.com/docs/manual/reference/change-events/invalidate.md#std-label-change-event-invalidate) for any existing [change streams](https://www.mongodb.com/docs/manual/changestreams.md#std-label-changeStreams) opened on the source or target collection, and also interrupts queries that are currently returning data from the renamed collection.

### Interaction with `mongodump`

A [`mongodump`](https://www.mongodb.com/docs/database-tools/mongodump.md#mongodb-binary-bin.mongodump) started with [`--oplog`](https://www.mongodb.com/docs/database-tools/mongodump.md#std-option-mongodump.--oplog) fails if a client issues the `renameCollection` command during the dump process. See [`mongodump.--oplog`](https://www.mongodb.com/docs/database-tools/mongodump.md#std-option-mongodump.--oplog) for more information.

## Example

The following example renames a collection named `orders` in the `test` database to `orders2014` in the `test` database.

```javascript
db.adminCommand( { renameCollection: "test.orders", to: "test.orders2014" } )
```

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) provides the [`db.collection.renameCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.renamecollection.md#mongodb-method-db.collection.renameCollection) helper for the command to rename collections within the *same* database. The following is equivalent to the previous example:

```javascript
use test
db.orders.renameCollection( "orders2014" )
```