diff --git a/source/reference/mongo.txt b/source/reference/mongo.txt index d2e3fd8b02c..6ff7fe63982 100644 --- a/source/reference/mongo.txt +++ b/source/reference/mongo.txt @@ -1,20 +1,30 @@ -.. _mongo: +================ +mongo +================ +.. only:: html + .. meta:: + :description: The mongo command man page. + :keywords: mongo, mongodb, man page, mongo process, mongo shell + .. default-domain:: mongodb -================ -:program:`mongo` -================ +.. _mongo: Synopsis -------- +.. describe:: mongo [--shell] [--nodb] [--norc] [--quiet] [--port ] [--host ] [--eval ] [-u ] [--username ] [-p ] [--password ] [--help] [-h] [--version] [--verbose] [--ipv6] [database] [file.js] + +Description +----------- + :program:`mongo` is an interactive JavaScript shell interface to -MongoDB. :program:`mongo` provides a powerful administrative interface -for systems administrators as well as an way to test queries and +MongoDB. The :program:`mongo` command provides a powerful interface +for systems administrators as well as a way to test queries and operations directly with the database. To increase the flexibility of -:program:`mongo`, the shell provides a fully functional JavaScript -environment. This manual page, addresses the basic invocation of the +the :program:`mongo` command, the shell provides a fully functional JavaScript +environment. This document addresses the basic invocation of the :program:`mongo` shell and an overview of its usage. .. STUB -- This manual contains more extensive documentation of :program:`mongo` in the ":doc:`/mongo`" document. @@ -26,86 +36,89 @@ Options .. program:: mongo -.. option:: --shell - - If you invoke the :program:`mongo` and specify a :term:`JavaScript` - file as an argument, or ":option:`mongo --eval`" the - :option:`--shell` provides the user with a shell prompt after the - file finishes executing. +.. cmdoption:: --shell -.. option:: --nodb + Enables the shell interface after a :term:`JavaScript` file is evaluated. + If you invoke the :program:`mongo` command and specify a JavaScript + file as an argument, or use :option:`mongo --eval` to specify + JavaScript on the command line, the :option:`mongo --shell` option + provides the user with a shell prompt after the file finishes + executing. - Use this option to prevent the shell from connecting to any - database instance. +.. cmdoption:: --nodb -.. option:: --norc + Prevents the shell from connecting to any database instances. - By default :program:`mongo` runs the ``~/.mongorc.js`` file when it - starts. Use this option to prevent the shell from sourcing this - file on start up. +.. cmdoption:: --norc -.. option:: --quiet + Prevents the shell from sourcing and evaluating + :file:`~/.mongorc.js` on startup. + +.. cmdoption:: --quiet Silences output from the shell during the connection process. -.. option:: --port +.. cmdoption:: --port - Specify the port where the :program:`mongod` or :program:`mongos` + Specifies the port where the :program:`mongod` or :program:`mongos` instance is listening. Unless specified :program:`mongo` connects to :program:`mongod` instances on port 27017, which is the default :program:`mongod` port. -.. option:: --host +.. cmdoption:: --host - Specific the host where the :program:`mongod` or :program:`mongos` is running to + specifies the host where the :program:`mongod` or :program:`mongos` is running to connect to as ````. By default :program:`mongo` will attempt - to connect to MongoDB process running on the localhost. + to connect to a MongoDB process running on the localhost. -.. option:: --eval +.. cmdoption:: --eval - Evaluates a JavaScript specified as an argument to this + Evaluates a JavaScript expression specified as an argument to this option. :program:`mongo` does not load its own environment when evaluating - code: as a result many convinces of the shell environment are not + code: as a result many options of the shell environment are not available. -.. option:: --username , -u +.. cmdoption:: --username , -u - Specify a username to authenticate to the MongoDB instance, if your - database requires authentication. Use in conjunction with the + Specifies a username to authenticate to the MongoDB instance. + Use in conjunction with the :option:`mongo --password` option to supply a password. + If you specify a username and password but the default database + or the specified database do not require authentication, + :program:`mongo` will exit with an exception. -.. option:: --password , -p +.. cmdoption:: --password , -p - Specify a password to authenticate to the MongoDB instance, if your - database requires authentication. Use in conjunction with the + Specifies a password to authenticate to the MongoDB instance. + Use in conjunction with the :option:`mongo --username` option to supply a username. If you specify a :option:`--username ` without the - :option:`--password` option, :program:`mongo` will prompt for a - password interactively. + :option:`mongo --password` option, :program:`mongo` will prompt for a + password interactively if authentication is required. -.. option:: --help, -h +.. cmdoption:: --help, -h Returns a basic help and usage text. -.. option:: --version +.. cmdoption:: --version Returns the version of the shell. -.. option:: --verbose +.. cmdoption:: --verbose Increases the verbosity of the output of the shell during the connection process. -.. option:: --ipv6 +.. cmdoption:: --ipv6 Enables IPv6 support that allows :program:`mongo` to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes, including :program:`mongo`, disable IPv6 support by default. -.. option:: +.. cmdoption:: - Specify the "database address" of the database to connect to. For + Specifies the "database address" of the database to connect to. For example: :: mongo admin @@ -122,15 +135,14 @@ Options .. _mongo-shell-file: -.. option:: +.. cmdoption:: - Optionally, specify a JavaScript file as the final argument to the - shell. The shell will run the file and then exit. Use the - :option:`mongo --shell` to return to a shell after the file + Specifies a JavaScript file to run and then exit. + Must be the last option specified. + Use the + :option:`mongo --shell` option to return to a shell after the file finishes running. - This should be the last address - Usage ----- @@ -156,7 +168,7 @@ values for your situation and substitute or omit the :option:`--port` as needed. To execute a JavaScript file without evaluating the ``~/.mongorc.js`` -file before starting a sell session, use the following form: +file before starting a shell session, use the following form: .. code-block:: sh @@ -172,3 +184,66 @@ the :option:`--eval ` option, use the following form: Note the use of single quotes (e.g. ``'``) to enclose the JavaScript, as well as the additional JavaScript required to generate this output. + +Files +----- + +:file:`~/.dbshell` + + :program:`mongo` maintains a history of commands in the `.dbshell` + file. + + .. note: + + Authentication commands (such as :dbcommand:`authenticate`, + :method:`db.addUser()`) will not be saved in the history file. + + .. warning: + + Versions of Windows :command:`mongo.exe` earlier than 2.2.0 + will save the `.dbshell` file in the :command:`mongo.exe` + working directory. + +:file:`~/.mongorc.js` + + :program:`mongo` will read `.mongorc.js` from the home directory + of the user invoking :program:`mongo`. + Specify the :option:`mongo --norc` option to disable + reading `.mongorc.js`. + +:file:`/tmp/mongo_edit{}.js` + + Created by :program:`mongo` when editing a file. If the file + exists :program:`mongo` will append an integer from 1 to 10 to + the time value to attempt to create a unique file. + +:file:`%TEMP%\mongo_edit{}.js` + + Created by :command:`mongo.exe` on Windows when editing a file. + If the file + exists :program:`mongo` will append an integer from 1 to 10 to + the time value to attempt to create a unique file. + +Environment +----------- + +.. envvar:: EDITOR + + Specifies the path to an editor to use with the `edit` shell command. + A JavaScript variable `EDITOR` will override the value of + :envvar:`EDITOR`. + +.. envvar:: HOME + + specifies the path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to. + +.. envvar:: HOMEDRIVE + + specifies the Windows path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to. + +.. envvar:: HOMEPATH + + specifies the Windows path to the home directory where :file:`.mongorc.js` will be + read from and :file:`.dbshell` will be written to.