How To Use the MongoDB Shell

The author selected the Open Internet/Free Speech Fund to receive a donation as part of the Write for DOnations program.

Introduction

Database systems such as MongoDB are typically used with an external application that connects to the database server and performs operations, such as reading and processing the data or writing new entries. In cases like this, you are not interacting with the database server directly. To perform administrative tasks on the database or execute ad-hoc database queries yourself, though, direct access might be needed.

That’s where the MongoDB shell comes in. The MongoDB shell is an interactive console you can use to connect to the database server and execute commands on it, allowing you to perform administrative tasks and read, write, or manipulate data directly. The MongoDB shell enables you to connect to the database from a command line prompt and interactively work with it from a terminal window. It also allows you to run external scripts to perform repeated tasks with greater convenience.

In this tutorial, you’ll use the MongoDB shell to connect to a MongoDB database and query the database interactively. You will also use the built-in help system and autocompletion features included in the shell.

Prerequisites

To follow this tutorial, you will need:

• A server with a regular, non-root user with sudo privileges and a firewall configured with UFW. This tutorial was validated using a server running Ubuntu 20.04, and you can prepare your server by following this initial server setup tutorial for Ubuntu 20.04.
• MongoDB installed on your server. To set this up, follow our tutorial on How to Install MongoDB on Ubuntu 20.04.
• Your server’s MongoDB instance secured by enabling authentication and creating an administrative user. To secure MongoDB like this, follow our tutorial on How To Secure MongoDB on Ubuntu 20.04.

Step 1 — Connecting to the MongoDB Server

To open up the MongoDB shell, run the mongo command from your server prompt. By default, the mongo command opens a shell connected to a locally-installed MongoDB instance running on port 27017.

Try running the mongo command with no additional parameters:

mongo

This will print a welcome message with some information about the server the shell is connected to, as well as what version of MongoDB is installed. The following example indicates that the MongoDB server is running on 127.0.0.1 (a loopback interface representing localhost) on MongoDB’s default port (27017) and running version 4.4.6.

Output
MongoDB shell version v4.4.6
connecting to: mongodb://127.0.0.1:27017/?compressors=disabled&gssapiServiceName=mongodb
Implicit session: session { "id" : UUID("b9a48dc7-e821-4b09-a753-429eedf072c5") }
MongoDB server version: 4.4.6

Below this message, the MongoDB shell’s prompt — indicated by a greater-than sign — will appear:

Try listing all the databases available on the server. Type show dbs after the shell prompt and press ENTER:

show dbs

Assuming you followed the prerequisite tutorial on How To Secure MongoDB, this command won’t return any output. The reason for this is that, even though the MongoDB server is running and the shell was able to connect to it, you didn’t provide any authentication information. Because of this, you have no access rights to work with any of the server databases and the show dbs command returns nothing.

Exit the shell by typing:

exit

The Mongo shell will print a brief goodbye message and return you to the system shell:

Output
bye

Now try reconnecting the MongoDB shell to the database server, but this time provide a username and password to properly authenticate into your MongoDB instance. To do so, you’ll need to provide additional command line parameters, as in the following example:

mongo -u AdminSammy -p --authenticationDatabase admin

This command consists of several parts:

• -u: this flag sets the username used to authenticate into the MongoDB server. This example specifies the administrative user created in the prerequisite MongoDB security tutorial, AdminSammy. For this tutorial, you can replace this with your own administrative user’s username if different.
• -p: this flag tells the MongoDB shell to use a password when connecting to the database. You will be prompted to provide a password in the terminal window after you press ENTER.
• --authenticationDatabase: this option specifies the authentication database of the user you’re logging in as. Typically, administrative accounts are managed in the admin database, but if your user’s authentication database is different, enter that database in place of admin.

Enter the password set during installation and you’ll once again get access to the shell.

Now try executing the show dbs command once again:

show dbs

This time, the command will return a list of all available databases in the system:

Output
admin   0.000GB
config  0.000GB
local   0.000GB

Because you’ve authenticated as a privileged user, the shell will allow you to run commands on any of these databases.

