- 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 systems 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. This document addresses the basic invocation of the mongo shell and an overview of its usage.
Options¶
Core Options¶
- mongo¶
- --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 or mongos instance is listening. If --port is not specified, mongo attempts to connect to port 27017.
- --host <hostname>¶
Specifies the name of the host machine where the mongod or mongos 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:
<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
- --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.
- --ipv6¶
Enables IPv6 support and allows the mongo to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.
- <db address>
Specifies the “database address” of the database to connect to. For example:
mongo admin
The above command will connect the mongo shell to the admin database 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:
mongo mongodb1.example.net mongo mongodb1/admin mongo 10.8.8.10/test
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.
- --disableJavaScriptJIT¶
New in version 3.2.
Disables use of the JavaScript engine’s JIT compiler.
- <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:
mongo file.js --username username --password
Use the --shell option to return to a shell after the file finishes running.
Authentication Options¶
- --authenticationDatabase <dbname>¶
Specifies the database in which the user is 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
Changed in version 2.6: Added support for the PLAIN and MONGODB-X509 authentication mechanisms.
Changed in version 3.0: Added support for the SCRAM-SHA-1 authentication mechanism. Changed default mechanism to SCRAM-SHA-1.
Specifies the authentication mechanism the mongo instance uses to authenticate to the mongod or mongos.
Value Description SCRAM-SHA-1 RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA1 hash function. MONGODB-CR MongoDB challenge/response authentication. 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¶
Enables connection to a mongod or mongos that has TLS/SSL support enabled.
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslPEMKeyFile <filename>¶
New in version 2.4.
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 a mongod or mongos that has CAFile enabled without allowConnectionsWithoutCertificates.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslPEMKeyPassword <value>¶
New in version 2.4.
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.
Changed in version 2.6: 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 SSL Certificate Passphrase.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslCAFile <filename>¶
New in version 2.4.
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.
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
Warning
For SSL connections (--ssl) to mongod and mongos, if the mongo shell runs without the --sslCAFile <CAFile> option (i.e. specifies the --sslAllowInvalidCertificates instead), the mongo shell will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslCRLFile <filename>¶
New in version 2.4.
Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslFIPSMode¶
New in version 2.6.
Directs the mongo to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the --sslFIPSMode option.
Note
FIPS-compatible SSL is available only in MongoDB Enterprise. See Configure MongoDB for FIPS for more information.
- --sslAllowInvalidCertificates¶
New in version 2.6.
Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the allowInvalidCertificates setting, MongoDB logs as a warning the use of the invalid certificate.
Changed in version 3.0: When running mongo with the --ssl option, you must include either --sslCAFile or --sslAllowInvalidCertificates.
Warning
For SSL connections (--ssl) to mongod and mongos, if the mongo shell runs without the --sslCAFile <CAFile> option (i.e. specifies the --sslAllowInvalidCertificates instead), the mongo shell will not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. Ensure that you always specify the CA file to validate the server certificates in cases where intrusion is a possibility.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
- --sslAllowInvalidHostnames¶
New in version 3.0.
Disables the validation of the hostnames in TLS/SSL certificates. Allows mongo to connect to MongoDB instances if the hostname their certificates do not match the specified hostname.
Changed in version 3.0: Most MongoDB distributions now include support for TLS/SSL. See Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients for more information about TLS/SSL and MongoDB.
Files¶
- ~/.dbshell
mongo maintains a history of commands in the .dbshell file.
Note
mongo does not recorded interaction related to authentication in the history file, including authenticate and db.createUser().
Warning
Versions of Windows mongo.exe earlier than 2.2.0 will save the .dbshell file in the mongo.exe working directory.
- ~/.mongorc.js
mongo will read the .mongorc.js file from the home directory of the user invoking mongo. In the file, users can define variables, customize the mongo 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 with --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 the mongo shell evaluates upon start-up. If a user also has a .mongorc.js file located in the HOME directory, the mongo 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 for mongo 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 from 1 to 10 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 from 1 to 10 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 variable EDITOR will override the value of EDITOR.
- HOME¶
Specifies the path to the home directory where mongo will read the .mongorc.js file and write the .dbshell file.
- HOMEDRIVE¶
On Windows systems, HOMEDRIVE specifies the path the directory where mongo will read the .mongorc.js file and write the .dbshell file.
- HOMEPATH¶
Specifies the Windows 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.
To connect to a database on a remote host using authentication and a non-standard port, use the following form:
mongo --username <user> --password <pass> --host <host> --port 28015
Alternatively, consider the following short form:
mongo -u <user> -p <pass> --host <host> --port 28015
Replace <user>, <pass>, and <host> with the appropriate values for your situation and substitute or omit the --port as needed.
To execute a JavaScript file without evaluating the ~/.mongorc.js file before starting a shell session, use the following form:
mongo --shell --norc alternate-environment.js
To execute a JavaScript file with authentication, with password prompted rather than provided on the command-line, use the following form:
mongo script-file.js -u <user> -p
To print return a query as JSON, from the system prompt using the --eval option, use the following form:
mongo --eval 'db.collection.find().forEach(printjson)'
Use single quotes (e.g. ') to enclose the JavaScript, as well as the additional JavaScript required to generate this output.
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.