OPTIONS

copydb

Definition

copydb

Copies a database from a remote host to the current host or copies a database to another database within the current host. 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. Hostname of the remote source mongod instance. Omit fromhost to copy from one database to another on the same server.
fromdb string Name of the source database.
todb string Name of the target databases.
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 username credentials on the fromhost MongoDB deployment.
nonce string Optional. A single use shared secret generated on the remote server, i.e. fromhost, using the copydbgetnonce command. See Authentication for details.
key string Optional. A hash of the password used for authentication. See Authentication for details.

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

Behavior

Be aware of the following properties of copydb:

  • copydb runs on the destination mongod instance, i.e. the host receiving the copied data.
  • If the destination mongod has authorization enabled, copydb must specify the credentials of a user present in the source database who has the privileges described in Required Access.
  • 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.
  • 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.

Required Access

Changed in version 2.6.

On systems running with authorization, the copydb command requires the following authorization on the target and source databases.

Source Database (fromdb)

Source is non-admin Database

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

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

If the source database is on a remote server, you also need the find action on the system.indexes and system.namespaces collections in the source database; e.g.

{ resource: { db: "mySourceDB", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "mySourceDB", collection: "system.namespaces" }, actions: [ "find" ] }

Source is admin Database

If the source database is the admin database, you must have privileges that specify find action 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" ] }
{ 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" ] }

If the source database is on a remote server, the you also need the find action on the system.indexes and system.namespaces collections in the admin database; e.g.

{ resource: { db: "admin", collection: "system.indexes" }, actions: [ "find" ] }
{ resource: { db: "admin", collection: "system.namespaces" }, actions: [ "find" ] }

Source Database is on a Remote Server

If copying from a remote server and the remote server has authentication enabled, you must authenticate to the remote host as a user with the proper authorization. See Authentication.

Target Database (todb)

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

Authentication

If copying from a remote server and the remote server has authentication enabled, then you must include a username, nonce, and key.

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.

The key is a hash generated as follows:

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

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.

Examples

Copy on the Same Host

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 Remote mongod Instances that Enforce Authentication

To copy from a remote host that enforces authentication, include the fromhost, username, nonce and key fields.

The following command copies the test database from a remote host example.net that runs with authorization to a new records database on the local mongod instance. Because the example.net has authorization enabled, the command includes the username, nonce and key fields:

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