1MONGO(1) mongodb-manual MONGO(1)
2
6 mongo - MongoDB Shell
7
9 mongo is an interactive JavaScript shell interface to MongoDB, which
10 provides a powerful interface for systems administrators as well as a
11 way for developers to test queries and operations directly with the
12 database. mongo also provides a fully functional JavaScript environment
13 for use with a MongoDB. This document addresses the basic invocation of
14 the mongo shell and an overview of its usage.
15
17 Core Options
18 mongo
19 --shell
21 Enables the shell interface. If you invoke the mongo command and
22 specify a JavaScript file as an argument, or use --eval to spec‐
23 ify JavaScript on the command line, the --shell option provides
24 the user with a shell prompt after the file finishes executing.
25 --nodb Prevents the shell from connecting to any database instances.
27 Later, to connect to a database within the shell, see
28 mongo-shell-new-connections.
29 --norc Prevents the shell from sourcing and evaluating ~/.mongorc.js on
31 start up.
32 --quiet
34 Silences output from the shell during the connection process.
35 --port <port>
37 Specifies the port where the mongod or mongos instance is lis‐
38 tening. If --port is not specified, mongo attempts to connect to
39 port 27017.
40 --host <hostname>
42 Specifies the name of the host machine where the mongod or mon‐
43 gos is running. If this is not specified, mongo attempts to con‐
44 nect to a MongoDB process running on the localhost.
45 To connect to a replica set, specify the replica set name and a
47 seed list of set members. Use the following form:
48 <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
50 --eval <javascript>
52 Evaluates a JavaScript expression that is specified as an argu‐
53 ment. mongo does not load its own environment when evaluating
54 code. As a result many options of the shell environment are not
55 available.
56 --username <username>, -u <username>
58 Specifies a username with which to authenticate to a MongoDB
59 database that uses authentication. Use in conjunction with the
60 --password and --authenticationDatabase options.
61 --password <password>, -p <password>
63 Specifies a password with which to authenticate to a MongoDB
64 database that uses authentication. Use in conjunction with the
65 --username and --authenticationDatabase options. To force mongo
66 to prompt for a password, enter the --password option as the
67 last option and leave out the argument.
68 --help, -h
70 Returns information on the options and use of mongo.
71 --version
73 Returns the mongo release number.
74 --verbose
76 Increases the verbosity of the output of the shell during the
77 connection process.
78 --ipv6 Enables IPv6 support and allows the mongo to connect to the Mon‐
80 goDB instance using an IPv6 network. All MongoDB programs and
81 processes disable IPv6 support by default.
82 <db address>
84 Specifies the "database address" of the database to connect to.
85 For example:
86 mongo admin
88 The above command will connect the mongo shell to the admin
90 database on the local machine. You may specify a remote database
91 instance, with the resolvable hostname or IP address. Separate
92 the database name from the hostname using a / character. See the
93 following examples:
94 mongo mongodb1.example.net
96 mongo mongodb1/admin
97 mongo 10.8.8.10/test
98 This syntax is the only way to connect to a specific database.
100 To specify alternate hosts and a database, you must use this
102 syntax and cannot use --host or --port.
103 <file.js>
105 Specifies a JavaScript file to run and then exit. Generally this
106 should be the last option specified.
107 Optional
109 To specify a JavaScript file to execute and allow mongo to prompt you
110 for a password using --password, pass the filename as the first parame‐
111 ter with --username and --password as the last options, as in the fol‐
112 lowing:
113 mongo file.js --username username --password
115 Use the --shell option to return to a shell after the file fin‐
117 ishes running.
118 Authentication Options
120 --authenticationDatabase <dbname>
121 New in version 2.4.
122 Specifies the database that holds the user's credentials.
125 If you do not specify a value for --authenticationDatabase,
127 mongo uses the database specified in the connection string.
128 --authenticationMechanism <name>
130 Default: MONGODB-CR
131 New in version 2.4.
133 Changed in version 2.6: Added support for the PLAIN and MON‐
136 GODB-X509 authentication mechanisms.
137 Specifies the authentication mechanism the mongo instance uses
140 to authenticate to the mongod or mongos.
141 ┌─────────────┬────────────────────────────┐
143 │Value │ Description │
144 ├─────────────┼────────────────────────────┤
145 │MONGODB-CR │ MongoDB challenge/response │
146 │ │ authentication. │
147 ├─────────────┼────────────────────────────┤
148 │MONGODB-X509 │ MongoDB SSL certificate │
149 │ │ authentication. │
150 ├─────────────┼────────────────────────────┤
151 │PLAIN │ External authentication │
152 │ │ using LDAP. You can also │
153 │ │ use PLAIN for authenticat‐ │
154 │ │ ing in-database users. │
155 │ │ PLAIN transmits passwords │
156 │ │ in plain text. This mecha‐ │
157 │ │ nism is available only in │
158 │ │ MongoDB Enterprise. │
159 ├─────────────┼────────────────────────────┤
160 │GSSAPI │ External authentication │
161 │ │ using Kerberos. This mech‐ │
162 │ │ anism is available only in │
163 │ │ MongoDB Enterprise. │
164 └─────────────┴────────────────────────────┘
165 --gssapiHostName
167 New in version 2.6.
168 Specify the hostname of a service using GSSAPI/Kerberos. Only
171 required if the hostname of a machine does not match the host‐
172 name resolved by DNS.
173 This option is available only in MongoDB Enterprise.
175 --gssapiServiceName
177 New in version 2.6.
178 Specify the name of the service using GSSAPI/Kerberos. Only
181 required if the service does not use the default name of mon‐
182 godb.
183 This option is available only in MongoDB Enterprise.
185 SSL Options
187 --ssl New in version 2.2.
188 Enables connection to a mongod or mongos that has SSL support
191 enabled.
192 The default distribution of MongoDB does not contain support for
194 SSL. For more information on MongoDB and SSL, see
195 http://docs.mongodb.org/manual/tutorial/configure-ssl.
196 --sslPEMKeyFile <filename>
198 New in version 2.4.
199 Specifies the .pem file that contains both the SSL certificate
202 and key. Specify the file name of the .pem file using relative
203 or absolute paths.
204 This option is required when using the --ssl option to connect
206 to a mongod or mongos that has CAFile enabled without allowCon‐
207 nectionsWithoutCertificates.
208 The default distribution of MongoDB does not contain support for
210 SSL. For more information on MongoDB and SSL, see
211 http://docs.mongodb.org/manual/tutorial/configure-ssl.
212 --sslPEMKeyPassword <value>
214 New in version 2.4.
215 Specifies the password to de-crypt the certificate-key file
218 (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only
219 if the certificate-key file is encrypted. In all cases, the
220 mongo will redact the password from all logging and reporting
221 output.
222 Changed in version 2.6: If the private key in the PEM file is
224 encrypted and you do not specify the --sslPEMKeyPassword option,
225 the mongo will prompt for a passphrase. See ssl-certifi‐
226 cate-password.
227 The default distribution of MongoDB does not contain support for
230 SSL. For more information on MongoDB and SSL, see
231 http://docs.mongodb.org/manual/tutorial/configure-ssl.
232 --sslCAFile <filename>
234 New in version 2.4.
235 Specifies the .pem file that contains the root certificate chain
238 from the Certificate Authority. Specify the file name of the
239 .pem file using relative or absolute paths.
240 The default distribution of MongoDB does not contain support for
242 SSL. For more information on MongoDB and SSL, see
243 http://docs.mongodb.org/manual/tutorial/configure-ssl.
244 WARNING:
246 If the mongo shell or any other tool that connects to mongos
247 or mongod is run without --sslCAFile, it will not attempt to
248 validate server certificates. This results in vulnerability
249 to expired mongod and mongos certificates as well as to for‐
250 eign processes posing as valid mongod or mongos instances.
251 Ensure that you always specify the CA file against which
252 server certificates should be validated in cases where intru‐
253 sion is a possibility.
254 --sslCRLFile <filename>
256 New in version 2.4.
257 Specifies the .pem file that contains the Certificate Revocation
260 List. Specify the file name of the .pem file using relative or
261 absolute paths.
262 The default distribution of MongoDB does not contain support for
264 SSL. For more information on MongoDB and SSL, see
265 http://docs.mongodb.org/manual/tutorial/configure-ssl.
266 --sslFIPSMode
268 New in version 2.6.
269 Directs the mongo to use the FIPS mode of the installed OpenSSL
272 library. Your system must have a FIPS compliant OpenSSL library
273 to use the --sslFIPSMode option.
274 NOTE:
276 FIPS Compatible SSL is available only in MongoDB Enterprise.
277 See http://docs.mongodb.org/manual/tutorial/configure-fips
278 for more information.
279 --sslAllowInvalidCertificates
281 New in version 2.6.
282 Bypasses the validation checks for server certificates and
285 allows the use of invalid certificates. When using the allowIn‐
286 validCertificates setting, MongoDB logs as a warning the use of
287 the invalid certificate.
288 The default distribution of MongoDB does not contain support for
290 SSL. For more information on MongoDB and SSL, see
291 http://docs.mongodb.org/manual/tutorial/configure-ssl.
292 --sslAllowInvalidHostnames
294 New in version 3.0.
295 Disables the validation of the hostnames in SSL certificates.
298 Allows mongo to connect to MongoDB instances if the hostname
299 their certificates do not match the specified hostname.
300 The default distribution of MongoDB does not contain support for
302 SSL. For more information on MongoDB and SSL, see
303 http://docs.mongodb.org/manual/tutorial/configure-ssl.
304
306 ~/.dbshell
307 mongo maintains a history of commands in the .dbshell file.
308 NOTE:
310 mongo does not recorded interaction related to authentication
311 in the history file, including authenticate and db.crea‐
312 teUser().
313 WARNING:
315 Versions of Windows mongo.exe earlier than 2.2.0 will save
316 the .dbshell file in the mongo.exe working directory.
317 ~/.mongorc.js
319 mongo will read the .mongorc.js file from the home directory of
320 the user invoking mongo. In the file, users can define vari‐
321 ables, customize the mongo shell prompt, or update information
322 that they would like updated every time they launch a shell. If
323 you use the shell to evaluate a JavaScript file or expression
324 either on the command line with --eval or by specifying a .js
325 file to mongo, mongo will read the .mongorc.js file after the
326 JavaScript has finished processing.
327 Specify the --norc option to disable reading .mongorc.js.
329 /etc/mongorc.js
331 Global mongorc.js file which the mongo shell evaluates upon
332 start-up. If a user also has a .mongorc.js file located in the
333 HOME directory, the mongo shell evaluates the global /etc/mon‐
334 gorc.js file before evaluating the user's .mongorc.js file.
335 /etc/mongorc.js must have read permission for the user running
337 the shell. The --norc option for mongo suppresses only the
338 user's .mongorc.js file.
339 On Windows, the global mongorc.js </etc/mongorc.js> exists in
341 the %ProgramData%\MongoDB directory.
342 /tmp/mongo_edit<time_t>.js
344 Created by mongo when editing a file. If the file exists, mongo
345 will append an integer from 1 to 10 to the time value to attempt
346 to create a unique file.
347 %TEMP%mongo_edit<time_t>.js
349 Created by mongo.exe on Windows when editing a file. If the file
350 exists, mongo will append an integer from 1 to 10 to the time
351 value to attempt to create a unique file.
352
354 EDITOR Specifies the path to an editor to use with the edit shell com‐
355 mand. A JavaScript variable EDITOR will override the value of
356 EDITOR.
357 HOME Specifies the path to the home directory where mongo will read
359 the .mongorc.js file and write the .dbshell file.
360 HOMEDRIVE
362 On Windows systems, HOMEDRIVE specifies the path the directory
363 where mongo will read the .mongorc.js file and write the
364 .dbshell file.
365 HOMEPATH
367 Specifies the Windows path to the home directory where mongo
368 will read the .mongorc.js file and write the .dbshell file.
369
371 The mongo shell supports the following keyboard shortcuts: [1]
372 ┌───────────────────┬────────────────────────────┐
374 │Keybinding │ Function │
375 ├───────────────────┼────────────────────────────┤
376 │Up arrow │ Retrieve previous command │
377 │ │ from history │
378 ├───────────────────┼────────────────────────────┤
379 │Down-arrow │ Retrieve next command from │
380 │ │ history │
381 ├───────────────────┼────────────────────────────┤
382 │Home │ Go to beginning of the │
383 │ │ line │
384 ├───────────────────┼────────────────────────────┤
385 │End │ Go to end of the line │
386 ├───────────────────┼────────────────────────────┤
387 │Tab │ Autocomplete method/com‐ │
388 │ │ mand │
389 ├───────────────────┼────────────────────────────┤
390 │Left-arrow │ Go backward one character │
391 ├───────────────────┼────────────────────────────┤
392 │Right-arrow │ Go forward one character │
393 ├───────────────────┼────────────────────────────┤
394 │Ctrl-left-arrow │ Go backward one word │
395 ├───────────────────┼────────────────────────────┤
396 │Ctrl-right-arrow │ Go forward one word │
397 ├───────────────────┼────────────────────────────┤
398 │Meta-left-arrow │ Go backward one word │
399 └───────────────────┴────────────────────────────┘
400 │Meta-right-arrow │ Go forward one word │
402 ├───────────────────┼────────────────────────────┤
403 │Ctrl-A │ Go to the beginning of the │
404 │ │ line │
405 ├───────────────────┼────────────────────────────┤
406 │Ctrl-B │ Go backward one character │
407 ├───────────────────┼────────────────────────────┤
408 │Ctrl-C │ Exit the mongo shell │
409 ├───────────────────┼────────────────────────────┤
410 │Ctrl-D │ Delete a char (or exit the │
411 │ │ mongo shell) │
412 ├───────────────────┼────────────────────────────┤
413 │Ctrl-E │ Go to the end of the line │
414 ├───────────────────┼────────────────────────────┤
415 │Ctrl-F │ Go forward one character │
416 ├───────────────────┼────────────────────────────┤
417 │Ctrl-G │ Abort │
418 ├───────────────────┼────────────────────────────┤
419 │Ctrl-J │ Accept/evaluate the line │
420 ├───────────────────┼────────────────────────────┤
421 │Ctrl-K │ Kill/erase the line │
422 ├───────────────────┼────────────────────────────┤
423 │Ctrl-L or type cls │ Clear the screen │
424 ├───────────────────┼────────────────────────────┤
425 │Ctrl-M │ Accept/evaluate the line │
426 ├───────────────────┼────────────────────────────┤
427 │Ctrl-N │ Retrieve next command from │
428 │ │ history │
429 ├───────────────────┼────────────────────────────┤
430 │Ctrl-P │ Retrieve previous command │
431 │ │ from history │
432 ├───────────────────┼────────────────────────────┤
433 │Ctrl-R │ Reverse-search command │
434 │ │ history │
435 ├───────────────────┼────────────────────────────┤
436 │Ctrl-S │ Forward-search command │
437 │ │ history │
438 ├───────────────────┼────────────────────────────┤
439 │Ctrl-T │ Transpose characters │
440 ├───────────────────┼────────────────────────────┤
441 │Ctrl-U │ Perform Unix line-discard │
442 ├───────────────────┼────────────────────────────┤
443 │Ctrl-W │ Perform Unix word-rubout │
444 ├───────────────────┼────────────────────────────┤
445 │Ctrl-Y │ Yank │
446 ├───────────────────┼────────────────────────────┤
447 │Ctrl-Z │ Suspend (job control works │
448 │ │ in linux) │
449 ├───────────────────┼────────────────────────────┤
450 │Ctrl-H │ Backward-delete a charac‐ │
451 │ │ ter │
452 ├───────────────────┼────────────────────────────┤
453 │Ctrl-I │ Complete, same as Tab │
454 ├───────────────────┼────────────────────────────┤
455 │Meta-B │ Go backward one word │
456 ├───────────────────┼────────────────────────────┤
457 │Meta-C │ Capitalize word │
458 ├───────────────────┼────────────────────────────┤
459 │Meta-D │ Kill word │
460 ├───────────────────┼────────────────────────────┤
461 │Meta-F │ Go forward one word │
462 ├───────────────────┼────────────────────────────┤
463 │Meta-L │ Change word to lowercase │
464 ├───────────────────┼────────────────────────────┤
465 │Meta-U │ Change word to uppercase │
466 └───────────────────┴────────────────────────────┘
467 │Meta-Y │ Yank-pop │
469 ├───────────────────┼────────────────────────────┤
470 │Meta-Backspace │ Backward-kill word │
471 ├───────────────────┼────────────────────────────┤
472 │Meta-< │ Retrieve the first command │
473 │ │ in command history │
474 ├───────────────────┼────────────────────────────┤
475 │Meta-> │ Retrieve the last command │
476 │ │ in command history │
477 └───────────────────┴────────────────────────────┘
478 [1] MongoDB accommodates multiple keybinding. Since 2.0, mongo
480 includes support for basic emacs keybindings.
481
483 Typically users invoke the shell with the mongo command at the system
484 prompt. Consider the following examples for other scenarios.
485 To connect to a database on a remote host using authentication and a
487 non-standard port, use the following form:
488 mongo --username <user> --password <pass> --host <host> --port 28015
490 Alternatively, consider the following short form:
492 mongo -u <user> -p <pass> --host <host> --port 28015
494 Replace <user>, <pass>, and <host> with the appropriate values for your
496 situation and substitute or omit the --port as needed.
497 To execute a JavaScript file without evaluating the ~/.mongorc.js file
499 before starting a shell session, use the following form:
500 mongo --shell --norc alternate-environment.js
502 To execute a JavaScript file with authentication, with password
504 prompted rather than provided on the command-line, use the following
505 form:
506 mongo script-file.js -u <user> -p
508 To print return a query as JSON, from the system prompt using the
510 --eval option, use the following form:
511 mongo --eval 'db.collection.find().forEach(printjson)'
513 Use single quotes (e.g. ') to enclose the JavaScript, as well as the
515 additional JavaScript required to generate this output.
516
518 · http://docs.mongodb.org/manual/reference/mongo-shell
519 · http://docs.mongodb.org/manual/reference/method
521 · http://docs.mongodb.org/manual/tutorial/access-mongo-shell-help
523 · http://docs.mongodb.org/manual/tutorial/get‐
525 ting-started-with-the-mongo-shell
526 · http://docs.mongodb.org/manual/core/shell-types
528 · http://docs.mongodb.org/manual/tuto‐
530 rial/write-scripts-for-the-mongo-shell
531
533 MongoDB Documentation Project
534
536 2011-2015
5373.0 January 30, 2015 MONGO(1)