mongo.txt

.. _mongo:

=========
``mongo``
=========

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. only:: html

   .. meta::
      :description: The mongo command man page.
      :keywords: mongo, mongodb, man page, mongo process, mongo shell

Description
-----------

.. only:: (not man)

   .. binary:: mongo

:binary:`~bin.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. :binary:`~bin.mongo` also provides
a fully functional JavaScript environment for use with a MongoDB. This
document addresses the basic invocation of the :binary:`~bin.mongo` shell
and an overview of its usage.

.. _mongo-shell-options:

Options
-------

Core Options
~~~~~~~~~~~~

.. program:: mongo

.. option:: --shell

   Enables the shell interface. If you invoke the :program:`mongo` command
   and specify a JavaScript file as an argument, or use :option:`--eval` to
   specify JavaScript on the command line, the :option:`--shell` option
   provides the user with a shell prompt after the file finishes executing.


.. option:: --nodb

   Prevents the shell from connecting to any database instances. Later, to
   connect to a database within the shell, see
   :ref:`mongo-shell-new-connections`.
   


.. option:: --norc

   Prevents the shell from sourcing and evaluating :file:`~/.mongorc.js` on
   start up.
   


.. option:: --quiet

   Silences output from the shell during the connection process.
   


.. option:: --port <port>

   Specifies the port where the :binary:`~bin.mongod` or :binary:`~bin.mongos`
   instance is listening. If :option:`--port` is not specified,
   :program:`mongo` attempts to connect to port ``27017``.


.. option:: --host <hostname>

   Specifies the name of the host machine where the 
   :binary:`~bin.mongod` or :binary:`~bin.mongos` is running. If this is not specified,
   :program:`mongo` attempts to connect to a MongoDB process running on
   the localhost.
   
   To connect to a replica set, specify the :setting:`replica set name
   <~replication.replSetName>` and a seed list of set members. Use the
   following form:
   
   .. code-block:: none
   
      <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
   
   For TLS/SSL connections (``--ssl``), :program:`mongo` verifies that the
   hostname of the :binary:`~bin.mongod` or :binary:`~bin.mongos` to which you are connecting matches
   the CN or SAN of the :binary:`~bin.mongod` or :binary:`~bin.mongos`'s ``--sslPEMKeyFile`` certificate.
   If the hostname does not match the CN/SAN, :program:`mongo` will fail to
   connect.


.. option:: --eval <javascript>

   Evaluates a JavaScript expression that is specified as an argument.
   :program:`mongo` does not load its own environment when evaluating code.
   As a result many options of the shell environment are not available.


.. option:: --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.
   


.. option:: --password <password>, -p <password>

   Specifies a password with which to authenticate to a MongoDB database
   that uses authentication. Use in conjunction with the :option:`--username`
   and :option:`--authenticationDatabase` options. To force :program:`mongo` to
   prompt for a password, enter the :option:`--password` option as the
   last option and leave out the argument.


.. option:: --help, -h

   Returns information on the options and use of :program:`mongo`.


.. option:: --version

   Returns the :program:`mongo` release number.


.. option:: --verbose

   Increases the verbosity of the output of the shell during the connection
   process.
   


.. option:: --ipv6

   Enables IPv6 support. :program:`mongo` disables IPv6 by default.
   
   To connect to a MongoDB cluster via IPv6, you must specify
   both :option:`--ipv6` *and* 
   :option:`--host \<mongod/mongos IPv6 address\> <mongo --host>`
   when starting the :program:`mongo` shell.
   
   :binary:`~bin.mongod` and :binary:`~bin.mongos` disable IPv6 support
   by default. Specifying :option:`--ipv6` when connecting to a
   ``mongod/mongos`` does not enable IPv6 support on the 
   ``mongod/mongos``. For documentation on enabling IPv6 support
   on the ``mongod/mongos``, see :setting:`net.ipv6`.


.. option:: <db address>

   Specifies the "database address" of the database to connect to. For
   example:
   
   .. code-block:: sh
   
      mongo admin
   
   The above command will connect the :program:`mongo` shell to the
   :term:`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:
   
   .. code-block:: sh
   
      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 :option:`--host` or :option:`--port`.


.. option:: --disableJavaScriptJIT

   .. versionadded:: 3.2
   
   Disables use of the JavaScript engine's JIT compiler.
   


.. _mongo-shell-file:

.. option:: <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
      :program:`mongo` to prompt you for a password using
      :option:`--password`, pass the filename as the first parameter with
      :option:`--username` and :option:`--password` as the last options, as
      in the following:
   
      .. code-block:: sh
   
         mongo file.js --username username --password
   
   Use the :option:`--shell` option to return to a shell after the file
   finishes running.


.. _mongo-shell-authentication-options:

