- Reference >
mongo
Shell Methods >- Database Methods >
- db.copyDatabase()
db.copyDatabase()¶
On this page
Definition¶
-
db.
copyDatabase
(fromdb, todb, fromhost, username, password, mechanism)¶ Deprecated since version 4.0: MongoDB deprecates
copydb
and its helperdb.copyDatabase()
. For information on alternatives, see copydb and clone Commands.Copies a database either from one
mongod
instance to the currentmongod
instance or within the currentmongod
. Themongo
shell methoddb.copyDatabase()
wraps thecopydb
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 samemongod
instance.username
string Optional. The name of the user on the
fromhost
MongoDB instance. The user authenticates to thefromdb
.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 supportsMONGODB-CR
to authenticate to thefromhost
.
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 commandcloneCollection
db.cloneDatabase()
and the commandclone
db.copyDatabase()
and the commandcopydb
Destination¶
- Run
db.copyDatabase()
in theadmin
database of the destinationmongod
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 thedb.stats()
operation to check the size of the database on the sourcemongod
instance.
Authentication to Source mongod
Instance¶
If copying from another
mongod
instance (fromhost
) that enforcesaccess control
, then you must authenticate to thefromhost
instance by specifying theusername
,password
, and optionallymechanism
. The method does not transmit the password in plaintext.db.copyDatabase()
uses thefromdb
as the authentication database for the specified user.Changed in version 4.0:
db.copyDatabase()
only supports SCRAM to authenticate to thefromhost
.
For more information on required access and authentication, see Required Access.
Concurrency¶
db.copyDatabase()
andclone
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 amongos
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 thefromhost
.db.copyDatabase()
uses thefromdb
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.
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:
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 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: