- Reference >
- MongoDB Package Components >
mongo
mongo
¶
On this page
Description¶
-
mongo
¶
mongo
is an interactive JavaScript shell interface to
MongoDB, which provides a powerful interface for system
administrators as well as a way for developers to test queries and
operations directly with the database. mongo
also provides
a fully functional JavaScript environment for use with a MongoDB.
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.
Note
- Starting in MongoDB 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. - Starting in version 4.0,
mongo
disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see Disable TLS 1.0.
Syntax¶
You can run
mongo
shell without any command-line options use the default settings:You can run
mongo
shell with a connection string that specifies the host and port and other connection options. For example:To connect
mongo
shell to a replica set, you can specify in the connection string the replica set members and name:For more information on the connection string options, see Connection String URI Format.
You can run
mongo
shell with various command-line options. For example:For more information on the options available, see Options.
Options¶
Core Options¶
-
--shell
¶
Enables the shell interface. If you invoke the mongo command and specify a JavaScript file as an argument, or use
--eval
to specify JavaScript on the command line, the--shell
option provides the user with a shell prompt after the file finishes executing.
-
--nodb
¶
Prevents the shell from connecting to any database instances. Later, to connect to a database within the shell, see Opening New Connections.
-
--norc
¶
Prevents the shell from sourcing and evaluating
~/.mongorc.js
on start up.
-
--quiet
¶
Silences output from the shell during the connection process.
-
--port
<port>
¶ Specifies the port where the
mongod
ormongos
instance is listening. If--port
is not specified, mongo attempts to connect to port27017
.
-
--host
<hostname>
¶ Specifies the name of the host machine where the
mongod
ormongos
is running. If this is not specified, mongo attempts to connect to a MongoDB process running on the localhost.- To connect to a replica set,
Specify the
replica set name
and a seed list of set members. Use the following form:- For TLS/SSL connections (
--ssl
), - The
mongo
shell verifies that the hostname (specified in--host
option or the connection string) matches theSAN
(or, ifSAN
is not present, theCN
) in the certificate presented by themongod
ormongos
. IfSAN
is present,mongo
does not match against theCN
. If the hostname does not match theSAN
(orCN
), themongo
shell will fail to connect. - For DNS seedlist connections,
Specify the connection protocol as
mongodb+srv
, followed by the DNS SRV hostname record and any options. TheauthSource
andreplicaSet
options, if included in the connection string, will override any corresponding DNS-configured options set in the TXT record. Use of themongodb+srv:
connection string implicitly enables TLS/SSL (normally set withssl=true
) for the client connection. The TLS/SSL option can be turned off by settingssl=false
in the query string.Example:
New in version 3.6.
-
--eval
<javascript>
¶ Evaluates a JavaScript expression that is specified as an argument. mongo does not load its own environment when evaluating code. As a result many options of the shell environment are not available.
-
--username
<username>
,
-u
<username>
¶ Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--password
and--authenticationDatabase
options.
-
--password
<password>
,
-p
<password>
¶ Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--username
and--authenticationDatabase
options. To force mongo to prompt for a password, enter the--password
option as the last option and leave out the argument.
-
--help
,
-h
¶
Returns information on the options and use of mongo.
-
--version
¶
Returns the mongo release number.
-
--verbose
¶
Increases the verbosity of the output of the shell during the connection process.
-
--networkMessageCompressors
<string>
¶ New in version 3.4.
Enables network compression for communication between this mongo shell and:
You can specify the following compressors:
Important
Messages are compressed when both parties enable network compression. Otherwise, messages between the parties are uncompressed.
If you specify multiple compressors, then the order in which you list the compressors matter as well as the communication initiator. For example, if a
mongo
shell specifies the following network compressorszlib,snappy
and themongod
specifiessnappy,zlib
, messages betweenmongo
shell andmongod
useszlib
.If the parties do not share at least one common compressor, messages between the parties are uncompressed. For example, if a
mongo
shell specifies the network compressorzlib
andmongod
specifiessnappy
, messages betweenmongo
shell andmongod
are not compressed.
-
--ipv6
¶
Enables IPv6 support. mongo disables IPv6 by default.
To connect to a MongoDB cluster via IPv6, you must specify both
--ipv6
and--host <mongod/mongos IPv6 address>
when starting the mongo shell.mongod
andmongos
disable IPv6 support by default. Specifying--ipv6
when connecting to amongod/mongos
does not enable IPv6 support on themongod/mongos
. For documentation on enabling IPv6 support on themongod/mongos
, seenet.ipv6
.
-
<db
name>
¶ Specifies the name of the database to connect to. For example:
The above command will connect the mongo shell to the admin database of the MongoDB deployment running on the local machine. You may specify a remote database instance, with the resolvable hostname or IP address. Separate the database name from the hostname using a
/
character. See the following examples:This syntax is the only way to connect to a specific database.
To specify alternate hosts and a database, you must use this syntax and cannot use
--host
or--port
.
-
--enableJavaScriptJIT
¶
New in version 4.0.
Enable the JavaScript engine’s JIT compiler.
-
--disableJavaScriptJIT
¶
Changed in version 4.0: The JavaScript engine’s JIT compiler is now disabled by default.
Disables the JavaScript engine’s JIT compiler.
-
--disableJavaScriptProtection
¶
New in version 3.4.
Allows fields of type javascript and javascriptWithScope to be automatically marshalled to JavaScript functions in the
mongo
shell.With the
--disableJavaScriptProtection
flag set, it is possible to immediately execute JavaScript functions contained in documents. The following example demonstrates this behavior within the shell:The default behavior (when
mongo
starts without the--disableJavaScriptProtection
flag) is to convert embedded JavaScript functions to the non-executable MongoDB shell typeCode
. The following example demonstrates the default behavior within the shell:
-
<file.js>
¶
Specifies a JavaScript file to run and then exit. Generally this should be the last option specified.
Optional
To specify a JavaScript file to execute and allow mongo to prompt you for a password using
--password
, pass the filename as the first parameter with--username
and--password
as the last options, as in the following:Use the
--shell
option to return to a shell after the file finishes running.
Authentication Options¶
-
--authenticationDatabase
<dbname>
¶ Specifies the authentication database where the specified
--username
has been created. See Authentication Database.If you do not specify a value for
--authenticationDatabase
, mongo uses the database specified in the connection string.
-
--authenticationMechanism
<name>
¶ Default: SCRAM-SHA-1
Specifies the authentication mechanism the mongo instance uses to authenticate to the
mongod
ormongos
.Changed in version 4.0: MongoDB removes support for the deprecated MongoDB Challenge-Response (
MONGODB-CR
) authentication mechanism.MongoDB adds support for SCRAM mechanism using the SHA-256 hash function (
SCRAM-SHA-256
).Value Description SCRAM-SHA-1 RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA-1 hash function. SCRAM-SHA-256 RFC 7677 standard Salted Challenge Response Authentication Mechanism using the SHA-256 hash function.
Requires featureCompatibilityVersion set to
4.0
.New in version 4.0.
MONGODB-X509 MongoDB TLS/SSL certificate authentication. GSSAPI (Kerberos) External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise. PLAIN (LDAP SASL) External authentication using LDAP. You can also use PLAIN
for authenticating in-database users.PLAIN
transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.
-
--gssapiHostName
¶
New in version 2.6.
Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.
This option is available only in MongoDB Enterprise.
-
--gssapiServiceName
¶
New in version 2.6.
Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of
mongodb
.This option is available only in MongoDB Enterprise.
TLS/SSL Options¶
-
--ssl
¶
Changed in version 3.2.6.
Enables connection to a
mongod
ormongos
that has TLS/SSL support enabled.Starting in version 3.2.6, if
--sslCAFile
orssl.CAFile
is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, themongo
shell exited with an error that it could not validate the certificate.If using x.509 authentication,
--sslCAFile
orssl.CAFile
must be specified unless using--sslCertificateSelector
.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslPEMKeyFile
<filename>
¶ Specifies the
.pem
file that contains both the TLS/SSL certificate and key. Specify the file name of the.pem
file using relative or absolute paths.This option is required when using the
--ssl
option to connect to amongod
ormongos
that hasCAFile
enabled withoutallowConnectionsWithoutCertificates
.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslPEMKeyPassword
<value>
¶ Specifies the password to de-crypt the certificate-key file (i.e.
--sslPEMKeyFile
). Use the--sslPEMKeyPassword
option only if the certificate-key file is encrypted. In all cases, the mongo will redact the password from all logging and reporting output.If the private key in the PEM file is encrypted and you do not specify the
--sslPEMKeyPassword
option, the mongo will prompt for a passphrase. See TLS/SSL Certificate Passphrase.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslCAFile
<filename>
¶ Specifies the
.pem
file that contains the root certificate chain from the Certificate Authority. Specify the file name of the.pem
file using relative or absolute paths.Starting in version 3.2.6, if
--sslCAFile
orssl.CAFile
is not specified, the system-wide CA certificate store will be used when connecting to an TLS/SSL-enabled server. In previous versions of MongoDB, themongo
shell exited with an error that it could not validate the certificate.If using x.509 authentication,
--sslCAFile
orssl.CAFile
must be specified unless using--sslCertificateSelector
.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslCertificateSelector
<parameter>=<value>
¶ New in version 4.0: Available on Windows and macOS as an alternative to
--sslPEMKeyFile
.--sslPEMKeyFile
and--sslCertificateSelector
options are mutually exclusive. You can only specify one.Specifies a certificate property in order to select a matching certificate from the operating system’s certificate store.
--sslCertificateSelector
accepts an argument of the format<property>=<value>
where the property can be one of the following:Property Value type Description subject
ASCII string Subject name or common name on certificate thumbprint
hex string A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.
The
thumbprint
is sometimes referred to as afingerprint
.When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.
-
--sslCRLFile
<filename>
¶ Specifies the
.pem
file that contains the Certificate Revocation List. Specify the file name of the.pem
file using relative or absolute paths.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslFIPSMode
¶
New in version 2.6.
Directs the mongo to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS compliant library to use the
--sslFIPSMode
option.Note
FIPS-compatible TLS/SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
-
--sslAllowInvalidCertificates
¶
Bypasses the validation checks for server certificates and allows the use of invalid certificates to connect.
Note
Starting in MongoDB 4.0, if you specify
--sslAllowInvalidCertificates
orssl.allowInvalidCertificates: true
when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is insufficient for authentication.Warning
Although available, avoid using the
--sslAllowInvalidCertificates
option if possible. If the use of--sslAllowInvalidCertificates
is necessary, only use the option on systems where intrusion is not possible.If the
mongo
shell (and other MongoDB Tools) runs with the--sslAllowInvalidCertificates
option, themongo
shell (and other MongoDB Tools) will not attempt to validate the server certificates. This creates a vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see--sslAllowInvalidHostnames
.When using the
allowInvalidCertificates
setting, MongoDB logs as a warning the use of the invalid certificate.For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslAllowInvalidHostnames
¶
New in version 3.0.
Disables the validation of the hostnames in TLS/SSL certificates. Allows mongo to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname.
For more information about TLS/SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients .
-
--sslDisabledProtocols
<string>
¶ Disables the specified TLS protocols. The option recognizes the following protocols:
TLS1_0
,TLS1_1
,TLS1_2
, and starting in version 4.0.4 (and 3.6.9 and 3.4.24),TLS1_3
.- On macOS, you cannot disable
TLS1_1
and leave bothTLS1_0
andTLS1_2
enabled. You must also disable at least one of the other two; for example,TLS1_0,TLS1_1
. - To list multiple protocols, specify as a comma separated list of
protocols. For example
TLS1_0,TLS1_1
. - The specified disabled protocols overrides any default disabled protocols.
Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS 1.1+ is available on the system. To enable the disabled TLS 1.0, specify
none
to--sslDisabledProtocols
. See Disable TLS 1.0.New in version 3.6.5.
- On macOS, you cannot disable
Sessions¶
-
--retryWrites
¶
New in version 3.6.
Enables retryable writes as the default for sessions in the
mongo
shell.For more information on sessions, see Client Sessions and Causal Consistency Guarantees.
Files¶
~/.dbshell
mongo
maintains a history of commands in the.dbshell
file.Note
mongo
does not record interaction related to authentication in the history file, includingauthenticate
anddb.createUser()
.
~/.mongorc.js
mongo
will read the.mongorc.js
file from the home directory of the user invokingmongo
. In the file, users can define variables, customize themongo
shell prompt, or update information that they would like updated every time they launch a shell. If you use the shell to evaluate a JavaScript file or expression either on the command line withmongo --eval
or by specifying a .js file to mongo,mongo
will read the.mongorc.js
file after the JavaScript has finished processing.Specify the
--norc
option to disable reading.mongorc.js
.
/etc/mongorc.js
Global
mongorc.js
file which themongo
shell evaluates upon start-up. If a user also has a.mongorc.js
file located in theHOME
directory, themongo
shell evaluates the global/etc/mongorc.js
file before evaluating the user’s.mongorc.js
file./etc/mongorc.js
must have read permission for the user running the shell. The--norc
option formongo
suppresses only the user’s.mongorc.js
file.On Windows, the global
mongorc.js </etc/mongorc.js>
exists in the%ProgramData%\MongoDB
directory./tmp/mongo_edit<time_t>.js
- Created by
mongo
when editing a file. If the file exists,mongo
will append an integer from1
to10
to the time value to attempt to create a unique file. %TEMP%mongo_edit<time_t>.js
- Created by
mongo.exe
on Windows when editing a file. If the file exists,mongo
will append an integer from1
to10
to the time value to attempt to create a unique file.
Environment¶
-
EDITOR
¶ Specifies the path to an editor to use with the
edit
shell command. A JavaScript variableEDITOR
will override the value ofEDITOR
.
-
HOME
¶ Specifies the path to the home directory where
mongo
will read the.mongorc.js
file and write the.dbshell
file.
Keyboard Shortcuts¶
The mongo
shell supports the following keyboard shortcuts:
[1]
Keybinding | Function |
---|---|
Up arrow | Retrieve previous command from history |
Down-arrow | Retrieve next command from history |
Home | Go to beginning of the line |
End | Go to end of the line |
Tab | Autocomplete method/command |
Left-arrow | Go backward one character |
Right-arrow | Go forward one character |
Ctrl-left-arrow | Go backward one word |
Ctrl-right-arrow | Go forward one word |
Meta-left-arrow | Go backward one word |
Meta-right-arrow | Go forward one word |
Ctrl-A | Go to the beginning of the line |
Ctrl-B | Go backward one character |
Ctrl-C | Exit the mongo shell |
Ctrl-D | Delete a char (or exit the mongo shell) |
Ctrl-E | Go to the end of the line |
Ctrl-F | Go forward one character |
Ctrl-G | Abort |
Ctrl-J | Accept/evaluate the line |
Ctrl-K | Kill/erase the line |
Ctrl-L or type cls |
Clear the screen |
Ctrl-M | Accept/evaluate the line |
Ctrl-N | Retrieve next command from history |
Ctrl-P | Retrieve previous command from history |
Ctrl-R | Reverse-search command history |
Ctrl-S | Forward-search command history |
Ctrl-T | Transpose characters |
Ctrl-U | Perform Unix line-discard |
Ctrl-W | Perform Unix word-rubout |
Ctrl-Y | Yank |
Ctrl-Z | Suspend (job control works in linux) |
Ctrl-H | Backward-delete a character |
Ctrl-I | Complete, same as Tab |
Meta-B | Go backward one word |
Meta-C | Capitalize word |
Meta-D | Kill word |
Meta-F | Go forward one word |
Meta-L | Change word to lowercase |
Meta-U | Change word to uppercase |
Meta-Y | Yank-pop |
Meta-Backspace | Backward-kill word |
Meta-< | Retrieve the first command in command history |
Meta-> | Retrieve the last command in command history |
[1] | MongoDB accommodates multiple keybinding.
Since 2.0, mongo includes support for basic emacs
keybindings. |
Use¶
Typically users invoke the shell with the mongo
command at
the system prompt. Consider the following examples for other
scenarios.
Connect to a mongod
Instance with Access Control¶
To connect to a database on a remote host using authentication and a non-standard port, use the following form:
Alternatively, consider the following short form:
Replace <user>
, <pass>
, and <host>
with the appropriate
values for your situation and substitute or omit the --port
as needed.
Connect to a Replica Set Using the DNS Seedlist Connection Format¶
New in version 3.6.
To connect to a replica set described using the
DNS Seedlist Connection Format, use the --host
option
to specify the connection string to the mongo
shell. In
the following example, the DNS configuration resembles:
The TXT record for the DNS entry includes the replicaSet
and authSource
options:
The following command then connects the mongo
shell to
the replica set:
The mongo
shell will automatically prompt you to provide
the password for the user specified in the username
option.
Execute JavaScript Against the mongo
Shell¶
To execute a JavaScript file without evaluating the ~/.mongorc.js
file before starting a shell session, use the following form:
To execute a JavaScript file with authentication, with password prompted rather than provided on the command-line, use the following form:
Use --eval
to Execute JavaScript Code¶
You may use the --eval
option to execute
JavaScript directly from the command line.
For example, the following operation evaluates a JavaScript string which queries a collection and prints the results as JSON.
On Linux and macOS, you will need to use single quotes (e.g. '
)
to enclose the JavaScript, using the following form:
On Windows, you will need to use double quotes (e.g. "
)
to enclose the JavaScript, using the following form: