db.copyDatabase()¶

On this page

Definition
Behavior
Required Access
Example

Definition¶

db.copyDatabase(fromdb, todb, fromhost, username, password, mechanism)¶

Deprecated since version 4.0: MongoDB deprecates copydb and its helper db.copyDatabase(). For information on alternatives, see copydb and clone Commands.

Copies a database either from one mongod instance to the current mongod instance or within the current mongod. The mongo shell method db.copyDatabase() wraps the copydb command and takes the following arguments:

Parameter	Type	Description
`fromdb`	string	Name of the source database.
`todb`	string	Name of the target database.
`fromhost`	string	Optional. The hostname of the source `mongod` instance. Omit to copy databases within the same `mongod` instance.
`username`	string	Optional. The name of the user on the `fromhost` MongoDB instance. The user authenticates to the `fromdb`. For more information, see Authentication to Source mongod Instance.
`password`	string	Optional. The password on the `fromhost` for authentication. The method does not transmit the password in plaintext. For more information, see Authentication to Source mongod Instance.
`mechanism`	string	Optional. The authentication mechanism on the `fromhost`. The `fromhost` credentials must use SCRAM-SHA-1. Changed in version 4.0: `copyDatabase()` no longer supports `MONGODB-CR` to authenticate to the `fromhost`.

Behavior¶

Feature Compatibility Version¶

You cannot copy data between a MongoDB 4.0 mongod instance with featureCompatibilityVersion (FCV) 4.0 and a MongoDB version 3.6 mongod instance.

Note

You cannot copy data between a MongoDB 4.0 mongod instance (regardless of the FCV value) and a MongoDB 3.4 and earlier mongod instance.

For example:

Instance 1	Instance 2
Version 4.0 `mongod` with FCV 4.0	Version 4.0 `mongod` with FCV 4.0	Can copy data.
Version 4.0 `mongod` with FCV 4.0	Version 4.0 `mongod` with FCV 3.6	Can copy data.
Version 4.0 `mongod` with FCV 4.0	Version 3.6 `mongod` with FCV 3.6	Cannot copy data. Instance 2 must be a MongoDB version 4.0
Version 4.0 `mongod` with FCV 3.6	Version 3.6 `mongod` with FCV 3.6	Can copy data.
Version 4.0 `mongod` with FCV 3.6	Version 3.6 `mongod` with FCV 3.4	Can copy data.

In general, if the mongod instance has its featureCompatibilityVersion (FCV) set to its MongoDB version, you cannot copy data between that instance and a mongod instance of an earlier MongoDB version.

Operations that copy data include:

db.cloneCollection() and the command cloneCollection
db.cloneDatabase() and the command clone
db.copyDatabase() and the command copydb

Destination¶

Run db.copyDatabase() in the admin database of the destination mongod instance, i.e. the instance receiving the copied data.
db.copyDatabase() creates the target database if it does not exist.
If the target database exists and no collection from the source database exists in the target database, db.copyDatabase() copies the collections from the source database to the target database. If any collection from the source database exists in the target database, db.copyDatabase() errors out and does not copy any remaining collections from the source database.
db.copyDatabase() requires enough free disk space on the host instance for the copied database. Use the db.stats() operation to check the size of the database on the source mongod instance.

Authentication to Source `mongod` Instance¶

If copying from another mongod instance (fromhost) that enforces access control, then you must authenticate to the fromhost instance by specifying the username, password, and optionally mechanism. The method does not transmit the password in plaintext.
db.copyDatabase() uses the fromdb as the authentication database for the specified user.
Changed in version 4.0: db.copyDatabase() only supports SCRAM to authenticate to the fromhost.

For more information on required access and authentication, see Required Access.

Concurrency¶

db.copyDatabase() and clone do not produce point-in-time snapshots of the source database. Write traffic to the source or destination database during the copy process will result in divergent data sets.
db.copyDatabase() does not lock the destination server during its operation, so the copy will occasionally yield to allow other operations to complete.

Indexes¶

MongoDB performs foreground builds of indexes on databases copied via db.copyDatabase(). Foreground index builds lock the database and prevent all other operations on that database until the foreground build completes. There may also be a performance impact on other databases while the indexes build.

