How to migrate your MongoDB database instance with mongodump, mongorestore, tar and scp

Migration of MongoDB database is part and parcel of DevOps, especially when you are running your own projects.

MongoDB provides us with two utilities for performing database migration - mongodump and mongorestore.

A simple MongoDB database migration can be performed in 5 steps:

  1. Use the mongodump command to export the data of a MongoDB database instance as files in the source server's filesystem.
  2. Use the tar command to compress the exported files as a single .tar.gz file in the source server's filesystem.
  3. Use the scp command to send the .tar.gz file from the source server to the destination server.
  4. Use the tar command to decompress the .tar.gz file at the destination server.
  5. Use the mongorestore to import the extracted files into the destination MongoDB database.

This post discusses how you can perform MongoDB database migration with utilities provided by MongoDB and most Linux servers.

Exporting data from MongoDB server with mongodump

The way you run mongodump depends on whether access control is turned on for your MongoDB server.

Exporting data from MongoDB server without access control

When you have a MongoDB server listening at the default port of localhost, you run the following command to export the data from the MongoDB database instance, a_database, onto the server's file system.

mongodump --db a_database

After the command completes, you will find a directory named as dump in the current working directory. Inside the dump directory, you will find the a_database directory. And inside the a_database directory, you will find .bson and .json files that describe the contents of the MongoDB database instance that you are exporting data from.

Exporting data from MongoDB server with access control

Suppose you have a MongoDB user account with the username auser and password apassword created inside the database admin, you run the following command to extract the data from the database instance a_database from the MongoDB server listening at the default port of localhost: 

mongodump --username auser --password apassword \
--authenticationDatabase admin --db a_database

As with the case of exporting data from a MongoDB server without access control, you will find similar output in the current working directory when the mongodump command completes.

Make sure that the user that is able to read from the database, if not you will encounter the following error: 

Failed: error connecting to db server: server returned error on SASL authentication step: Authentication failed.

Using the tar command to compress the exported files as a single .tar.gz file in the source server's filesystem

When we compress all the contents inside the dump directory into a single .tar.gz file, we can transfer the exported data over to the destination server's file system easily. You can use the tar command to compress all the contents inside the dump directory into a single .tar.gz file:

tar -czvf dump.tar.gz dump

When the command completes, you will be able to see the dump.tar.gz file in your current working directory. The dump.tar.gz file will contain the dump directory along with its subdirectories and files.

Using the scp command to send the .tar.gz into the destination server

If there is a SSH server running at your destination server, you can use the scp command to send the dump.tar.gz file from your current working directory to the destination server. Suppose your destination server is reachable by the domain example.com, has a user account with username root and has a /var/receiving directory, you can run the following command to send your dump.tar.gz file to the destination server:

scp dump.tar.gz root@example.com:/var/receiving/dump.tar.gz

Using the tar command to decompress the single .tar.gz file back into output files generated by mongodump

Once the file transfer is done, you can use the ssh command to get into your destination server to extract the contents of dump.tar.gz:

ssh root@example.com

Once you had logged into the destination server, you can run the following commands to extract the dump directory from dump.tar.gz:

cd /var/receiving
tar -zxvf dump.tar.gz

After the command completes, you will find the output files generated by mongodump at the /var/receiving folder.

Importing data into MongoDB server with mongorestore

As with the case of exporting data from MongoDB server, the way you run mongorestore depends on whether access control is turned on for your MongoDB.

Importing data into MongoDB server with no access control

When you have a MongoDB server listening at the default port of localhost, you run the following command to import the data from the dump directory into the MongoDB database instance, a_database:

mongorestore --drop --db a_database dump/a_database

This command will drop all existing collections inside the MongoDB database instance a_database before populating the contents from dump/a_database. When the command completes, the MongoDB database instance at the destination server will contain the migrated data from the source server.

Importing data into MongoDB server with access control

Suppose you have a MongoDB user account with the username auser and password apassword created inside the database admin, you run the following command to import the data from dump/a_database into the MongoDB server listening at the default port of localhost: 

mongorestore --drop --db a_database --username auser 
\ --password apassword --authenticationDatabase admin dump/a_database

Similar to the case of importing data into the MongoDB server without access control, the command will drop all existing collections inside the MongoDB database instance a_database before populating the contents from dump/a_database. After the command completes, the MongoDB database instance at the destination server will contain the migrated data from the source server.

Make sure that the user that is able to write to the database, if not you will encounter the following error: 

Failed: error connecting to db server: server returned error on SASL authentication step: Authentication failed.

About Clivant

Clivant a.k.a Chai Heng enjoys composing software and building systems to serve people. He owns techcoil.com and hopes that whatever he had written and built so far had benefited people. All views expressed belongs to him and are not representative of the company that he works/worked for.