The mongo
Shell
On this page
The mongo
shell is an interactive JavaScript interface to
MongoDB. You can use the mongo
shell to query and update
data as well as perform administrative operations.
Note
The following document pertains to the mongo
shell
included in the
MongoDB Server Download.
For information on the new MongoDB Shell, mongosh
, refer to the
mongosh Documentation.
To understand the differences between the two shells, see
Comparison of the mongo
Shell and mongosh
.
Download the mongo
Shell
The mongo
shell is included as part of the MongoDB
server installation. If you have already installed the
server, the mongo
shell is installed to the same location
as the server binary.
Alternatively, if you would like to download the mongo
shell separately from the MongoDB Server, you can install the shell as
a standalone package by following these steps:
Access the Download Center for your Edition of MongoDB:
Select your preferred Version and Platform from the dropdowns.
Select the Package to download according to your platform:
Copy the
mongo
shell from the archive to a location on your filesystem.
For additional installation guidance specific to your platform, or to
install the mongo
shell as part of a MongoDB Server
installation, see the installation guide for your platform.
Start the mongo
Shell and Connect to MongoDB
Once you have downloaded the mongo
shell, you can use it
to connect to your running MongoDB server.
Note
Starting in MongoDB 4.2 (and 4.0.13), the mongo
shell displays a
warning message when connected to non-genuine MongoDB instances as
these instances may behave differently from the official MongoDB
instances; e.g. missing or incomplete features, different feature
behaviors, etc.
Prerequisites
The MongoDB server must be installed and running before you can connect to it from the
mongo
shell. Follow the steps in the installation tutorial for your platform to install and start the MongoDB server if required.Once you have verified that the
mongod
server is running, open a terminal window (or a command prompt for Windows) and go to your<mongo shell installation dir>
directory:cd <mongo shell installation dir> Tip
Adding your
<mongo shell installation dir>
to thePATH
environment variable allows you to typemongo
directly instead of having to first go to the<mongo shell installation dir>
directory or specify the full path to the binary. Alternatively, you can copy themongo
shell to a location on your filesystem that is already present in yourPATH
, such as/usr/bin
on Linux.
Local MongoDB Instance on Default Port
You can run mongo
shell without any command-line options
to connect to a MongoDB instance
running on your localhost with default port 27017:
mongo
Local MongoDB Instance on a Non-default Port
To explicitly specify the port, include the --port
command-line option. For example, to connect to a MongoDB
instance running on localhost with a non-default port 28015:
mongo --port 28015
MongoDB Instance on a Remote Host
To explicitly specify the hostname and/or port,
You can specify a connection string. For example, to connect to a MongoDB instance running on a remote host machine:
mongo "mongodb://mongodb0.example.com:28015" You can use the command-line option
--host <host>:<port>
. For example, to connect to a MongoDB instance running on a remote host machine:mongo --host mongodb0.example.com:28015 You can use the
--host <host>
and--port <port>
command-line options. For example, to connect to a MongoDB instance running on a remote host machine:mongo --host mongodb0.example.com --port 28015
MongoDB Instance with Authentication
To connect to a MongoDB instance requires authentication:
You can specify the username, authentication database, and optionally the password in the connection string. For example, to connect and authenticate to a remote MongoDB instance as user
alice
:Note
If you do not specify the password in the connection string, the shell will prompt for the password.
mongo "mongodb://alice@mongodb0.examples.com:28015/?authSource=admin" You can use the
--username <user>
and--password
,--authenticationDatabase <db>
command-line options. For example, to connect and authenticate to a remote MongoDB instance as useralice
:Note
If you specify
--password
without the user's password, the shell will prompt for the password.mongo --username alice --password --authenticationDatabase admin --host mongodb0.examples.com --port 28015
Connect to a MongoDB Replica Set
To connect to a replica set:
You can specify the replica set name and members in the connection string.
mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA" If using the DNS Seed List Connection Format, you can specify the connection string:
mongo "mongodb+srv://server.example.com/" Note
Use of the
+srv
connection string modifier automatically sets the ssl option to true for the connection.You can specify the replica set name and members from the
--host <replica set name>/<host1>:<port1>,<host2>:<port2>,...
command-line option. For example, to connect to replica set namedreplA
:mongo --host replA/mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017
TLS/SSL Connection
For TLS/SSL connections,
You can specify the
ssl=true
option in the connection string.mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA&ssl=true" If using the DNS Seed List Connection Format, you can include the
+srv
connection string modifier:mongo "mongodb+srv://server.example.com/" Note
Use of the
+srv
connection string modifier automatically sets the ssl option to true for the connection.You can specify
--ssl
command-line option. For example, to connect to replica set namedreplA
:mongo --ssl --host replA/mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017
Tip
See also:
For more information on the options used in the connection examples as well as other options, see mongo reference and examples of starting up mongo.
Working with the mongo
Shell
To display the database you are using, type db
:
db
The operation should return test
, which is the default database.
To switch databases, issue the use <db>
helper, as in the
following example:
use <database>
See also db.getSiblingDB()
method to access a
different database from the current database without switching your
current database context (i.e. db
).
To list the databases available to the user, use the helper show
dbs
. [1]
You can switch to non-existing databases. When you first store data in
the database, such as by creating a collection, MongoDB creates the
database. For example, the following creates both the database
myNewDatabase
and the collection myCollection
during
the insertOne()
operation:
use myNewDatabase db.myCollection.insertOne( { x: 1 } );
The db.myCollection.insertOne()
is one
of the methods available in the mongo shell.
db
refers to the current database.myCollection
is the name of the collection.
If the mongo
shell does not accept the name of a collection,
you can use the alternative db.getCollection()
syntax.
For instance, if a collection name contains a space or hyphen, starts
with a number, or conflicts with a built-in function:
db.getCollection("3 test").find() db.getCollection("3-test").find() db.getCollection("stats").find()
The mongo
shell prompt has a limit of 4095 codepoints for
each line. If you enter a line with more than 4095 codepoints, the
shell will truncate it.
For more documentation of basic MongoDB operations in the
mongo
shell, see:
[1] | If the deployment runs with access control, the operation returns different values based on user privileges. See listDatabases Behavior for details. |
Format Printed Results
The db.collection.find()
method returns a cursor to
the results; however, in the mongo
shell, if the returned
cursor is not assigned to a variable using the var
keyword, then
the cursor is automatically iterated up to 20 times to print up to the
first 20 documents that match the query. The mongo
shell
will prompt Type it
to iterate another 20 times.
To format the printed result, you can add the .pretty()
to the
operation, as in the following:
db.myCollection.find().pretty()
In addition, you can use the following explicit print methods in the
mongo
shell:
print()
to print without formattingprint(tojson(<obj>))
to print with JSON formatting and equivalent toprintjson()
printjson()
to print with JSON formatting and equivalent toprint(tojson(<obj>))
For more information and examples on cursor handling in the
mongo
shell, see Iterate a Cursor in the mongo
Shell. See also
Cursor Help for list of cursor help in the
mongo
shell.
Multi-line Operations in the mongo
Shell
If you end a line with an open parenthesis ('('
), an open brace
('{'
), or an open bracket ('['
), then the subsequent lines start
with ellipsis ("..."
) until you enter the corresponding closing
parenthesis (')'
), the closing brace ('}'
) or the closing
bracket (']'
). The mongo
shell waits for the closing
parenthesis, closing brace, or the closing bracket before evaluating
the code, as in the following example:
> if ( x > 0 ) { ... count++; ... print (x); ... }
You can exit the line continuation mode if you enter two blank lines, as in the following example:
> if (x > 0 ... ... >
Tab Completion and Other Keyboard Shortcuts
The mongo
shell supports keyboard shortcuts. For example,
Use the up/down arrow keys to scroll through command history. See .dbshell documentation for more information on the
.dbshell
file.Use
<Tab>
to autocomplete or to list the completion possibilities, as in the following example which uses<Tab>
to complete the method name starting with the letter'c'
:db.myCollection.c<Tab> Because there are many collection methods starting with the letter
'c'
, the<Tab>
will list the various methods that start with'c'
.
For a full list of the shortcuts, see Shell Keyboard Shortcuts
.mongorc.js
File
When starting, mongo
checks the user's HOME
directory for a JavaScript file named .mongorc.js. If found, mongo
interprets the
content of .mongorc.js
before displaying the prompt for the
first time. If you use the shell to evaluate a JavaScript file or
expression, either by using the --eval
option on the command line or by specifying a .js file to
mongo, mongo
will read the
.mongorc.js
file after the JavaScript has finished processing.
You can prevent .mongorc.js
from being loaded by using the
--norc
option.
Exit the Shell
To exit the shell, type quit()
or use the <Ctrl-C>
shortcut.
Comparison of the mongo
Shell and mongosh
The new MongoDB Shell, mongosh, offers numerous
advantages over the mongo
shell, such as:
Improved syntax highlighting.
Improved command history.
Improved logging.
Some mongo
shell methods are unavailable or have been replaced
with updated methods in mongosh
.
To maintain backwards compatibility, the methods that mongosh
supports use
the same syntax as the corresponding methods in the mongo
shell.
To see the complete list of methods supported by mongosh
, see
MongoDB Shell Methods.