You can keep track of ongoing index creation operations with the db.currentOp() command.

Sharded Clusters¶

Do not use db.copyDatabase() from a mongos instance.
Do not use db.copyDatabase() to copy databases that contain sharded collections.

Required Access¶

Source Database (`fromdb`)¶

If the mongod instance of the source database (fromdb) enforces access control, you must have proper authorization for the source database.

If you are copying from a different mongod instance that enforces access control, you must authenticate to the fromhost instance as a user with the appropriate authorization:

Changed in version 4.0: db.copyDatabase() only supports SCRAM to authenticate to the fromhost.
db.copyDatabase() uses the fromdb as the authentication database for the specified user.

Source is non-`admin` Database¶

Changed in version 3.0.

If the source database is a non-admin database, you must have privileges that specify find, listCollections, and listIndexes actions on the source database, and find action on the system.js collection in the source database.

copy

{ resource: { db: "mySourceDB", collection: "" }, actions: [ "find", "listCollections", "listIndexes" ] },
{ resource: { db: "mySourceDB", collection: "system.js" }, actions: [ "find" ] },

Source is `admin` Database¶

Changed in version 3.0.

If the source database is the admin database, you must have privileges that specify find, listCollections, and listIndexes actions on the admin database, and find action on the system.js, system.users, system.roles, and system.version collections in the admin database. For example:

copy

{ resource: { db: "admin", collection: "" }, actions: [ "find",  "listCollections", "listIndexes" ] },
{ resource: { db: "admin", collection: "system.js" }, actions: [ "find" ] },
{ resource: { db: "admin", collection: "system.users" }, actions: [ "find" ] },
{ resource: { db: "admin", collection: "system.roles" }, actions: [ "find" ] },
{ resource: { db: "admin", collection: "system.version" }, actions: [ "find" ] }

Target Database (`todb`)¶

If the mongod instance of the target database (todb) enforces access control, you must have proper authorization for the target database.

Copy from non-`admin` Database¶

If the source database is not the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js collection in the target database. For example:

copy

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] },
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] }

Copy from `admin` Database¶

If the source database is the admin database, you must have privileges that specify insert and createIndex actions on the target database, and insert action on the system.js, system.users, system.roles, and system.version collections in the target database. For example:

copy

{ resource: { db: "myTargetDB", collection: "" }, actions: [ "insert", "createIndex" ] },
{ resource: { db: "myTargetDB", collection: "system.js" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.users" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.roles" }, actions: [ "insert" ] },
{ resource: { db: "myTargetDB", collection: "system.version" }, actions: [ "insert" ] }

Example¶

Copy from the Same `mongod` Instance¶

To copy within the same mongod instance, omit the fromhost.

The following operation copies a database named records into a database named archive_records:

copy

db.copyDatabase('records', 'archive_records')

Copy Database from a `mongod` Instances that Enforce Authentication¶

The following operation copies a database named reporting from a mongod instance that runs on example.net and enforces access control and uses SCRAM-SHA-1 authentication mechanism.

copy

 db.copyDatabase(
   "reporting",       // from database
   "reporting_copy",  // to database
   "example.net",     // from host
   "reportUser",      // user on from database
   "abc123",          // password for user
   "SCRAM-SHA-1"      // mechanism for user
)

db.copyDatabase()¶

Definition¶

Behavior¶

Feature Compatibility Version¶

Destination¶

Authentication to Source mongod Instance¶

Concurrency¶

Indexes¶

Sharded Clusters¶

Required Access¶

Source Database (fromdb)¶

Source is non-admin Database¶

Source is admin Database¶

Target Database (todb)¶

Copy from non-admin Database¶

Copy from admin Database¶

Example¶

Copy from the Same mongod Instance¶

Copy Database from a mongod Instances that Enforce Authentication¶

Authentication to Source `mongod` Instance¶

Source Database (`fromdb`)¶

Source is non-`admin` Database¶

Source is `admin` Database¶

Target Database (`todb`)¶

Copy from non-`admin` Database¶

Copy from `admin` Database¶

Copy from the Same `mongod` Instance¶

Copy Database from a `mongod` Instances that Enforce Authentication¶