Home - jellesiderius/mage-db-sync GitHub Wiki

This tool downloads clean/stripped Magento databases over SSH, imports and configures it for development purposes. Have a fully configurated production or staging environment on your local machine within minutes. Making life a little bit easier.

Before using this tool, please read the notes.

🎯 What Does This Tool Do?

1. Downloads Databases Over SSH

Connects to your remote server via SSH, navigates to your Magento root folder, and downloads databases:

  • Magento database (stripped or full data)
  • WordPress database (auto-detected if Fishpig or standalone WordPress exists)
  • Supports both production and staging environments

2. Automatically Imports & Configures

After downloading, the tool imports and configures your entire environment:

  • ✅ Magento fully configured and ready to use
  • ✅ WordPress (if present) configured with correct URLs
  • ✅ Search engines automatically detected and configured
  • ✅ Media sync available for both Magento and WordPress
  • ✅ No manual database editing required

3. Production to Staging Sync

Automatically synchronize production databases to staging environments with proper configuration applied.

⚙️ Automatic Configuration Features

Magento Configuration

When importing a Magento database, the tool automatically:

  • 🌐 Replaces all URLs to your local domain (auto-detected from DDEV or manual config)
  • 👤 Creates admin user with credentials: admin / admin123
  • 🔍 Auto-detects search engine (OpenSearch, ElasticSearch 7/8) and configures it
  • 📧 Disables SMTP settings to prevent email sending
  • 🔒 Disables reCaptcha for local development
  • 🛍️ Creates dummy customer for each store ([email protected] / password123)
  • 🖼️ Syncs media images via rsync (optional: category, product, WYSIWYG, brands, etc.)
  • ⚡ Clears search indices to prevent conflicts
  • ✅ Validates store IDs from config files to prevent errors from deleted stores
  • 🎨 Runs custom commands via .mage-db-sync-config.json

WordPress Configuration

When importing a WordPress database, the tool automatically:

  • 🌐 Configures URLs for single-site or multisite installations
  • 👤 Creates admin user with credentials: admin / admin123
  • 🏢 Handles multisite with proper domain mapping (manual or auto-detected from Magento)
  • 📸 Syncs wp-content/uploads folder via rsync (optional)
  • ✅ Validates blog IDs to prevent errors from deleted sites

📋 Requirements & Compatibility

System Requirements

  • OS: macOS or Linux (not tested on Windows)
  • Node.js: v24 or higher
  • Magerun2: Globally installed and accessible via magerun2 command
  • Optional: rsync (for media/uploads sync)
  • Optional: DDEV (highly recommended for local development)

Magento Compatibility

  • ✅ Magento 2.3.x
  • ✅ Magento 2.4.x
  • ✅ Adobe Commerce (Cloud & On-premise)

WordPress Compatibility

  • ✅ WordPress standalone
  • ✅ WordPress multisite
  • ✅ Fishpig Magento/WordPress integration

⚠️ Important Notes

Before Using

  • 📖 Read the documentation – Understanding the tool prevents data loss for your development environment
  • 🔑 Configure SSH access – Ensure you can SSH into your remote servers
  • 💾 Backup local data – This tool overwrites your local database
  • 🔧 Install Magerun2 – Version 5.2.0 or higher required

Security & Safety

  • 🚨 Local use only – Never run this against production directly
  • 🔒 Database stripping – Customer data removed by default (configurable)
  • 🛡️ SSH key authentication – Password authentication supported but keys recommended
  • ⚠️ Data loss warning – Local databases are completely replaced

DDEV Integration

The tool is fully compatible with DDEV and will:

  • ✅ Auto-detect DDEV services (database, OpenSearch, ElasticSearch)
  • ✅ Use DDEV project name for configurations
  • ✅ Configure URLs based on DDEV domain
  • ✅ Import directly into DDEV containers