Now that you have successfully connected to the MongoDB server using a MongoDB shell, you can move on to learning how to execute commands in the shell.

Step 2 — Executing Commands

As with other command line interfaces, the MongoDB shell accepts commands and returns the desired results to standard output. As mentioned previously, in MongoDB shell, all commands are typed into the command prompt denoted with the greater-than sign (>). Pressing ENTER after the command immediately executes it and returns the command output to the screen.

Most commands in MongoDB database are executed on a database or on a collection in a selected database. The currently-selected database is represented by the db object accessible through the shell. You can check which database is currently selected by typing db into the shell:

db

On a freshly-connected shell instance, the selected database is always called test:

Output
test

You can safely use this database to experiment with MongoDB and the MongoDB shell. To switch to another database, you can run the use command followed by the new database name. Try switching to a database called fruits:

use fruits

The shell will inform you that you’re now using the new database:

Output
switched to db fruits

You can verify this by typing db again to find the name of the currently-selected database:

db

This time, the output will reflect the new database:

Output
fruits

Notice that you haven’t explicitly created the fruits database. MongoDB allows you to run commands on databases and collections that don’t yet exist; it only creates these structures when an object is first inserted into them. Even though you have successfully changed the current database to fruits, this database does not exist yet.

Try creating this database by inserting an object into it. The following example outlines how to insert an object into a collection within the database called apples. By adding this object, the operation will create both the fruits database and the apples collection.

Type the following line into the MongoDB shell and press ENTER. Notice the highlighted collection name (apples):

db.apples.insert(

Pressing ENTER after an open parenthesis will start a multi-line command prompt, allowing you to enter longer commands in more than one line. The insert command won’t register as complete until you enter a closing parenthesis. Until you do, the prompt will change from the greater-than sign to an ellipsis (...).

You don’t need to break up MongoDB commands into multiple lines like this, but doing so can make long commands easier to read and understand.

On the next line, enter the object within a pair of curly brackets ({ and }). This example document has only one field and value pair:

{name: 'Red Delicious'}

When you once again press ENTER, another line prompt will be shown, allowing you to add further command parameters, like other documents or any specifications allowed by MongoDB’s insert method. For this example, though, you can end your input and run the operation by entering a closing parenthesis and pressing ENTER:

)

This time, the Mongo shell will register the ending of the insert command and execute the whole statement.

Output
WriteResult({ "nInserted" : 1 })

After inserting this new object into the database, both the fruits database and apples collection will exist. Check the list of available databases with show dbs command:

show dbs

Again, this returns a list of all the available databases, but this time the list includes the fruits database:

Output
admin   0.000GB
config  0.000GB
fruits  0.000GB
local   0.000GB

To retrieve a list of collections available in the currently-selected database, the show collections command comes in handy:

show collections

Since the fruits database is selected, it will only return the newly-created apples collection:

Output
apples

With that, you’ve learned how to execute commands in the MongoDB shell. You also created a sample object, which in turn created a new database and a new collection that is now persisted on the server.

In the final step of this guide, you’ll learn how to invoke the MongoDB shell’s help features to better understand commands and execute them with greater ease.

Step 3 — Getting Interactive Help from the Shell

The MongoDB shell has a built-in help system that you can use to get information on database system’s available commands and the objects stored within it. This introductory help screen can be accessed with the help command directly in the shell prompt:

help

The MongoDB shell will return a list of more detailed help entries you can use to learn about more specific parts of the shell, as well as with a few examples of most commonly used commands:

Output
        db.help()                    help on db methods
        db.mycoll.help()             help on collection methods
        sh.help()                    sharding helpers
        rs.help()                    replica set helpers
        help admin                   administrative help
        help connect                 connecting to a db help
        help keys                    key shortcuts
        help misc                    misc things to know
        help mr                      mapreduce

        show dbs                     show database names
        show collections             show collections in current database
        show users                   show users in current database
        show profile                 show most recent system.profile entries with time >= 1ms
        show logs                    show the accessible logger names
        show log [name]              prints out the last segment of log in memory, 'global' is default
        use <db_name>                set current database
        db.mycoll.find()             list objects in collection mycoll
        db.mycoll.find( { a : 1 } )  list objects in mycoll where a == 1
        it                           result of the last line evaluated; use to further iterate
        DBQuery.shellBatchSize = x   set default number of items to display on shell
        exit                         quit the mongo shell

