This article is part of Robert Sheldon's continuing series on Mongo DB. To see all of the items in the series, click here.

The MongoDB Database Tools are a set of command-line utilities for working with MongoDB instances and their data. You can use the tools to carry out a variety of operations, such as importing or exporting data or creating archive files that you can restore to a MongoDB instance. The tools let you work with MongoDB standalone instances (version 4.2 or later) or with MongoDB Atlas deployments. You can download the tools for free from the MongoDB site, based on your specific operating system.

In this article, I provide you with an overview of the Database Tools and what it takes to install them. I then demonstrate how several of the tools work, providing examples of how to import and export data, as well as how to create data archives and restore data from those archives. My goal here is to introduce you to the tools and give you with a foundation for using them in day-to-day operations so you’ll be comfortable exploring them and working them in your MongoDB environments.

Note: For the examples in this article, I used the same MongoDB Atlas environment I used for the previous articles in this series. Refer to the first article for details about setting up these environments. The examples are based on the hr database and candidates collection. If you plan to try out these examples, the database and collection should not exist or, if they do exist, should not contain documents or schema validation rules. You’ll also need to download the candidates_in.json file from here.

Installing the MongoDB Database Tools

You can install the MongoDB Database Tools on Windows, macOS, and Linux. The exact process you use for installing the tools will depend on the operating system and installation type. For example, you can install the tools in Windows from either an .msi file or.zip file. In macOS, you can use Homebrew or install them from a .zip file.

The Database Tools are available for the following platforms:

You can download platform-specific installation packages from MongoDB Database Tools Downloads. For details about how to install the Database tools in your environment, refer to the Installation topic in the tools’ documentation. Again, the installation process depends on the OS platform and installation type, so be sure to review the information carefully.

In some cases, you might need to update the PATH environment variable on your system so you can easily access the tools from you system’s command-line interface (CLI). Otherwise, you’ll need to specify the entire pathname when using one of the tools.

After you install the tools, you should be able to use them immediately in your CLI. A simple way to check whether a tool is available is to verify its version. For this, you need only specify the tool’s name, followed by the --version argument, as in the following example:

The command checks the version of the mongoimport tool, which imports document data from a file into a collection. When you specify --version as the argument, the tool returns only version information, such as the following:

If the directory that contains the database tools is not included in the PATH variable, you must specify the entire pathname when calling the tools. For example, I saved a copy of the tools to the /Users/user1/mongo/ folder on my Mac computer and then ran the following command to verify the version:

When I was preparing for this article, I noticed some inconsistencies around tool versions. The current version is 100.11.0. On my Mac, I first used Homebrew to update the existing tools to the current version. However, Homebrew installed version 100.9.5, not 100.11.0.

To get around this, I downloaded the .zip file for macOS and installed the tools in a different folder. This time I got the current version. I also installed the tools in Windows, using the .msi file, and I again got the current version. When you install the tools on your system, be sure to verify the version.

I also noticed another version-related issue. As I already noted, the current version is 100.11.0. However, the documentation for some of the Database Tools specifically states that the information applies to version 100.10.0, while other documentation makes no reference to the version. In addition, the list of changelogs available for each version only goes up to version 100.10.0.

All that said, my impression is that the tools’ basic functionality does not appear to change significantly from one version to the next, at least based on what I’ve seen.

The MongoDB Database Tools

The MongoDB Database Tools provide a set of command-line utilities that you can use when working with a MongoDB standalone instance or with an Atlas deployment. The toolset includes the following utilities:

Now that you have an overview of the various tools, let’s look at a few of them in action, starting with how to import and export data.

Importing and exporting data files

For the first example, we’ll import the document data from the candidates_in.json file into the candidates collection in the hr database. At this point, you should have downloaded the file and saved it to a directory on your system. The file contains 10 documents that include details about individual candidates. For example, the first document describes a candidate named Drew:

Because you’ll be connecting to MongoDB Atlas, you’ll need to use an Atlas account when running your commands, so be sure to have that username and password handy.

To connect to Atlas, you must include a connection string in your commands that is specific to your Atlas cluster and account. I explained how to get the connection information in the first article in this series and in the previous article on MongoDB Shell. Basically, your connection string should be in the following format:

You need to provide the username and password for your account and the cluster information specific to your Atlas deployment, replacing the syntax placeholders as appropriate. For example, I use the following connection string in my commands (replacing <password> with the actual password):

In this case, the username is user1, and the cluster information for my Atlas deployment is clust1.cb0m704. You can get the cluster information for your deployment directly from Atas.

Notice that I’ve also tagged the name of the database onto the end of the connection string, after the forward slash. This saves me the trouble of having to pass in an additional argument in my command.

Now let’s incorporate the connection string into the following mongoimport command:

The command includes the following options:

When you run this command, you should receive a message indicating that 10 documents were successfully imported the collection.

