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

db.copyDatabase()

Definition

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

Copies a database from a remote host to the current host or copies a database to another database within the current host. db.copyDatabase() wraps the copydb command and takes the following arguments:

Parameter Type Description
fromdb string The name of the source database.
todb string The name of the destination database.
fromhost string Optional. The name of the source database host. Omit the hostname to copy from one database to another on the same server.
username string Optional. The username credentials on the fromhost for authentication and authorization.
password string Optional. The password on the fromhost for authentication and authorization. The method does not transmit the password in plaintext.

Behavior

Be aware of the following properties of db.copyDatabase():

  • db.copyDatabase() runs on the destination mongod instance, i.e. the host receiving the copied data.
  • If the destination mongod has authorization enabled, db.copyDatabase() must specify the credentials of a user present in the source database who has the privileges described in Required Access.
  • db.copyDatabase() creates the target database if it does not exist.
  • 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.
  • 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.

Required Access

Changed in version 2.6.

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 the <username> and <password>. The method does not transmit the password in plaintext.

Example

To copy a database named records into a database named archive_records, use the following invocation of db.copyDatabase():

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

See also

clone