Restore logical backup to self-managed MongoDB | mongorestore - ApsaraDB for MongoDB

Prerequisites

Ensure the following:

An ApsaraDB for MongoDB instance that uses local SSDs
A self-managed MongoDB database running the same version as the ApsaraDB for MongoDB instance
MongoDB Database Tools (same major version) installed on the self-managed database host (on-premises server or ECS instance). Install MongoDB

Important

mongorestore must be compatible with your MongoDB version. An older mongorestore does not support a newer MongoDB version. Check the mongorestore Compatibility matrix.

Sharded cluster considerations

Restore to a sharded cluster self-managed database

For sharded cluster self-managed databases:

Set <hostname> to the mongos endpoint. Do not point to an individual shard.
Add --nsExclude="config.*" to the mongorestore command to avoid config database errors.

Restore from a sharded cluster instance

For ApsaraDB for MongoDB sharded cluster instances:

Download and import backup data for each shard separately.
Orphaned documents in the sharded cluster instance may produce dirty data in the self-managed database.
When restoring backup files from multiple shards to the same sharded cluster database, add --drop only for the first shard. Omit --drop for subsequent shards to avoid deleting previously restored data.

Step 1: Create a logical backup

Log on to the ApsaraDB for MongoDB console.
In the left-side navigation pane, click Replica Set Instances or Sharded Cluster Instances.
In the upper-left corner of the page, select the resource group and region of the instance.
Click the instance ID, or click in the Actions column and select Manage.
In the upper-right corner of the instance details page, click Back up Instance.
In the Back up Instance panel, set Backup Method to Logical Backup.
Click OK and wait for the backup to complete.

Step 2: Download the backup file

Download backup files.
Copy the backup file to the host running the self-managed MongoDB database and mongorestore.

Step 3: Run `mongorestore`

Import the backup data into the self-managed database:

mongorestore -h <hostname> --port <server port> -u <username> -p <password> --drop --gzip --archive=<backupfile> -vvvv --stopOnError

Required parameters

Parameter	Description
`<hostname>`	Address of the self-managed MongoDB database host. Use `127.0.0.1` for localhost. For sharded cluster architectures, set this to the `mongos` endpoint.
`<server port>`	Port number of the self-managed MongoDB database. Default: `27017`.
`<username>`	Account with read and write permissions on all databases. Use the root account.
`<password>`	Password for the specified account.
`<backupfile>`	File name or path of the downloaded logical backup file.

Optional parameters

Parameter	Description
`--drop`	Drops each collection before restoring it. When restoring multiple shards to the same sharded cluster database, add this parameter only for the first shard.
`--gzip`	Decompresses gzip-compressed backup data. Supported from MongoDB 3.1.4. mongo-tools changelog.
`-vvvv`	Highest verbosity level. Each additional `v` adds more detail to the output log.
`--stopOnError`	Stops the restore immediately on error.
`--nsExclude`	Excludes matching namespaces from the restore. Example: `--nsExclude="config.*"`. Required for sharded cluster self-managed databases.

Performance tuning

For large datasets, add these parameters to improve restore performance:

Parameter	Description
`--numParallelCollections`	Collections to restore in parallel. Default: `4`. Increase if the target host has sufficient CPU and I/O capacity.
`--numInsertionWorkersPerCollection`	Concurrent insert workers per collection. Default: `1`. Increase for large imports based on available server resources.

Example with parallelism:

mongorestore -h 127.0.0.1 --port 27017 -u root -p <password> \
  --drop --gzip --archive=<backupfile> \
  --numParallelCollections=4 \
  --numInsertionWorkersPerCollection=4 \
  -vvvv --stopOnError

Example

mongorestore -h 127.0.0.1 --port 27017 -u root -p ******** --drop --gzip --archive=hins1111_data_20190710.ar -vvvv --stopOnError

Verify the restored data

Verify the restored data for completeness and correctness.

Check document counts

Compare document counts between the backup and the restored database:

// Connect to the self-managed database
use <database_name>

// Check the document count for each collection
db.getCollectionNames().forEach(function(c) {
    print(c + ": " + db.getCollection(c).countDocuments({}));
});

Compare the output against the document counts in the source ApsaraDB for MongoDB instance.

Run sample queries

Spot-check that documents, fields, and values are intact:

// Verify a specific document exists
db.<collection_name>.findOne({ _id: ObjectId("<known_id>") })

Verify indexes

Confirm that indexes were restored correctly:

db.<collection_name>.getIndexes()

Compare against the source instance to verify all indexes are present.

Post-restore checklist

After verification, confirm the following:

[ ] Document counts match between the source instance and the self-managed database
[ ] Indexes are present and match the source instance
[ ] Sample queries return expected results
[ ] Application connectivity to the self-managed database is confirmed
[ ] For sharded cluster restores, check for orphaned documents and clean up dirty data