Navigation
This version of the documentation is archived and no longer supported.

copydb

On this page

Definition

copydb

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. Run copydb in the admin database of the destination server with the following syntax:

copy 
{ copydb: 1,
  fromhost: <hostname>,
  fromdb: <database>,
  todb: <database>,
  slaveOk: <bool>,
  writeConcern: <document>,
  bypassDocumentValidation: <boolean> }

copydb accepts the following options:

Field Type Description
fromhost string Optional. The hostname of the source mongod instance. Omit to copy databases within the same mongod instance.
fromdb string Name of the source database.
todb string Name of the target database.
slaveOk boolean Optional. Set slaveOK to true to allow copydb to copy data from secondary members as well as the primary. fromhost must also be set.
writeConcern document Optional. A document that expresses the write concern for the operation. Omit to use the default write concern.
bypassDocumentValidation boolean

Optional. Enables copydb to bypass document validation during the operation. This lets you insert documents that do not meet the validation requirements.

New in version 3.2.

The mongo shell provides the db.copyDatabase() wrapper for the copydb command.

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:

Destination

  • Run copydb in the admin database of the destination mongod instance, i.e. the instance receiving the copied data.
  • copydb 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, copydb copies the collections from the source database to the target database. If any collection from the source database exists in the target database, copydb errors out and does not copy any remaining collections from the source database.
  • copydb 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

To copy from another mongod instance (fromhost) that enforces access control, then you must use the mongo shell method db.copyDatabase().

Concurrency

  • copydb 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.
  • copydb 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 copydb. 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.

Replica Sets

With read preference configured to set the slaveOk option to true, you may run copydb on a secondary member of a replica set.

Sharded Clusters

  • Do not use copydb from a mongos instance.
  • Do not use copydb to copy databases that contain sharded collections.

Required Access

Source Database (fromdb)

If you are copying within the same mongod instance that enforces access control, you must have the appropriate authorization.

If you are copying from a different mongod instance that enforces access control, see db.copyDatabase().

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" ] }

Examples

Copy from the Same mongod Instance

To copy from the same host, omit the fromhost field.

The following command copies the test database to a new records database on the current mongod instance:

copy 
db.adminCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records"
})

Copy from a Remote Host to the Current Host

To copy from a remote host, include the fromhost field.

The following command copies the test database from the remote host example.net to a new records database on the current mongod instance:

copy 
db.adminCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records",
   fromhost: "example.net"
})

To copy from another mongod instance (fromhost) that enforces access control, then you must use the mongo shell method db.copyDatabase().

See also

←   convertToCapped create  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.