Transferring data

Requires Pro — migrating (MigrateData), exporting (ExportData) and importing (ImportData). See Plans and Pro features.

Copying a database to another connection, writing one out to files, and reading those files back. All three are the same dialog, opened from Backup and transfer on a database or a collection in the explorer.

The three transfers

Transfer	What it does
Migrate	Copies to another connection or another database. Move deletes the source afterwards
Export	Writes to BSON, JSON or CSV files
Import	Reads those files back

The scope is whatever you opened the menu on: on a database every collection goes, on a collection only that one. Collections whose names begin with system. are never included.

Backups are on the same menu and are a different thing — an archive built to be restored, rather than files built to be read by something else. If your source is a relational database rather than MongoDB, see Migrating from SQL.

Migrate goes through a backup, and verifies the copy

A migration is not a document-by-document copy loop. It takes a backup of the source into a temporary directory and restores it into the target, which is why it carries what a backup carries: collection options and indexes, not only documents. The temporary archive is deleted afterwards, whether the transfer finished or failed.

Then it checks the result before reporting success:

the number of collections and documents the restore reported against what the backup wrote,
the number of indexes against the archive's manifest,
and the document count of every collection, counted in the target database itself rather than taken from the restore.

A mismatch in any of them fails the transfer.

Copy or Move

Copy leaves the source alone. Move deletes it — the database, or the one collection you started from — and only after the copy has been verified.

Move is a deletion, and the dialog makes you say so

Choosing Move shows a warning and a second checkbox — I understand that the source will be deleted — and the button does nothing until it is ticked. If verification fails, the source is left where it is and the message says so. If the copy verified but the source could not be removed, that is reported too: you then have the data in both places, which is the safe half of the failure.

What a migration refuses

The same database on the same connection as source and target.
A source or target connection that is not available.
A source with nothing in it.
Collections in the target that have the same names as the ones arriving — unless Replace conflicting collections is ticked. The message names them. With it ticked, those collections are dropped and rewritten.
A target connection marked read-only. The guard is on the connection being written to; the source's setting does not matter.

Export writes one file per collection

The format decides the file layout as well as its contents:

a collection is written to the file you name,
a database is written to a directory, one file per collection, named after the collection with the format's extension.

Format	What is in the file
BSON	Documents one after another, the same layout as a `mongodump` collection file
JSON	Newline-delimited canonical Extended JSON — one document per line, what `mongoimport` calls JSON Lines
CSV	Every value is Extended JSON, so dates and `ObjectId`s survive the round trip; the header is the union of the fields of all documents

These files are written by the same writer as an exported query result, because the import path reads them back. A second writer that drifted would produce files this application cannot read.

A collection export is assembled in memory

Exporting a query result streams each batch to disk and releases it. Exporting a collection or a database does not: it reads the collection into memory first and then writes the file. For a collection large enough to matter, take a backup instead, or export a query result in pieces.

A failed collection export also leaves its partial file behind. The result export deletes its own; this path does not.

Import reads a file, or a directory of them

On a collection, import reads the single file you name. On a database, it reads every file in the directory whose extension matches the chosen format, in name order, and each file's name without its extension becomes the collection name. The format is the one you selected in the dialog; nothing is guessed from the contents of the files.

Documents are inserted in batches of 500.

Import inserts, it does not merge

There is no upsert and no matching on _id. A document whose _id is already in the collection fails the import, and what earlier batches already inserted stays — the same is true of an import you cancel from the status bar. Import into an empty collection, or tick Replace conflicting collections, which drops the existing collection before writing it again.

Without that box ticked, an import that would land on an existing collection is refused before anything is written.

Import is a write, so a read-only connection refuses it. Export only reads, and is allowed on one.

While it runs

Every transfer reports into the same status channel as backups and restores, so the status bar shows which collection is being moved and how many documents have gone, and can request cancellation from outside the dialog. Progress is also in the dialog itself; its buttons stay disabled until the transfer ends.

Backups and Restoring a backup — the archive format, and what a restore costs you.
Exporting results — one query's answer rather than a whole collection, and the streaming path.
GridFS — uploading and downloading a single stored file, which is the same two entitlements applied to one object.

Transferring data

#The three transfers

#Migrate goes through a backup, and verifies the copy

#Copy or Move

#What a migration refuses

#Export writes one file per collection

#Import reads a file, or a directory of them

#While it runs

#Related