mongodump.txt

.. _mongodump:

=============
``mongodump``
=============

.. default-domain:: mongodb

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

.. |tool-binary| replace:: mongodump

.. include:: /includes/admonition-mac-osx-sierra-restriction.rst

Synopsis
--------

:binary:`~bin.mongodump` is a utility for creating a binary export of the
contents of a database. :binary:`~bin.mongodump` can export data from
either :binary:`~bin.mongod` or :binary:`~bin.mongos` instances.

:binary:`~bin.mongodump` can be a part of a :ref:`backup strategy
<backup-with-mongodump>` with :binary:`~bin.mongorestore` for partial
backups based on a query, syncing from production to staging or
development environments, or changing the storage engine of a
standalone. However, the use of :binary:`~bin.mongodump` and
:binary:`~bin.mongorestore` as a backup strategy can be problematic for
sharded clusters and replica sets.

For an overview of :binary:`~bin.mongodump` in conjunction with
:binary:`~bin.mongorestore` part of a backup and recovery strategy, see
:doc:`/tutorial/backup-and-restore-tools`.

.. seealso:: :binary:`~bin.mongorestore`,
   :doc:`/tutorial/backup-sharded-cluster-with-database-dumps`
   and :doc:`/core/backups`.

.. _mongodump-behavior:

Behavior
--------

Data Exclusion
~~~~~~~~~~~~~~

.. include:: /includes/fact-mongodump-local-database.rst

:binary:`~bin.mongodump` only captures the documents in the database in its
backup data and does not include index data. :binary:`~bin.mongorestore` or
:binary:`~bin.mongod` must then rebuild the indexes after restoring data.

Version Compatibility
~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/warning-mongodump-compatibility-2.2.rst

.. _mongodump-read-preference:

Read Preference
~~~~~~~~~~~~~~~

Replica Sets
````````````

.. versionchanged:: 3.2.0

   The choice of target or targets for the :option:`--host <mongodump --host>`
   parameter affects the read preference of :binary:`~bin.mongodump`
   when connecting to a replica set.

   - If the string passed to ``--host`` is prefixed by the replica set name,
     :binary:`~bin.mongodump` reads from the :readmode:`primary` replica set 
     member by default. For example:

     .. code-block:: javascript

       --host "replSet/rep1.example.net:27017,rep2.example.net:27017,rep3.example.net:27017"

   - If the string passed to ``--host`` contains a list of
     :binary:`~bin.mongod` instances, but does not include the replica set
     name as a prefix to the host string, :binary:`~bin.mongodump`
     reads from the :readmode:`nearest` node by default. For example:

     .. code-block:: javascript

       --host "rep1.example.net:27017,rep2.example.net:27017,rep3.example.net:27017"

Sharded Clusters
````````````````

.. versionchanged:: 3.0.5

   For a sharded cluster where the shards are replica sets,
   :binary:`~bin.mongodump` no longer prefers reads from secondary
   members when run against the :binary:`~bin.mongos` instance.

For sharded clusters, specify the hostname of a :binary:`~bin.mongos`
for the ``--host`` option.
:binary:`~bin.mongodump` reads from the :readmode:`primary` replica set
member on each shard replica set in the cluster.

Unsharded collections in a sharded cluster are stored on a
:ref:`primary shard <primary-shard>`.
:binary:`~bin.mongodump` reads from the primary replica set member on
the primary shard for any unsharded collections. Note: each
database has its own primary shard.

Overwrite Files
~~~~~~~~~~~~~~~

.. include:: /includes/fact-mongodump-overwrite-files.rst

Data Compression Handling
~~~~~~~~~~~~~~~~~~~~~~~~~

When run against a :binary:`~bin.mongod` instance that uses the
:doc:`WiredTiger </core/wiredtiger>` storage engine,
:binary:`~bin.mongodump` outputs uncompressed data.

Working Set
~~~~~~~~~~~

:binary:`~bin.mongodump` can adversely affect performance of the
:binary:`~bin.mongod`. If your data is larger than system memory, the
:binary:`~bin.mongodump` will push the working set out of memory.

Required Access
---------------

.. include:: /includes/access-mongodump-collections.rst

Options
-------

.. include:: /includes/extracts/fact-3.0-tools-drop-dbpath-support-mongodump.rst

.. binary:: mongodump

.. program:: mongodump

.. option:: --help

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


.. option:: --verbose, -v

   Increases the amount of internal reporting returned on standard output
   or in log files. Increase the verbosity with the ``-v`` form by
   including the option multiple times, (e.g. ``-vvvvv``.)
   