Authentication Options
~~~~~~~~~~~~~~~~~~~~~~

.. option:: --authenticationDatabase <dbname>

   Specifies the database in which the user is created.
   See :ref:`user-authentication-database`.
   

   If you do not specify a value for :option:`--authenticationDatabase`, :program:`mongo` uses the database
   specified in the connection string.


.. _mongo-shell-authentication-mechanisms:

.. option:: --authenticationMechanism <name>

   *Default*: SCRAM-SHA-1

   .. versionchanged:: 2.6
      Added support for the ``PLAIN`` and ``MONGODB-X509`` authentication
      mechanisms.
   
   .. versionchanged:: 3.0
      Added support for the ``SCRAM-SHA-1`` authentication mechanism. Changed
      default mechanism to ``SCRAM-SHA-1``.
   

   Specifies the authentication mechanism the :program:`mongo` instance uses to
   authenticate to the :binary:`~bin.mongod` or :binary:`~bin.mongos`.
   
   .. list-table::
      :header-rows: 1
      :widths: 20 40
   
      * - Value
   
        - Description
   
      * - :ref:`SCRAM-SHA-1 <authentication-scram-sha-1>`
   
        - `RFC 5802 <https://tools.ietf.org/html/rfc5802>`_ standard
          Salted Challenge Response Authentication Mechanism using the SHA1
          hash function.
   
      * - :ref:`MONGODB-CR <authentication-mongodb-cr>`
   
        - MongoDB challenge/response authentication.
   
      * - :ref:`MONGODB-X509 <security-auth-x509>`
   
        - MongoDB TLS/SSL certificate authentication.
   
      * - :ref:`GSSAPI <security-auth-kerberos>` (Kerberos)
   
        - External authentication using Kerberos. This mechanism is
          available only in `MongoDB Enterprise
          <http://www.mongodb.com/products/mongodb-enterprise?jmp=docs>`_.
   
      * - :ref:`PLAIN <security-auth-ldap>` (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
          <http://www.mongodb.com/products/mongodb-enterprise?jmp=docs>`_.


.. option:: --gssapiHostName

   .. versionadded:: 2.6
   
   Specify the hostname of a service using :doc:`GSSAPI/Kerberos
   </core/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.
   


.. option:: --gssapiServiceName

   .. versionadded:: 2.6
   
   Specify the name of the service using :doc:`GSSAPI/Kerberos
   </core/kerberos>`. Only required if the service does not use the
   default name of ``mongodb``.
   
   This option is available only in MongoDB Enterprise.
   


.. _mongo-shell-ssl:

TLS/SSL Options
~~~~~~~~~~~~~~~

.. option:: --ssl

   
   .. versionchanged:: 3.2.6
   
   Enables connection to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that has
   TLS/SSL support enabled.
   
   .. include:: /includes/extracts/ssl-facts-mongo-shell-ca.rst
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst
   


.. option:: --sslPEMKeyFile <filename>

   
   Specifies the :file:`.pem` file that contains both the TLS/SSL certificate
   and key. Specify the file name of the :file:`.pem` file using relative
   or absolute paths.
   
   This option is required when using the ``--ssl`` option to connect
   to a :binary:`~bin.mongod` or :binary:`~bin.mongos` that has
   :setting:`~net.ssl.CAFile` enabled *without*
   :setting:`~net.ssl.allowConnectionsWithoutCertificates`.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst
   


.. option:: --sslPEMKeyPassword <value>

   
   Specifies the password to de-crypt the certificate-key file (i.e.
   ``--sslPEMKeyFile``). Use the :option:`--sslPEMKeyPassword` option only if the
   certificate-key file is encrypted. In all cases, the :program:`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 :option:`--sslPEMKeyPassword` option, the :program:`mongo` will prompt for a
   passphrase. See :ref:`ssl-certificate-password`.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst


.. option:: --sslCAFile <filename>

   Specifies the :file:`.pem` file that contains the root certificate chain
   from the Certificate Authority. Specify the file name of the
   :file:`.pem` file using relative or absolute paths.
   
   .. include:: /includes/extracts/ssl-facts-mongo-shell-ca.rst
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst
   


.. option:: --sslCRLFile <filename>

   
   Specifies the :file:`.pem` file that contains the Certificate Revocation
   List. Specify the file name of the :file:`.pem` file using relative or
   absolute paths.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst
   


.. option:: --sslFIPSMode

   .. versionadded:: 2.6
   
   Directs the :program:`mongo` to use the FIPS mode of the installed OpenSSL
   library. Your system must have a FIPS compliant OpenSSL library to use
   the :option:`--sslFIPSMode` option.
   
   .. include:: /includes/note-fips-is-enterprise-only.rst


.. option:: --sslAllowInvalidCertificates

   
   Bypasses the validation checks for server certificates and allows
   the use of invalid certificates to connect.
   
   .. note::
      
      .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst
   
   .. include:: /includes/extracts/ssl-facts-invalid-cert-warning-clients.rst
   
   When using the :setting:`~net.ssl.allowInvalidCertificates` setting,
   MongoDB logs as a warning the use of the invalid certificate.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst
   


.. option:: --sslAllowInvalidHostnames

   .. versionadded:: 3.0
   
   Disables the validation of the hostnames in TLS/SSL certificates. Allows
   :program:`mongo` to connect to MongoDB instances even if the hostname in their
   certificates do not match the specified hostname.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst


Files
-----

.. _mongo-dbshell-file:

:file:`~/.dbshell`
   :binary:`~bin.mongo` maintains a history of commands in the :file:`.dbshell`
   file.

   .. note::

      :binary:`~bin.mongo` does not recorded interaction related to
      authentication in the history file, including
      :dbcommand:`authenticate` and :method:`db.createUser()`.

   .. warning::

      Versions of Windows :binary:`~bin.mongo.exe` earlier than 2.2.0 will
      save the `.dbshell` file in the :binary:`~bin.mongo.exe` working
      directory.

.. _mongo-mongorc-file:

:file:`~/.mongorc.js`
   :binary:`~bin.mongo` will read the ``.mongorc.js`` file from the home
   directory of the user invoking :binary:`~bin.mongo`. In the file, users
   can define variables, customize the :binary:`~bin.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 :option:`--eval` or
   by specifying :ref:`a .js file to mongo <mongo-shell-file>`,
   :binary:`~bin.mongo` will read the ``.mongorc.js`` file *after* the
   JavaScript has finished processing.

   Specify the :option:`--norc` option to disable
   reading ``.mongorc.js``.

.. _mongo-global-mongorc-file:

:file:`/etc/mongorc.js`
   Global ``mongorc.js`` file which the :binary:`~bin.mongo` shell
   evaluates upon start-up. If a user also has a :file:`.mongorc.js`
   file located in the :envvar:`HOME` directory, the :binary:`~bin.mongo`
   shell evaluates the global :file:`/etc/mongorc.js` file *before*
   evaluating the user's :file:`.mongorc.js` file.

   :file:`/etc/mongorc.js` must have read permission for the user
   running the shell. The :option:`--norc` option for :binary:`~bin.mongo`
   suppresses only the user's :file:`.mongorc.js` file.

   On Windows, the global :file:`mongorc.js </etc/mongorc.js>` exists
   in the :file:`%ProgramData%\\MongoDB` directory.

:file:`/tmp/mongo_edit{<time_t>}.js`
   Created by :binary:`~bin.mongo` when editing a file. If the file exists,
   :binary:`~bin.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 :binary:`~bin.mongo.exe` on Windows when editing a file. If
   the file exists, :binary:`~bin.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 :binary:`~bin.mongo` will
   read the :file:`.mongorc.js` file and write the :file:`.dbshell`
   file.

.. envvar:: HOMEDRIVE

   On Windows systems, :envvar:`HOMEDRIVE` specifies the path the
   directory where :binary:`~bin.mongo` will read the :file:`.mongorc.js`
   file and write the :file:`.dbshell` file.

.. envvar:: HOMEPATH

   Specifies the Windows path to the home directory where
   :binary:`~bin.mongo` will read the :file:`.mongorc.js` file and write
   the :file:`.dbshell` file.

.. _mongo-keyboard-shortcuts:

Keyboard Shortcuts
------------------

The :binary:`~bin.mongo` shell supports the following keyboard shortcuts:
[#multiple-bindings]_

.. list-table::
   :header-rows: 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 :binary:`~bin.mongo` shell

   * - Ctrl-D
     - Delete a char (or exit the :binary:`~bin.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

.. [#multiple-bindings] MongoDB accommodates multiple keybinding.
   Since 2.0, :binary:`~bin.mongo` includes support for basic emacs
   keybindings.

.. _mongo-usage-examples:

Use
---

Typically users invoke the shell with the :binary:`~bin.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:

.. code-block:: sh

   mongo --username <user> --password <pass> --host <host> --port 28015

Alternatively, consider the following short form:

.. code-block:: sh

   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 :option:`--port`
as needed.

To execute a JavaScript file without evaluating the :file:`~/.mongorc.js`
file before starting a shell session, use the following form:

.. code-block:: sh

   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:

.. code-block:: sh

   mongo script-file.js -u <user> -p

To print return a query as :term:`JSON`, from the system prompt using
the :option:`--eval <mongo --eval>` option, use the following form:

.. code-block:: sh

   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.

.. seealso::

   - :doc:`/reference/mongo-shell`

   - :doc:`/reference/method`

   - :doc:`/mongo`