WFU-Migrate

A CLI tool for migrating WordPress multisite databases between Wake Forest University environments (dev, uat, pprd, prod, local).

Key Features

• Serialization-safe migrations: Uses WP-CLI via Docker for all search-replace operations, ensuring serialized PHP data is preserved correctly
• Single-site migration: Migrate individual sites between any environment
• Environment migration: Refresh entire lower environments from production
• S3 integration: Automatic file sync and backup archival
• Resume capability: Continue interrupted migrations from where they left off
• Pre-flight checks: Validates prerequisites before migration

Prerequisites

• Node.js 18+ LTS
• Docker Desktop (for WP-CLI operations)
• AWS CLI (for S3 operations)
• Access to WFU database endpoints

Installation

npm install -g wfu-migrate

Or for development:

git clone <repository-url>
cd wfu-migrate
./init.sh

Quick Start

1. Configure the tool:

   wfu-migrate config wizard

2. Check system readiness:

   wfu-migrate doctor

3. Migrate a single site:

   wfu-migrate migrate 123 --from prod --to dev

4. Migrate entire environment:

   wfu-migrate env-migrate dev

Commands

migrate

Migrate a single site between environments.

wfu-migrate migrate <site-id> --from <env> --to <env> [options]

Options:

• --from <env> - Source environment (dev, uat, pprd, prod) [required]
• --to <env> - Target environment (dev, uat, pprd, prod, local) [required]
• --dry-run - Preview changes without executing
• -f, --force - Skip confirmation prompts
• -v, --verbose - Show detailed output
• --homepage - Include homepage (site ID 1) tables
• --custom-domain <source:target> - Custom domain replacement
• --skip-backup - Skip target backup (dangerous)
• --skip-s3 - Skip S3 sync and archival
• --work-dir <path> - Custom working directory
• --keep-files - Keep local SQL files after completion
• --timeout <minutes> - Timeout for database operations (default: 20)

env-migrate

Migrate full environment from production to lower environment.

wfu-migrate env-migrate <target> [options]

Target: uat, dev, or local (source is always prod)

Options:

• --dry-run - Preview changes without executing
• -f, --force - Skip confirmation prompts
• -v, --verbose - Show detailed output
• --network-only - Migrate network tables only
• --sites-only - Migrate sites only (skip network tables)
• --batch-size <n> - Sites per batch (default: 5)
• --parallel - Process sites in parallel
• --concurrency <n> - Max concurrent migrations (default: 3)
• --include-sites <ids> - Comma-separated site IDs to include
• --exclude-sites <ids> - Comma-separated site IDs to exclude
• --active-only - Only migrate active sites
• --exclude-main-site - Exclude site ID 1
• --skip-backup - Skip environment backup
• --skip-s3 - Skip S3 archival and sync
• --auto-rollback - Automatically rollback on failure
• --max-retries <n> - Retries for failed operations (default: 3)
• --health-check - Pre/post migration health checks
• --resume <id> - Resume incomplete migration
• --list-migrations - List incomplete migrations
• --skip-failed - Skip previously failed sites when resuming
• --retry-failed - Retry only failed sites when resuming

config

Configuration management.

wfu-migrate config wizard           # Interactive setup
wfu-migrate config set <key> <val>  # Set a value
wfu-migrate config get <key>        # Get a value
wfu-migrate config list             # List all (passwords masked)
wfu-migrate config verify           # Verify configuration
wfu-migrate config reset            # Reset to defaults
wfu-migrate config import_wfuwp     # Import from wfuwp

doctor

System diagnostics and health checks.

wfu-migrate doctor

Checks:

• Docker availability
• MySQL client (native or Docker fallback)
• AWS CLI configuration
• Configuration validity
• Environment connectivity
• Migration database readiness
• S3 bucket accessibility

URL Replacement Patterns

The tool handles complex URL patterns for WFU's asymmetric environment structure:

Production URLs

• Main site: www.wfu.edu
• Subsites: {subsite}.wfu.edu (e.g., news.wfu.edu)

Lower Environment URLs

• Main site: {env}.wfu.edu (e.g., dev.wfu.edu)
• Subsites: {subsite}.{env}.wfu.edu (e.g., news.dev.wfu.edu)

Local Environment URLs

• Main site: wfu.local
• Subsites: {subsite}.wfu.local

Configuration

Configuration is stored at ~/.wfu-migrate/config.json. Passwords are encrypted using AES-256-CBC.

Why WP-CLI?

WordPress databases contain serialized PHP data with string length prefixes:

s:15:"example.wfu.edu"

Simple SQL REPLACE() operations break this serialization by changing the string without updating the length prefix. WP-CLI correctly:

1. Unserializes the data
2. Performs replacements
3. Re-serializes with correct length prefixes

Development

# Install dependencies
npm install

# Run in development mode
npm run dev -- migrate --help

# Build
npm run build

# Test
npm test

# Lint
npm run lint

License

MIT