Skip to content

DOCS-527 improve mongo man page documentation, add .dbshell .mongorc.js #271

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 1, 2012
Merged

DOCS-527 improve mongo man page documentation, add .dbshell .mongorc.js #271

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1af11c
DOCS-527 edit, reformat, add dbshell and environment variables
Oct 1, 2012
0712733
DOCS-527 clean up formatting
Oct 1, 2012
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
177 changes: 126 additions & 51 deletions source/reference/mongo.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <port>] [--host <host>] [--eval <JavaScript>] [-u <username>] [--username <username>] [-p <password>] [--password <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.
Expand All @@ -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 <PORT>
.. cmdoption:: --port <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 <HOSTNAME>
.. cmdoption:: --host <HOSTNAME>

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 ``<HOSTNAME>``. 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 <JAVASCRIPT>
.. cmdoption:: --eval <JAVASCRIPT>

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 <USERNAME>, -u <USERNAME>
.. cmdoption:: --username <USERNAME>, -u <USERNAME>

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 <password>, -p <password>
.. cmdoption:: --password <password>, -p <password>

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 <mongo --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:: <db address>
.. cmdoption:: <db address>

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
Expand All @@ -122,15 +135,14 @@ Options

.. _mongo-shell-file:

.. option:: <file.js>
.. cmdoption:: <file.js>

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
-----

Expand All @@ -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

Expand All @@ -172,3 +184,66 @@ the :option:`--eval <mongo --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{<time_t>}.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{<time_t>}.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.