copydb¶

On this page

Definition
Behavior
Required Access
Generate nonce and key
Examples

Definition¶

copydb¶

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:

{ copydb: 1,
  fromhost: <hostname>,
  fromdb: <database>,
  todb: <database>,
  slaveOk: <bool>,
  username: <username>,
  nonce: <nonce>,
  key: <key> }

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.
`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.
`nonce`	string	Optional. A single use shared secret generated on the remote server, i.e. `fromhost`, using the `copydbgetnonce` command. For more information, Generate nonce and key.
`key`	string	Optional. A hash of the password used for authentication. For more information, Generate nonce and key.

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

When authenticating to the fromhost instance, copydb uses MONGODB-CR mechanism to authenticate the fromhost user. To authenticate users with SCRAM-SHA-1 mechanism, use the db.copyDatabase() method.

Behavior¶

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.
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¶

If copying from another mongod instance (fromhost) that enforces access control, then you must authenticate to the fromhost instance by specifying the username, nonce, and key.

When authenticating to the fromhost instance, copydb uses the fromdb as the authentication database for the specified user.
When authenticating to the fromhost instance, copydb uses MONGODB-CR mechanism to authenticate the fromhost user. To authenticate users with SCRAM-SHA-1 mechanism, use the db.copyDatabase() method.

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

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.

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¶

Changed in version 2.6.

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

If copying from another mongod instance (fromhost) that enforces access control, then you must authenticate to the fromhost instance by specifying the username, nonce, and key.

When authenticating to the fromhost instance, copydb uses the fromdb as the authentication database for the specified user.

When authenticating to the fromhost instance, copydb uses MONGODB-CR mechanism to authenticate the fromhost user. To authenticate users with SCRAM-SHA-1 mechanism, use the db.copyDatabase() method.

Source Database (`fromdb`)¶

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.

{ 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:

{ 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:

{ 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:

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

Generate `nonce` and `key`¶

If copying from another mongod instance that enforces access control, then you must include a username, nonce, and key to authenticate to that instance as a user with proper access.

Tip

The db.copyDatabase() handles the generation of the nonce and key.

`nonce`¶

The nonce is a one-time password that you request from the remote server using the copydbgetnonce command, as in the following:

use admin
mynonce = db.runCommand( { copydbgetnonce : 1, fromhost: <hostname> } ).nonce

If running the copydbgetnonce command directly on the remote host, you can omit the fromhost field in the copydbgetnonce command.

`key`¶

The key is a hash generated as follows:

hex_md5(mynonce + username + hex_md5(username + ":mongo:" + password))

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:

use admin
db.runCommand({
   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:

use admin
db.runCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records",
   fromhost: "example.net"
})

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

If copying from another mongod instance (fromhost) that enforces access control, then you must authenticate to the fromhost instance by specifying the username, nonce, and key.

When authenticating to the fromhost instance, copydb uses the fromdb as the authentication database for the specified user.

Note

When authenticating to the fromhost instance, copydb uses MONGODB-CR mechanism to authenticate the fromhost user. To authenticate users with SCRAM-SHA-1 mechanism, use the db.copyDatabase() method.

The following command copies the test database from a mongod instance that runs on the remote host example.net and enforces access control:

use admin
db.runCommand({
   copydb: 1,
   fromdb: "test",
   todb: "records",
   fromhost: "example.net",
   username: "reportingAdmin",
   nonce: "<nonce>",
   key: "<passwordhash>"
})

copydb¶

Definition¶

Behavior¶

Destination¶

Authentication to Source mongod Instance¶

Concurrency¶

Replica Sets¶

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¶

Generate nonce and key¶

nonce¶

key¶

Examples¶

Copy from the Same mongod Instance¶

Copy from a Remote Host to the Current Host¶

Copy Databases 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¶

Generate `nonce` and `key`¶

`nonce`¶

`key`¶

Copy from the Same `mongod` Instance¶

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