🧩 mongodbcopy

mongodbcopy is a developer-friendly CLI tool to copy, export, import, or back up MongoDB collections and databases - safely, quickly, and locally - without complex MongoDB shell commands.

🚀 Features

• 🪄 Simple CLI - Copy databases or specific collections in one line
• ⚡ Fast batch copying - Adjustable batch size for huge datasets
• 🧰 Dry-run mode - Simulate copy before actually writing
• 💾 JSON Export/Import - Backup or restore collections as JSON files
• 🤖 CI-ready - Use --yes to skip confirmations in scripts
• 📊 Progress feedback - Real-time progress bars with document counts
• 🔄 Incremental backups - Copy only new/updated documents since last backup
• 🔑 Index copying - Automatically copy indexes from source to target
• ✅ Schema validation - Validate data compatibility before copying
• 🚀 Performance optimized - Streaming and bulk operations for large datasets
• 🧠 Environment-based config - Works out of the box via .env

📦 Installation

Global Installation (Recommended)

npm install -g mongodbcopy

Local Project Installation

npm install mongodbcopy

Development Installation

# Clone from GitHub
git clone https://github.com/iamdhiraj69/mongodbcopy.git
cd mongodbcopy
npm install

# Link globally for testing
npm link

2️⃣ Setup Environment

Copy .env.example → .env and update your MongoDB details:

SOURCE_DB_URI=mongodb+srv://username:[email protected]
TARGET_DB_URI=mongodb+srv://username:[email protected]
DB_NAME=my_database

🧠 Usage

Copy All Collections

mongodbcopy --all

Copy Specific Collections

mongodbcopy --collections users,posts

Preview Without Writing (Dry Run)

mongodbcopy --all --dry-run

Copy with Custom Batch Size

mongodbcopy --all --batch-size 500

Skip Confirmation

mongodbcopy --all --yes

Copy with Indexes

mongodbcopy --all --copy-indexes

Incremental Backup (only new/updated documents)

# Copy documents updated in the last 7 days
mongodbcopy --all --incremental --timestamp-field updatedAt --since 2024-01-01T00:00:00Z

Validate Schema Before Copy

mongodbcopy --all --validate-schema

Disable Progress Bars

mongodbcopy --all --no-progress

💾 Backup / Restore JSON

Export Collections to JSON

mongodbcopy --all --export-json

All files will be saved to the backup/ folder (auto-created).

Import JSON Back into MongoDB

mongodbcopy --import-json

You can change the backup directory using:

mongodbcopy --export-json --output-dir ./my_backup

⚙️ Environment Variables

| Key | Description | Default | |-----|-------------|---------| | SOURCE_DB_URI | MongoDB source URI | Required | | TARGET_DB_URI | MongoDB target URI | Required | | DB_NAME | Database name | Required | | BATCH_SIZE | Documents per insert batch | 1000 | | LOG_TO_FILE | Write logs to file (true/false) | false | | LOG_PATH | Log file path (if enabled) | ./mongodbcopy.log | | BACKUP_DIR | JSON export/import folder | ./backup |

🥇 CLI Examples

Basic Copy

mongodbcopy --collections users,posts --batch-size 2000 --yes

Copies only users and posts collections using batch size 2000 without confirmation.

Full Backup with Indexes

mongodbcopy --all --copy-indexes --export-json --output-dir ./full-backup

Exports all collections and their indexes to JSON files.

Incremental Sync

mongodbcopy --all --incremental --timestamp-field updatedAt --since 2024-01-01T00:00:00Z

Copies only documents updated since January 1, 2024.

Safe Production Copy

mongodbcopy --all --validate-schema --copy-indexes --batch-size 5000

Validates schema compatibility and copies with indexes using larger batches.

💻 Programmatic API Usage

Use mongodbcopy in your Node.js applications:

import { copyCollections } from 'mongodbcopy';

// Copy specific collections
const results = await copyCollections({
  sourceUri: 'mongodb://localhost:27017',
  targetUri: 'mongodb://localhost:27018',
  dbName: 'myDatabase',
  collections: ['users', 'posts'],
  batchSize: 1000,
  dryRun: false,
  showProgress: true
});

console.log(results);
// [
//   { name: 'users', copied: 1500, total: 1500, status: 'copied' },
//   { name: 'posts', copied: 3200, total: 3200, status: 'copied' }
// ]

// Export to JSON with indexes
const exportResults = await copyCollections({
  sourceUri: 'mongodb://localhost:27017',
  targetUri: 'mongodb://localhost:27017',
  dbName: 'myDatabase',
  collections: ['users'],
  exportJson: true,
  outputDir: './backup',
  copyIndexes: true
});

// Incremental backup (only documents updated since a date)
const incrementalResults = await copyCollections({
  sourceUri: 'mongodb://localhost:27017',
  targetUri: 'mongodb://localhost:27018',
  dbName: 'myDatabase',
  collections: ['users'],
  incremental: true,
  timestampField: 'updatedAt',
  since: new Date('2024-01-01'),
  showProgress: true
});

// Copy with schema validation
const validatedResults = await copyCollections({
  sourceUri: 'mongodb://localhost:27017',
  targetUri: 'mongodb://localhost:27018',
  dbName: 'myDatabase',
  collections: ['users'],
  validateSchema: true,
  copyIndexes: true
});

🧰 Development

npm install
npm run start

🪄 NPM CLI Setup (optional)

To use it as a global CLI after publishing, add this to package.json:

{
  "bin": {
    "mongodbcopy": "./src/index.js"
  }
}

Then install globally:

npm i -g .
mongodbcopy --help

🧩 Roadmap

| Status | Enhancement | Description | |--------|------------|-------------| | ✅ | --dry-run | Simulate copy without writing | | ✅ | --collections | Copy specific collections | | ✅ | JSON export/import | Backup & restore to local JSON | | ✅ | --yes flag | Skip confirmation for CI | | ✅ | Progress bars | Real-time visual feedback with document counts | | ✅ | Index copying | Copy indexes from source to target | | ✅ | Incremental backups | Copy only new/updated documents | | ✅ | Schema validation | Validate before copying | | ✅ | Performance optimizations | Streaming and bulk operations | | ✅ | Enhanced test coverage | Comprehensive test cases | | 🧠 | File logging | Save logs for debugging | | 🧩 | TypeScript version | Optional future version |

🧑‍💻 Author

Dhiraj
📦 GitHub: iamdhiraj69