Migrate MongoDB Atlas to Self-Hosted VPS: Complete Data Migration Guide

Ready to move your MongoDB database from Atlas to a self-hosted VPS? This guide covers the complete migration process using mongodump and mongorestore—the official MongoDB tools for safe, reliable data transfer.

Prerequisites#

Before starting the migration, ensure you have:

• A running MongoDB instance on your VPS (see our MongoDB installation guide)
• MongoDB Database Tools installed on your local machine
• Your MongoDB Atlas connection string
• Your VPS MongoDB connection string

Step 1: Install MongoDB Database Tools#

The migration tools (mongodump, mongorestore) are part of MongoDB Database Tools. Install them on your local machine:

1# macOS (using Homebrew)
2brew install mongodb-database-tools
3
4# Ubuntu/Debian
5sudo apt-get install mongodb-database-tools
6
7# Verify installation
8mongodump --version

Step 2: Export Data from MongoDB Atlas#

Use mongodump to create a backup of your Atlas database. This is a non-destructive operation—your Atlas data remains untouched.

1# Export entire database from Atlas
2mongodump --uri="mongodb+srv://username:password@cluster.mongodb.net/your-database" \
3  --out=./mongodb-backup
4
5# This creates:
6# ./mongodb-backup/your-database/
7#   ├── collection1.bson
8#   ├── collection1.metadata.json
9#   ├── collection2.bson
10#   └── ...

Step 3: Verify the Backup#

Always verify your backup before proceeding. Check the backup directory structure and file sizes:

1# List backup contents
2ls -la ./mongodb-backup/your-database/
3
4# Check total backup size
5du -sh ./mongodb-backup/

You should see .bson files for each collection and corresponding .metadata.json files containing indexes.

Step 4: Transfer Backup to VPS#

Copy the backup files to your VPS using SCP:

1# Transfer backup to VPS
2scp -r ./mongodb-backup user@your-vps-ip:~/mongodb-backup
3
4# For large backups, consider using rsync for resumable transfers
5rsync -avz --progress ./mongodb-backup user@your-vps-ip:~/mongodb-backup

Step 5: Import Data to VPS MongoDB#

SSH into your VPS and restore the database using mongorestore:

1# SSH into VPS
2ssh user@your-vps-ip
3
4# Install MongoDB tools on VPS (if not already installed)
5sudo apt-get install -y mongodb-database-tools
6
7# Restore to VPS MongoDB
8mongorestore --uri="mongodb://admin:password@localhost:27017/?authSource=admin" \
9  --db your-database \
10  ~/mongodb-backup/your-database

If you used --gzip during export, add --gzip to the restore command as well.

Step 6: Validate the Migration#

Critical: Always validate your data after migration. Connect to your VPS MongoDB and verify:

1// Connect to VPS MongoDB
2mongosh "mongodb://admin:password@your-vps-ip:27017/your-database?authSource=admin"
3
4// Check database stats
5db.stats()
6
7// Count documents in each collection
8db.getCollectionNames().forEach(c => {
9  print(`${c}: ${db[c].countDocuments()} documents`)
10})
11
12// Verify indexes were restored
13db.getCollectionNames().forEach(c => {
14  print(`\n${c} indexes:`)
15  printjson(db[c].getIndexes())
16})

Compare document counts with your Atlas database to ensure nothing was lost.

Step 7: Update Application Connection String#

Update your application's environment variables to point to the new VPS MongoDB:

1# Before (Atlas)
2MONGO_URI='mongodb+srv://user:pass@cluster.mongodb.net/your-database'
3
4# After (VPS)
5MONGO_URI='mongodb://admin:password@your-vps-ip:27017/your-database?authSource=admin'

Rollback Strategy#

Keep your Atlas database running until you've fully validated the migration. If issues arise:

1. Revert your application's connection string to Atlas
2. Investigate and fix issues on VPS
3. Re-run migration with fresh data if needed
4. Only decommission Atlas after a week of stable production

Migration Tips#

• Test on dev first — Always migrate a development database before touching production
• Schedule during low traffic — Minimize data changes during migration window
• Document everything — Keep notes of each step for troubleshooting
• Set up monitoring — Monitor VPS MongoDB performance after migration

FAQs#

Q: How long does migration take?#

A: Depends on database size and network speed. A 15MB database takes under a minute. Larger databases (1GB+) may take 10-30 minutes.

Q: Will indexes be preserved?#

A: Yes, mongodump exports index definitions in .metadata.json files, and mongorestore recreates them automatically.

Q: Can I migrate while the application is running?#

A: Yes, mongodump creates a point-in-time snapshot. However, any writes after the dump starts won't be included. For zero-downtime migration, consider MongoDB's live migration tools or a brief maintenance window.

Q: What if mongorestore fails midway?#

A: mongorestore is idempotent. Drop the partially restored database and run it again. Your backup files remain intact.

Conclusion#

Migrating from MongoDB Atlas to a self-hosted VPS is straightforward with mongodump and mongorestore. The key steps: export your data, transfer securely, import to VPS, and validate thoroughly. Keep Atlas running as a fallback until you're confident in the migration.