Compatibility Mode

Compatibility mode is a feature in WP Migrate DB Pro that controls how WordPress plugins and themes are loaded for requests made during migrations.

WP Migrate DB Pro uses AJAX requests to perform migrations. Every time an AJAX request is served by WordPress, all of WordPress core, the active theme, and all the active plugins are loaded. By implementing Compatibility mode, WP Migrate DB Pro cuts down on that overhead by excluding these plugins, and the default theme, from loading during migration requests.

Compatibility mode is automatically enabled and set to exclude all plugins and themes. Compatibility mode greatly reduces the chance of another plugin disrupting the migration process. It may also boost the overall speed of the migration and will reduce the migration’s memory footprint by excluding unnecessary plugins.

If required, plugins can be added to an allow list, to be loaded during migration requests. To include any specific plugins:

1. Click on the Settings tab
2. Confirm that the “Load Select Plugins for Migration Requests” toggle under “Advanced Settings” is enabled, or enable it
3. Select the plugins you wish to enable
4. Click Save

By default, this feature is enabled and no plugins are selected.

WP Migrate DB Pro Versions 1.8 to 1.9

In WP Migrate DB Pro 1.8, compatibility mode was updated to exclude all plugins and themes by default and to be automatically enabled. To include any specific plugins:

1. Click on the Settings tab
2. Expand the “Compatibility” section
3. Confirm that the “Load Select Plugins for Migration Requests” toggle under “Advanced Settings” is enabled, or enable it
4. Select the plugins you wish to enable
5. Click Save

WP Migrate DB Pro Versions 1.4 to 1.7.2

Compatibility mode was originally introduced in WP Migrate DB Pro version 1.4 and provided the ability to exclude plugins from loading during a migration request. To activate Compatibility mode if you’re using any of these versions:

1. Click the Settings tab
2. Enable the option that reads “Plugin Compatibility Mode”
3. Read the prompt and click “OK”
4. Click the “Select All” text link below the text area (see note)
5. Click the “Save Changes” button

Plugin Filter {plugin-filter}

There is also a filter available to add plugins to the allowed list. Using the wpmdb_compatibility_plugin_whitelist filter, you can include a plugin by adding its plugin slug to the plugins array used to allow plugins:

add_filter( 'wpmdb_compatibility_plugin_whitelist', function ( $plugins ) {
    $plugins[] = 'my-neat-plugin';
    return $plugins;
} );

Adding a plugin this way will always have it enabled during migrations, without the need to use the plugin selector during a migration process, or enabling it from the WP Migrate DB Pro Settings.

If for whatever reason, you need to enable the default theme to be loaded during a migration, the wpmdb_compatibility_enable_theme hook can be used to turn this on.

add_filter( 'wpmdb_compatibility_enable_theme', function () {
    return true;
} );

How it Works

It is important to note that we only exclude plugins and themes from loading once we have determined that the request is a migration request from WP Migrate DB Pro. Plugins or the theme are never actually disabled throughout this process, they’re simply not loaded.

Note: The WP Migrate DB Pro core and addon plugins are automatically excluded from this list to ensure you’re not excluding plugins that are required to execute the migration. Additionally, plugins that start with wp-migrate-db or wpmdb will also always be loaded. This should keep any tweaks plugins you may have installed running during migrations.

Serialized Data Errors

WP Migrate DB - Failed to instantiate object for replacement. If the serialized object's class is defined by a plugin, you should enable that plugin for migration requests.

The above error can sometimes occur if you have installed a plugin that stores a serialized object in your database. As outlined in the error message, the fix for this is to include the plugin that is causing the error in the allowed list, using either of the methods described above.

When Compatibility Mode Doesn’t Work

Compatibility Mode works in most cases for most plugins. However, since Compatibility Mode works by intercepting requests for the active_plugins option, any hooks that are fired prior to the query section of the get_option() function will not get intercepted. One such case is the query filter which is fired in wp-includes/wp-db.php before a query is run.

For more information on compatibility mode please see our introductory post on it.