356 lines
11 KiB
Groff
356 lines
11 KiB
Groff
.TH "MONGODUMP" "1" "March 14, 2013" "2.2.3" "mongodb-manual"
|
|
.SH NAME
|
|
mongodump \- MongoDB
|
|
.
|
|
.nr rst2man-indent-level 0
|
|
.
|
|
.de1 rstReportMargin
|
|
\\$1 \\n[an-margin]
|
|
level \\n[rst2man-indent-level]
|
|
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
-
|
|
\\n[rst2man-indent0]
|
|
\\n[rst2man-indent1]
|
|
\\n[rst2man-indent2]
|
|
..
|
|
.de1 INDENT
|
|
.\" .rstReportMargin pre:
|
|
. RS \\$1
|
|
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
|
|
. nr rst2man-indent-level +1
|
|
.\" .rstReportMargin post:
|
|
..
|
|
.de UNINDENT
|
|
. RE
|
|
.\" indent \\n[an-margin]
|
|
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.nr rst2man-indent-level -1
|
|
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
|
|
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
|
|
..
|
|
.\" Man page generated from reStructuredText.
|
|
.
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fI\%mongodump\fP is a utility for creating a binary export of the
|
|
contents of a database. Consider using this utility as part an
|
|
effective \fBbackup strategy\fP. Use in
|
|
conjunction with \fBmongorestore\fP to provide restore
|
|
functionality.
|
|
.IP Note
|
|
The format of data created by \fI\%mongodump\fP tool from the
|
|
2.2 distribution or later is different and incompatible with
|
|
earlier versions of \fBmongod\fP.
|
|
.RE
|
|
.IP "See also"
|
|
.sp
|
|
"\fBmongorestore\fP" and "\fB/administration/backups\fP".
|
|
.RE
|
|
.SH OPTIONS
|
|
.INDENT 0.0
|
|
.TP
|
|
.B mongodump
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-help
|
|
Returns a basic help and usage text.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-verbose, \-v
|
|
Increases the amount of internal reporting returned on the command
|
|
line. Increase the verbosity with the \fB\-v\fP form by including the
|
|
option multiple times, (e.g. \fB\-vvvvv\fP.)
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-version
|
|
Returns the version of the \fI\%mongodump\fP utility and exits.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-host <hostname><:port>
|
|
Specifies a resolvable hostname for the \fBmongod\fP that you wish to
|
|
use to create the database dump. By default \fI\%mongodump\fP will
|
|
attempt to connect to a MongoDB process ruining on the localhost
|
|
port number \fB27017\fP.
|
|
.sp
|
|
Optionally, specify a port number to connect a MongoDB instance
|
|
running on a port other than \fB27017\fP.
|
|
.sp
|
|
To connect to a replica set, use the \fI\%--host\fP
|
|
argument with a setname, followed by a slash and a comma\-separated
|
|
list of host names and port numbers. The \fI\%mongodump\fP
|
|
utility will, given the seed of at least one connected set member,
|
|
connect to the primary member of that set. This option would resemble:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongodump \-\-host repl0/mongo0.example.net,mongo0.example.net:27018,mongo1.example.net,mongo2.example.net
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
You can always connect directly to a single MongoDB instance by
|
|
specifying the host and port number directly.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-port <port>
|
|
Specifies the port number, if the MongoDB instance is not running
|
|
on the standard port. (i.e. \fB27017\fP) You may also specify a port
|
|
number using the \fI\%--host\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ipv6
|
|
Enables IPv6 support that allows \fI\%mongodump\fP to connect to
|
|
the MongoDB instance using an IPv6 network. All MongoDB programs
|
|
and processes, including \fI\%mongodump\fP, disable IPv6 support
|
|
by default.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-ssl
|
|
New in version 2.4: MongoDB added support for SSL connections to \fBmongod\fP
|
|
instances in mongodump.
|
|
.IP Note
|
|
SSL support in mongodump is not compiled into the default
|
|
distribution of MongoDB. See \fB/administration/ssl\fP for more
|
|
information on SSL and MongoDB.
|
|
.sp
|
|
Additionally, mongodump does not support connections to
|
|
\fBmongod\fP instances that require client certificate
|
|
validation.
|
|
.RE
|
|
.sp
|
|
Allows \fI\%mongodump\fP to connect to \fBmongod\fP
|
|
instance over an SSL connection.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-username <username>, \-u <username>
|
|
Specifies a username to authenticate to the MongoDB instance, if
|
|
your database requires authentication. Use in conjunction with the
|
|
\fI\%--password\fP option to supply a
|
|
password.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-password <password>, \-p <password>
|
|
Specifies a password to authenticate to the MongoDB instance. Use
|
|
in conjunction with the \fI\%--username\fP
|
|
option to supply a username.
|
|
.sp
|
|
If you specify a \fI\%--username\fP
|
|
without the \fI\%--password\fP option, \fI\%mongodump\fP will
|
|
prompt for a password interactively.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationDatabase <dbname>
|
|
New in version 2.4.
|
|
.sp
|
|
Specifies the database that holds the user\(aqs (e.g
|
|
\fI\%--username\fP) credentials.
|
|
.sp
|
|
By default, \fI\%mongodump\fP assumes that the database specified to the
|
|
\fI\%--db\fP argument holds the user\(aqs credentials, unless you
|
|
specify \fI\%--authenticationDatabase\fP.
|
|
.sp
|
|
See \fBuserSource\fP,
|
|
\fB/reference/privilege\-documents\fP and
|
|
\fB/reference/user\-privileges\fP for more information about
|
|
delegated authentication in MongoDB.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationMechanism <name>
|
|
New in version 2.4.
|
|
.sp
|
|
Specifies the authentication mechanism. By default, the
|
|
authentication mechanism is \fBMONGODB\-CR\fP, which is the MongoDB
|
|
challenge/response authentication mechanism. In the MongoDB Subscriber Edition,
|
|
\fI\%mongodump\fP also includes support for \fBGSSAPI\fP to handle
|
|
Kerberos authentication.
|
|
.sp
|
|
See \fB/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication\fP
|
|
for more information about Kerberos authentication.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-dbpath <path>
|
|
Specifies the directory of the MongoDB data files. If used, the
|
|
\fI\%--dbpath\fP option enables \fI\%mongodump\fP to attach
|
|
directly to local data files and copy the data without the
|
|
\fBmongod\fP. To run with \fI\%--dbpath\fP,
|
|
\fI\%mongodump\fP needs to restrict access to the data
|
|
directory: as a result, no \fBmongod\fP can access the same
|
|
path while the process runs.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-directoryperdb
|
|
Use the \fI\%--directoryperdb\fP in conjunction with the
|
|
corresponding option to \fBmongod\fP. This option allows
|
|
\fI\%mongodump\fP to read data files organized with each
|
|
database located in a distinct directory. This option is only
|
|
relevant when specifying the \fI\%--dbpath\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-journal
|
|
Allows \fI\%mongodump\fP operations to use the durability
|
|
\fIjournal\fP to ensure that the export is in a
|
|
consistent state. This option is only relevant when specifying the
|
|
\fI\%--dbpath\fP option.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-db <db>, \-d <db>
|
|
Use the \fI\%--db\fP option to specify a database for
|
|
\fI\%mongodump\fP to backup. If you do not specify a DB,
|
|
\fI\%mongodump\fP copies all databases in this instance into the
|
|
dump files. Use this option to backup or copy a smaller subset of
|
|
your data.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-collection <collection>, \-c <collection>
|
|
Use the \fI\%--collection\fP option to specify a collection for
|
|
\fI\%mongodump\fP to backup. If you do not specify a collection,
|
|
this option copies all collections in the specified database or
|
|
instance to the dump files. Use this option to backup or copy a
|
|
smaller subset of your data.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-out <path>, \-o <path>
|
|
Specifies a path where \fI\%mongodump\fP and store the output
|
|
the database dump. To output the database dump to standard output,
|
|
specify a \fB\-\fP rather than a path.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-query <json>, \-q <json>
|
|
Provides a query to limit (optionally) the documents included in
|
|
the output of \fI\%mongodump\fP.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-oplog
|
|
Use this option to ensure that \fI\%mongodump\fP creates a dump
|
|
of the database that includes an \fIoplog\fP, to create a
|
|
point\-in\-time snapshot of the state of a \fBmongod\fP instance. To
|
|
restore to a specific point\-in\-time backup, use the output created
|
|
with this option in conjunction with \fImongorestore \-\-oplogReplay\fP.
|
|
.sp
|
|
Without \fI\%--oplog\fP, 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.
|
|
.sp
|
|
\fI\%--oplog\fP has no effect when running \fI\%mongodump\fP
|
|
against a \fBmongos\fP instance to dump the entire contents of
|
|
a sharded cluster. However, you can use \fI\%--oplog\fP to dump
|
|
individual shards.
|
|
.IP Note
|
|
\fI\%--oplog\fP only works against nodes that maintain a
|
|
\fIoplog\fP. This includes all members of a replica set, as
|
|
well as \fImaster\fP nodes in master/slave replication
|
|
deployments.
|
|
.RE
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-repair
|
|
Use this option to run a repair option in addition to dumping the
|
|
database. The repair option attempts to repair a database that may
|
|
be in an inconsistent state as a result of an improper shutdown or
|
|
\fBmongod\fP crash.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-forceTableScan
|
|
Forces \fI\%mongodump\fP to scan the data store directly:
|
|
typically, \fI\%mongodump\fP saves entries as they appear in the
|
|
index of the \fB_id\fP field. Use \fI\%--forceTableScan\fP to skip
|
|
the index and scan the data directly. Typically there are two cases
|
|
where this behavior is preferable to the default:
|
|
.INDENT 7.0
|
|
.IP 1. 3
|
|
If you have key sizes over 800 bytes that would not be present
|
|
in the \fB_id\fP index.
|
|
.IP 2. 3
|
|
Your database uses a custom \fB_id\fP field.
|
|
.UNINDENT
|
|
.sp
|
|
When you run with \fI\%--forceTableScan\fP, \fI\%mongodump\fP
|
|
does not use \fB$snapshot\fP. As a result, the dump produced
|
|
by \fI\%mongodump\fP can reflect the state of the database at
|
|
many different points in time.
|
|
.IP Warning
|
|
Use \fI\%--forceTableScan\fP with extreme caution
|
|
and consideration.
|
|
.RE
|
|
.IP Warning
|
|
Changed in version 2.2: When used in combination with \fBfsync\fP or
|
|
\fBdb.fsyncLock()\fP, \fBmongod\fP may block some
|
|
reads, including those from \fI\%mongodump\fP, when
|
|
queued write operation waits behind the \fBfsync\fP
|
|
lock.
|
|
.RE
|
|
.UNINDENT
|
|
.SH BEHAVIOR
|
|
.sp
|
|
When running \fI\%mongodump\fP against a \fBmongos\fP instance
|
|
where the \fIsharded cluster\fP consists of \fIreplica sets\fP, the \fIread preference\fP of the operation will prefer reads
|
|
from \fIsecondary\fP members of the set.
|
|
.SH USAGE
|
|
.sp
|
|
See the \fB/tutorial/backup\-databases\-with\-binary\-database\-dumps\fP
|
|
for a larger overview of \fI\%mongodump\fP usage. Also see the
|
|
"\fBmongorestore\fP" document for an overview of the
|
|
\fBmongorestore\fP, which provides the related inverse
|
|
functionality.
|
|
.sp
|
|
The following command, creates a dump file that contains only the
|
|
collection named \fBcollection\fP in the database named \fBtest\fP. In
|
|
this case the database is running on the local interface on port
|
|
\fB27017\fP:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongodump \-\-collection collection \-\-db test
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
In the next example, \fI\%mongodump\fP creates a backup of the
|
|
database instance stored in the \fB/srv/mongodb\fP directory on the
|
|
local machine. This requires that no \fBmongod\fP instance is
|
|
using the \fB/srv/mongodb\fP directory.
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongodump \-\-dbpath /srv/mongodb
|
|
.ft P
|
|
.fi
|
|
.sp
|
|
In the final example, \fI\%mongodump\fP creates a database dump
|
|
located at \fB/opt/backup/mongodump\-2011\-10\-24\fP, from a database
|
|
running on port \fB37017\fP on the host \fBmongodb1.example.net\fP and
|
|
authenticating using the username \fBuser\fP and the password
|
|
\fBpass\fP, as follows:
|
|
.sp
|
|
.nf
|
|
.ft C
|
|
mongodump \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass /opt/backup/mongodump\-2011\-10\-24
|
|
.ft P
|
|
.fi
|
|
.SH AUTHOR
|
|
MongoDB Documentation Project
|
|
.SH COPYRIGHT
|
|
2011-2013, 10gen, Inc.
|
|
.\" Generated by docutils manpage writer.
|
|
.
|