The first two entries, highlighted in this example output, illustrate how to execute a help command for the current database and a collection within the current database, respectively. The example collection name given is mycoll, but any valid collection name can be used.

The last highlighted line — db.mycoll.find() — is an example of one way to retrieve an object from a collection using the find command, which lists objects in a given collection. Because collections are some of the most commonly used structures in a Mongo database, this step will go over how to use Mongo’s find() and help() collection-level methods.

First, access the apples collection’s help screen to find the commands available for this collection:

db.apples.help()

The output for this command will be lengthy list of available commands you can perform on the apples collection:

Output
DBCollection help
        db.apples.find().help() - show DBCursor help
        db.apples.bulkWrite( operations, <optional params> ) - bulk execute write operations, optional parameters are: w, wtimeout, j
        db.apples.count( query = {}, <optional params> ) - count the number of documents that matches the query, optional parameters are: limit, skip, hint, maxTimeMS
        db.apples.countDocuments( query = {}, <optional params> ) - count the number of documents that matches the query, optional parameters are: limit, skip, hint, maxTimeMS
. . .
        db.apples.find([query],[fields]) - query is an optional query filter. fields is optional set of fields to return.
                                                      e.g. db.apples.find( {x:77} , {name:1, x:1} )
        db.apples.find(...).count()
        db.apples.find(...).limit(n)
        db.apples.find(...).skip(n)
        db.apples.find(...).sort(...)
. . .

In addition to the pure list of available commands you can execute on the db.apples collection (each of which are followed by short descriptions of what the given command does), this help screen also gives usage examples for frequently-used commands such as find().

This bundled help system serves as a useful reference of available commands. You can use it to check your syntax in case you don’t remember the exact spelling or the acceptable fields for a command.

Since you’ve already learned from the help screens that find() can be used to retrieve objects from a collection, you can now try retrieving the object you created in the apples collection in the previous step.

However, this example will highlight another of MongoDB’s interactive help aids known as command completion. The MongoDB shell follows the pattern found in other popular shells such as Bash or zsh in which pressing the keyboard’s TAB key will automatically complete whatever command you’re in the process of typing.

Start by typing the following, but do not press ENTER yet:

db.a

Instead of typing the collection name in full, press the TAB key on the keyboard. The MongoDB shell will respond with the list of all the available possibilities that begin with a:

Output
> db.a
db.adminCommand(  db.aggregate(     db.apples         db.auth(

This output lists three commands, indicated by an opening parenthesis, as well as the apples collection.

Type one more letter into the shell:

db.ap

Press TAB once more. This time, there are no other possibilities starting with ap and the MongoDB shell will automatically complete the entry and type db.apples for you. Follow the same principle and complete the find() command using TAB completion. Type fi but do not press ENTER:

db.apples.fi

Pressing TAB will automatically complete the command name to db.apples.find. At this point, pressing TAB again would cause the shell to list further possibilities, but you can manually add a closing parenthesis to execute the find command:

db.apples.find()

The shell will show a list of all the objects found in the apples collection. There will be only one object, the one you inserted previously:

Output
{ "_id" : ObjectId("60f31447f5643f739b0276e9"), "name" : "Red Delicious" }

With that, you’ve learned how to use the built-in help system and the Mongo shell’s autocomplete feature.

Conclusion

By reading this article, you will have familiarized yourself with the MongoDB shell. The shell makes it possible to insert new objects into the database, query the existing collections, and perform administrative tasks for managing the database, its data, and its users.

The MongoDB shell exposes direct access to most of Mongo’s features, such as database and collection objects and methods, making it the primary tool to interactive with a database server. However, the same set of functions and methods can be used when working with MongoDB programmatically, either through MongoDB shell scripting or through the drivers MongoDB has made available for many programming languages.

You can execute commands from other articles in this series in the MongoDB shell following the principles described in this tutorial. We encourage you to learn more about MongoDB Shell in the official MongoDB documentation.