Migrate Sandbox!

Overview

Why the exclamation? Because "Migrate Sandbox" was already taken!

Migrate Sandbox is a UI where developers can quickly and safely experiment with migrate process plugins and migrate process pipelines.

To that end, example source data and pipelines have been provided for almost all process plugins defined in the core Migrate module and the contributed Migrate Plus module. That's examples for almost 50 plugins! You can also use the sandbox to debug your custom process plugins or other contributed plugins.

As of version 1.1.0 the sandbox can be populated from a real migration. This allows for some debugging of source plugins in addition to making process pipelines even faster and easier to debug.

Migrate Sandbox is an especially good tool for grokking the hard-to-grok process plugins such as sub_process, migration_lookup, entity_generate, and transpose, not to mention all the dom-related ones.

The starter config provided for each of these plugins gives you a great jumping-off point.

Requirements

Core Migrate...obviously.

Recommended modules

• Yaml Editor: if you enable yaml_editor the editing experience will be much much better. The screenshot has yaml_editor enabled.
• Migrate Plus: If you're doing migrations, you would probably benefit from this module. There are many examples in Migrate Sandbox for plugins from Migrate Plus.
• Migrate Example: This is a sub-module of Migrate Plus. The migration_lookup example provided with Migrate Sandbox is based on the beer_term migration in Migration Example. Running that migration would make the example work without any editing.

Check out our blog post!

Migrate Sandbox or How to Fail Fast in Drupal Migrations

How the Sandbox Works

What happens in the sandbox stays in the sandbox. Here's how the magic happens.

1. The sandbox migration uses a custom id_map that does not save any migrate_map data to the db.
2. Instead of logging errors to the db in migrate_message tables, errors are output using on-screen messages.
3. Special destination plugins migrate data into entities that are displayed in the sandbox but are never saved.

Oh, and you'll never have to reset the status of a stuck migration because the sandbox does that automatically. This all helps you fail fast while keeping your db clean.

On-screen Migrate Messages

On-screen Yaml Validation

On-screen Exceptions

Though nothing goes directly into the database, the latest configuration is saved to migrate_sandbox.latest. There is always an option to select migrate_sandbox.latest as your starter config.

Sandbox Escape Warnings

There are a number of process plugins from Migrate and Migrate Plus that may result in side-effects outside of the sandbox. If you include any of the following process plugins in your sandbox pipeline, there will be a warning above the Save & Run button.

• callback
• dom_migration_lookup (Migrate Plus)
• download
• entity_generate (Migrate Plus)
• file_blob (Migrate Plus)
• file_copy
• migration_lookup
• service (Migrate Plus)

You may still use these plugins in Migrate Sandbox, but you should be aware that there could be persistent consequences.

What Migrate Sandbox is Not

Migrate Sandbox has limitations!

1. Due to security implications, it should never be used by untrusted users.
2. Migrate Sandbox is not for use on production sites for any reason.
3. It is not intended to run real migrations.
4. It is not designed for debugging destination plugins.
5. The sandbox migration cannot be used to experiment with the track_changes setting or with high-water marks.

Similar Projects

Migrate Devel gives some other tools for developing migrations. Migrate Sandbox is really focussed on making it fast and fun to experiment with the process part of migration.