.. option:: --quiet

   Runs the :program:`mongodump` in a quiet mode that attempts to limit the amount
   of output.

   This option suppresses:
   
   - output from :term:`database commands <database command>`
   
   - replication activity
   
   - connection accepted events
   
   - connection closed events


.. option:: --version

   Returns the :program:`mongodump` release number.


.. option:: --host <hostname><:port>, -h <hostname><:port>

   *Default*: localhost:27017

   Specifies a resolvable hostname for the :binary:`~bin.mongod` to which to
   connect. By default, the :program:`mongodump` attempts to connect to a MongoDB
   instance running on the localhost on port number ``27017``.
   
   To connect to a replica set, specify the
   :setting:`~replication.replSetName` and a seed list of set members, as in
   the following:
   
   .. code-block:: none
   
      <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
   
   You can always connect directly to a single MongoDB instance by
   specifying the host and port number directly.
   
   .. versionchanged:: 3.0.0
      If you use IPv6 and use the ``<address>:<port>`` format, you must
      enclose the portion of an address and port combination in
      brackets (e.g. ``[<address>]``).


.. option:: --port <port>

   *Default*: 27017

   Specifies the TCP port on which the MongoDB instance listens for
   client connections.


.. option:: --ipv6

   *Removed in version 3.0.*
   
   Enables IPv6 support and allows :program:`mongodump` to connect to the
   MongoDB instance using an IPv6 network. Prior to MongoDB 3.0, you 
   had to specify :option:`--ipv6` to use IPv6. In MongoDB 3.0 and later, IPv6
   is always enabled.


.. option:: --ssl

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


.. option:: --sslCAFile <filename>

   .. versionadded:: 2.6
   
   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.
   
   .. warning::
   
      For TLS/SSL connections (``--ssl``) to :binary:`~bin.mongod` and
      :binary:`~bin.mongos`, if the :program:`mongodump` runs without the
      :option:`--sslCAFile`, :program:`mongodump` will not attempt
      to validate the server certificates. This creates a vulnerability
      to expired :binary:`~bin.mongod` and :binary:`~bin.mongos` certificates as
      well as to foreign processes posing as valid :binary:`~bin.mongod` or
      :binary:`~bin.mongos` instances. Ensure that you *always* specify the
      CA file to validate the server certificates in cases where
      intrusion is a possibility.
   
   .. include:: /includes/extracts/ssl-facts-see-more.rst


