Skip to content

Latest commit

 

History

History
161 lines (111 loc) · 4.11 KB

mtransfer.rst

File metadata and controls

161 lines (111 loc) · 4.11 KB

mtransfer

mtransfer allows WiredTiger databases to be exported from one MongoDB instance and imported into another.

Caveats

The mtransfer script is EXPERIMENTAL and has a number of important usage caveats:

  • MongoDB must be started with the --directoryperdb flag.
  • mtransfer does not work with sharding, the encrypted storage engine, or MMAPv1 data files.
  • To export or import a database, MongoDB must not be running using either the source or destination database paths.
  • A database must be imported to all nodes in a replica set or query results will be inconsistent.
  • A database cannot be imported to any node in the replica set it was exported from. Collections have unique identifiers, and this would violate that uniqueness.
  • mtransfer currently only supports database files compressed with the default snappy library.

While there are some sanity checks built into the script, manipulating MongoDB files directly is inherently dangerous. Take care to test and backup your data.

Installation

The mtransfer script requires the wiredtiger Python library which is currently not installed by default with mtools.

The wiredtiger library can be installed via pip3 or built from source, but in either case requires:

  • A C compiler.
  • The snappy and zlib development packages installed.

To install via pip3 use either of:

pip3 install 'mtools[mtransfer]'
pip3 install wiredtiger

If you are encountering errors using or installing the wiredtiger module via pip3, you may need to Build and install WiredTiger from source.

Usage

mtransfer [-h] [--version] [--verbose] [--dbpath DBPATH]
                  {export,import} database

General Parameters

Help

-h, --help
shows the help text and exits.

Version

--version
shows the version number and exits.

Verbosity

--verbose
shows extra information

Commands

mtransfer reads or writes the data files in a MongoDB instance using the WiredTiger storage engine.

Database Path

--dbpath path the path to the MongoDB database files (defaults to the current working directory where the script is run).

Command

export creates a file mtransfer.bson in the specified database directory. This must be copied along with the other files in the directory to the destination server(s).

import reads the mtransfer.bson file from the specified database directory and updates MongoDB's metadata to include the database.

Database

The name of the database to export / import. The MongoDB database name must match the directory name on disk for the export, and the MongoDB database name will be set to the directory name for the import.

Example Database Transfer and Rename

On the origin server

Before starting, ensure MongoDB is not running.

  1. Change into the origin directory and create 'olddb/mtransfer.bson' with exported metadata:
cd /from/dbpath
mtransfer export olddb
  1. Copy the database files to the destination
rsync -av olddb destination:/to/dbpath

On the destination server

Before starting, ensure MongoDB is not running.

  1. Rename the database directory (optional)
cd /to/dbpath
mv olddb newdb
  1. Import the database (with the new name, if renamed)
mtransfer import newdb
  1. Start mongod and confirm the transferred database is now available.

Disclaimer

This software is not supported by MongoDB, Inc. under any of their commercial support subscriptions or otherwise. Any usage of mtools is at your own risk. Bug reports, feature requests and questions can be posted in the Issues section on GitHub.