MU-Migration

The easiest way to install MU-Migration is using the WP-CLI package manager. This requires WP-CLI version 0.23 or higher.

If you encounter memory exhaustion errors during installation, it is a known WP-CLI issue that may require increasing the PHP memory limit.

wp package install 10up/mu-migration

Alternatively, you can install it manually:

1. Clone the repository into your WordPress plugins/ folder.
2. Run composer install to fetch necessary dependencies.
3. Activate the plugin within WordPress.

Important: You must install this plugin on both the source site (the site being moved) and the target Multisite installation.

# After cloning to plugins/
composer install

After a migration, you can use this command to reset or force password updates for users on a specific site.

Arguments and Flags

• <newpassword> (optional): The new password to set. If omitted, passwords will be reset to random secure values.
• --blog_id=<id>: Target a specific subsite.
• --reset: Resets passwords to random secure values.
• --send_email: Sends a password reset email to all users.
• --include=<users_id>: Only update these specific user IDs.
• --exclude=<users_id>: Skip these specific user IDs.

# Update all users on site 3 to a specific password
wp mu-migration update_passwords 'new_weak_password' --blog_id=3

# Reset all users to random passwords and email them
wp mu-migration update_passwords --reset --blog_id=3 --send_email

Options for the wp mu-migration import users command.

# <inputfile> : The name of the exported .csv file
# --map_file=<map> : The path to the JSON file where the ID mapping will be saved (default: ids_maps.json)
# --blog_id=<blog_id> : The ID of the blog to import users into (default: 1)

Options for the wp mu-migration import tables command.

# <inputfile> : The name of the exported .sql file
# --blog_id=<blog_id> : The ID of the blog to import tables into (Required)
# --old_prefix=<old> : The original database prefix (default: current wpdb prefix)
# --new_prefix=<new> : The new database prefix to apply
# --original_blog_id=<ID> : The original blog ID (used to calculate upload paths)
# --old_url=<olddomain> : The original site URL for search-replace
# --new_url=<newdomain> : The new site URL for search-replace

Options for the wp mu-migration import all command.

# <zipfile> : The name of the exported .zip file
# --blog_id=<blog_id> : The ID of the blog to import into. If not provided in Multisite, a new site is created.
# --new_url=<new_url> : The new URL for the site.
# --mysql-single-transaction : If set, wraps the SQL import in a START TRANSACTION and COMMIT.
# --uid_fields=<uid_fields> : Comma-separated list of user ID fields used to map post authors during import.

Use the wp mu-migration export users command to export WordPress users and their metadata to a .csv file. The export includes standard user fields and user meta, while automatically filtering out sensitive or environment-specific keys (like session_tokens, capabilities, or user-settings).

Options:

• <outputfile>: The name of the exported .csv file.
• --blog_id=<blog_id>: The ID of the blog to export users from.

Note: You can extend the exported user data or the default CSV headers using the following WordPress filters:

• mu_migration/export/user/headers: Add custom columns to the CSV.
• mu_migration/export/user/data: Add custom data to each user row.

wp mu-migration export users output.csv --blog_id=2

Use the wp mu-migration export all command to create a comprehensive migration package in a single .zip file. This package includes site metadata (JSON), user data (CSV), and database tables (SQL). You can optionally include files from the WordPress filesystem.

Options:

• <zipfile>: The name of the resulting .zip file.
• --blog_id=<blog_id>: The ID of the blog to export.
• --tables=<table_list>: Specific tables to include in the SQL export.
• --non-default-tables=<table_list>: Additional tables to include.
• --plugins: Include the wp-content/plugins directory.
• --themes: Include the active theme and child theme directories.
• --uploads: Include the wp-content/uploads directory.
• --verbose: Enable verbose output.

wp mu-migration export all site.zip --plugins --themes --uploads

Import an entire site from a .zip package into a Multisite installation. This is a high-level command that orchestrates several sub-tasks:

1. Extracts the zip package.
2. Imports tables (using the tables command).
3. Moves files: Plugins, themes, and uploads are moved to their correct locations.
4. Imports users (using the users command).
5. Updates post authors: Uses the generated user map to reassign post authors based on provided uid_fields.
6. Flushes rewrite rules.

A valid zip package must contain a .json metadata file, a .csv user file, and a .sql database file.

wp mu-migration import all site.zip --uid_fields=_content_audit_owner

Import SQL tables from a single site instance into a Multisite environment. This command performs a search-and-replace for database prefixes and URLs, and updates the necessary tables to ensure compatibility with Multisite (e.g., updating the user_roles option key).

Requirements: The sed utility must be installed on the system to handle prefix replacement in the .sql file.

wp mu-migration import tables site.sql --old_prefix=wp_ --old_url=old_domain.com --new_url=new_domain.com