.. option:: --sslPEMKeyFile <filename>

   .. versionadded:: 2.6
   
   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 :option:`--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>

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


.. option:: --sslCRLFile <filename>

   .. versionadded:: 2.6
   
   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:: --sslAllowInvalidCertificates

   .. versionadded:: 2.6
   
   Bypasses the validation checks for server certificates and allows
   the use of invalid certificates. When using the
   :setting:`~net.ssl.allowInvalidCertificates` setting, MongoDB logs as a
   warning the use of the invalid certificate.
   
   .. include:: /includes/extracts/ssl-facts-x509-invalid-certificate.rst
   
   .. include:: /includes/extracts/ssl-facts-invalid-cert-warning-clients.rst
   
   .. 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:`mongodump` 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


.. option:: --sslFIPSMode

   .. versionadded:: 2.6
   
   Directs the :program:`mongodump` 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:: --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 ``--username`` and
   ``--authenticationDatabase`` options.
   
   .. versionchanged:: 3.0.0
   
      If you do not specify an argument for :option:`--password`, :program:`mongodump` returns
      an error.
   
   .. versionchanged:: 3.0.2
   
      If you wish :program:`mongodump` to prompt the user
      for the password, pass the :option:`--username` option without
      :option:`--password` or specify an empty string as the :option:`--password` value,
      as in ``--password ""`` .


.. option:: --authenticationDatabase <dbname>

   If you do not specify an authentication database, :program:`mongodump`
   assumes that the database specified to export holds the user's credentials.


.. 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:`mongodump` 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:: --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.
   


.. 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:: --db <database>, -d <database>

   Specifies a database to backup. If you do not specify a database,
   :binary:`~bin.mongodump` copies all databases in this instance into the dump
   files.
   


.. option:: --collection <collection>, -c <collection>

   Specifies a collection to backup. If you do not specify a collection,
   this option copies all collections in the specified database or instance
   to the dump files.
   


.. option:: --query <json>, -q <json>

   Provides a :term:`JSON document` as a query that optionally limits the
   documents included in the output of :binary:`~bin.mongodump`.
   
   .. include:: /includes/fact-quote-command-line-query.rst
   


.. option:: --queryFile <path>

   .. versionadded:: 3.2
   
   Specifies the path to a file containing a JSON document as a query
   filter that limits the documents included in the output of
   :binary:`~bin.mongodump`. :option:`--queryFile` enables you to create query filters that
   are too large to fit in your terminal's buffer.


.. option:: --forceTableScan

   Forces :binary:`~bin.mongodump` to scan the data store directly: typically,
   :binary:`~bin.mongodump` saves entries as they appear in the index of
   the ``_id`` field. If you specify a query :option:`--query`,
   :program:`mongodump` will use the most appropriate index to support that query.
   
   Use :option:`--forceTableScan` to skip the index and scan the data directly. Typically
   there are two cases where this behavior is preferable to the
   default:
   
   1. If you have key sizes over 800 bytes that would not be present in the
      ``_id`` index.
   
   2. Your database uses a custom ``_id`` field.
   
   When you run with :option:`--forceTableScan`, :binary:`~bin.mongodump` does
   not use :operator:`$snapshot`. As a result, the dump produced by
   :binary:`~bin.mongodump` can reflect the state of the database at many
   different points in time.
   
   .. important:: Use :option:`--forceTableScan` with extreme caution and
      consideration.


.. option:: --gzip

   .. versionadded:: 3.2
   
   Compresses the output. If :binary:`~bin.mongodump` outputs to the dump
   directory, the new feature compresses the individual files. The files
   have the suffix ``.gz``.
   
   If :binary:`~bin.mongodump` outputs to an archive file or the standard
   out stream, the new feature compresses the archive file or the data
   output to the stream.
   


.. option:: --out <path>, -o <path>

   Specifies the directory where :binary:`~bin.mongodump` will write
   :term:`BSON` files for the dumped databases. By default,
   :binary:`~bin.mongodump` saves output files in a directory named
   ``dump`` in the current working directory.
   
   To send the database dump to standard output, specify "``-``" instead of
   a path. Write to standard output if you want process the output before
   saving it, such as to use ``gzip`` to compress the dump. When writing
   standard output, :binary:`~bin.mongodump` does not write the metadata that
   writes in a ``<dbname>.metadata.json`` file when writing to files
   directly.
   
   You cannot use the ``--archive`` option with the
   :option:`--out` option.
   


.. option:: --archive <file or null>

   .. versionadded:: 3.2
   
   Writes the output to a single archive file or to the standard output
   (``stdout``).
   
   To output the dump to an archive file, run :binary:`~bin.mongodump` with the new
   ``--archive`` option and the archive filename.
   
   To output the dump to the standard output stream in order to pipe to
   another process, run :binary:`~bin.mongodump` with the ``archive`` option
   but *omit* the filename.
   
   You cannot use the ``--archive`` option with the
   :option:`--out` option.
   


.. option:: --repair

   .. filler to prevent giza bug
   .. note::
   
      When repairing a database, you should use :option:`mongod --repair`
      rather than this option. For instructions on repairing a database,
      refer to
      :doc:`/tutorial/recover-data-following-unexpected-shutdown`.
   
   Changes the behavior of :program:`mongodump` to only write valid data and
   exclude data that may be in an invalid state as a result of an
   improper shutdown or :program:`mongod` crash.
   
   :option:`--repair` is different from :option:`mongod --repair`, and may produce
   a large amount of duplicate documents. It is only available for use
   against :binary:`~bin.mongod` instances using the ``mmapv1`` storage
   engine. You cannot run :option:`--repair` against :binary:`~bin.mongos`, or against
   :binary:`~bin.mongod` instances that use the ``wiredTiger`` storage
   engine.
   
   For instructions on repairing a database, refer to
   :doc:`/tutorial/recover-data-following-unexpected-shutdown`.


.. option:: --oplog

   Creates a file named :file:`oplog.bson` as part of the
   :binary:`~bin.mongodump` output. The :file:`oplog.bson` file, located in
   the top level of the output directory, contains oplog entries that
   occur during the :binary:`~bin.mongodump` operation. This file provides
   an effective point-in-time snapshot of the state of a
   :binary:`~bin.mongod` instance. To restore to a specific point-in-time
   backup, use the output created with this option in conjunction with
   :option:`mongorestore --oplogReplay`.
   
   Without :option:`--oplog`, if there are write operations during the dump
   operation, the dump will not reflect a single moment in time. Changes
   made to the database during the update process can affect the output of
   the backup.
   
   :option:`--oplog` has no effect when running :binary:`~bin.mongodump`
   against a :binary:`~bin.mongos` instance to dump the entire contents of a
   sharded cluster. However, you can use :option:`--oplog` to dump
   individual shards.
   
   :option:`--oplog` only works against nodes that maintain an
   :term:`oplog`. This includes all members of a replica set, as well as
   :term:`master` nodes in master/slave replication deployments.
   
   :option:`--oplog` does not dump the oplog collection.


.. option:: --dumpDbUsersAndRoles

   Includes user and role definitions in the database's dump directory
   when performing :binary:`~bin.mongodump` on a specific database. This
   option applies only when you specify a database in the
   :option:`--db` option. MongoDB always includes user and role
   definitions when :binary:`~bin.mongodump` applies to an entire instance
   and not just a specific database.
   


.. option:: --excludeCollection string

   .. versionadded:: 3.0
   
   Excludes the specified collection from the :program:`mongodump` output.
   To exclude multiple collections, specify the :option:`--excludeCollection` multiple times.


.. option:: --excludeCollectionsWithPrefix string

   .. versionadded:: 3.0
   
   Excludes all collections with a specified prefix from the :program:`mongodump`
   outputs. To specify multiple prefixes, specify the :option:`--excludeCollectionsWithPrefix` multiple
   times.


.. option:: --numParallelCollections int, -j int

   *Default*: 4

   Number of collections :program:`mongodump` should export
   in parallel.


.. option:: --readPreference <string>

   Specify the :ref:`read preference<replica-set-read-preference>` for 
   :program:`mongodump`. 
   
   See :ref:`replica-set-read-preference-modes`.
   
   :program:`mongodump` defaults to :readmode:`primary` 
   :ref:`read preference <replica-set-read-preference>` when connected to a 
   :binary:`~bin.mongos` or a :term:`replica set`.
   
   Otherwise, :program:`mongodump` defaults to :readmode:`nearest`.
   
   .. include:: /includes/warning-read-preference-mongos.rst

   See :ref:`mongodump-read-preference`.
   


Examples
--------

``mongodump`` a Collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following operation creates a dump file that contains only the
collection named ``collection`` in the database named ``test``. In
this case the database is running on the local interface on port
``27017``:

.. code-block:: sh

   mongodump  --db test --collection collection


``mongodump`` a Database Excluding Specified Collections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The following operation dumps all collections in the ``test`` database
except for ``users`` and ``salaries``:

.. code-block:: sh

   mongodump  --db test --excludeCollection=users --excludeCollection=salaries

``mongodump`` with Access Control
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In the next example, :binary:`~bin.mongodump` creates a database dump
located at ``/opt/backup/mongodump-2011-10-24``, from a database
running on port ``37017`` on the host ``mongodb1.example.net`` and
authenticating using the username ``user`` and the password
``pass``, as follows:

.. code-block:: sh

   mongodump --host mongodb1.example.net --port 37017 --username user --password pass --out /opt/backup/mongodump-2011-10-24

.. _mongodump-example-archive-file:

Output to an Archive File
~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 3.2

To output the dump to an archive file, run :binary:`~bin.mongodump` with the
``--archive`` option and the archive filename. For example, the following
operation creates a file ``test.20150715.archive`` that contains the dump
of the ``test`` database.

.. code-block:: sh

   mongodump --archive=test.20150715.archive --db test

.. _mongodump-example-archive-stdout:

Output an Archive to Standard Output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 3.2

To output the archive to the standard output stream in order to pipe to
another process, run :binary:`~bin.mongodump` with the ``archive``
option but *omit* the filename:

.. code-block:: sh

   mongodump --archive --db test --port 27017 | mongorestore --archive --port 27018

.. note::

   You cannot use the ``--archive`` option with the
   :option:`--out` option.

.. _mongodump-example-gzip:

Compress the Output
~~~~~~~~~~~~~~~~~~~

To compress the files in the output dump directory, run
:binary:`~bin.mongodump` with the new ``--gzip`` option. For example,
the following operation outputs compressed files into the default
``dump`` directory.

.. code-block:: sh

   mongodump --gzip --db test

To compress the archive file output by :binary:`~bin.mongodump`, use the
``--gzip`` option in conjunction with the :option:`--archive`
option, specifying the name of the compressed file.

.. code-block:: sh

   mongodump --archive=test.20150715.gz --gzip --db test