You can just as easily export a collection’s documents as you can import them. For this, you can use the mongoexport tool. For example, the following command exports the newly added documents in the candidates collection to the candidates_out.json file:

The --uri , --collection , and --jsonArray options are the same as the mongoimport command. However, the mongoexport command includes the --out option, rather than the --file option.

The --out option specifies the full pathname of the export file that will be created when you run this command. On my system, I saved the file to the same directory I used earlier, /Users/user1/mongo/.

When you run this command, you should also receive a message indicating that the 10 documents were successfully exported to the candidates_out.json file.

Note that, for many options in a Database Tools command, you can reference the option in multiple ways. For example, the following mongoexport command carries out the same operation as the previous command:

In the case, the command does not specify --uri option name before connection string. It also uses -c instead of --collection and -o instead of --out. However, the command still exports the 10 documents just like before. You can find a description of all the options and their alternative naming in the documentation for each tool.

There might be times when you don’t want to include your connection information in the command itself because of concerns that it might be visible to other programs (especially with regards to the password).

One way you can reduce the risk of exposing the connection information is to add it to a configuration file, specifying the connection string in a YAML format. You can then call the configuration file from within your commands.

For example, suppose you create a configuration file named tools.conf and include the following uri instruction in the file:

After you create the file, you can then save it to a directory that you can access from your commands. On my system, I saved the file to the /Users/user1/mongo/ folder.

Once you’ve created the configuration file, you can include a --config option to your commands that points to the file, as in the following example:

When you run the command, you should get the same results as you would if you included the --uri option directly.

Importing and exporting binary files

The MongoDB Database Tools also include the mongodump utility, which lets you back up data to binary archive files. When using the tool, you have several options for storing the data. For example, you can use the following command to save the data in the candidates collection to a directory dump structure:

Most of the elements in this statement you’ve seen before when using the mongoexport tool. The only difference is that the pathname specified in the --out option adds the dump subdirectory, where the dump structure will be created. You can specify whatever directory works for you.

When you run this command, the utility creates the hr subdirectory within the dump directory to hold the collection data for the hr database. The utility also adds the candidates.bson file to the hr directory. The file contains the collection’s data in a binary format. In addition, the utility generates the candidates.metadata.json file, which stores metadata about the collection. The metadata is saved in a JSON format.

The mongoexport tool will create the same structure for each database and collection that you back up to the dump directory structure, so if you back up multiple databases or collections, they will be reflected in the directory hierarchy.

In some cases, you might want to save your data to an archive file, rather than to the dump directory structure. For this, you can use a command similar to the previous one, only this time, you should specify the --archive option, rather than the --out option, as in the following example:

The command saves the data in the candidates collection to the candidates.archive file.

When you create an archive file in this way, the data is not compressed. However, you can compress the data by including the --gzip option in your command and using the .gz file extension in the filename, as in the following example:

After you use mongodump to back up data, you can then use the mongorestore utility to restore it, regardless of the format used when backing up the data. For example, the following command restores the candidates collection from the dump directory structure:

First off, notice that the --uri option does not specify the database. This is not needed because the command now contains the --nsInclude option, which specifies the name of the database and collection (the namespace) to be restored. The namespace in this case is hr.candidates.

The use of this option is important because backups can contain multiple databases and multiple collections. The --nsInclude option lets you specify exactly what to include. It even lets you use wildcards to identify your target databases and collections.

When you restore data from the dump directory structure, you do not specify an option name (such as --archive) for the source directory. Instead, you simply include the directory path, which on my system is /Users/user1/mongo/dump/.

It is also possible to restore data to a database or collection with names different from the original database or collection. For example, the following command restores the original candidates collection in the hr database to the candidates2 collection in the hr2 database:

To restore data to a different database or collection, you need to include the --nsFrom and the --nsTo options in your command. The --nsFrom option specifies the original namespace, and the --nsTo option specifies the target namespace, which in this case is hr2.candidates2. In other words, the original data will be restored to the candidates2 collection in the hr2 database. If they do not exist, MongoDB will create them.

You can just as easily restore data from an archive file. For this, you need to include the --archive option, specifying the full pathname as the argument’s value, as in the following example:

The command now uses the --nsTo option to specify hr3.candidates3 as the target namespace.

The next command is similar to the preceding one, except that it specifies hr4.candidates4 as the new namespace and it restores data from the compressed archive file:

Notice that the command now includes the --gzip option, just like you saw when you used the mongodump utility to create the file.

Getting started with the MongoDB Database Tools

The four utilities I’ve demonstrated here—mongoimport, mongoexport, mongodump, and mongorestore—can be very useful when working with MongoDB data. However, I’ve only skimmed the surface on how to use these tools. There is much more to each one, particularly in terms of their supported options.

The Database Tools also include several utilities that I did not cover here, although they too can be extremely useful. Be sure to check out the Database Tools documentation to learn more about each one. It’s worth investing the time necessary to install them and learn how they work so you’re ready to use them when the need arises.