Migrate Helper

Provides utilities for managing Drupal migrations, including the ability to rename migration machine names and their associated database tables without data loss.

Features

1. Source lookup: View migration source information for entities via admin tab
2. Quick status: Check migration status without HTTP or row count overhead
3. Migration info: Inspect migration tables and configuration
4. List tables: View all migration tables and identify orphaned ones
5. Cleanup stubs: Remove orphaned stub entities left over after migrations complete
6. Rename migrations: Rename one migration by ID, or many at once by prefix (bulk), without losing map/message data

Installation

drush en migrate_helper

Reference

1. Source lookup

A "Migrate Source" tab is added to entity pages, allowing administrators to view migration information for migrated content.

Supported entity types:

• Nodes (/node/{nid}/migrate-source)
• Media (/media/{mid}/migrate-source)
• Taxonomy terms (/taxonomy/term/{tid}/migrate-source)

Information displayed:

• Source IDs from the original migration
• Destination IDs (the Drupal entity ID)
• Migration status (Imported, Needs update, Stub, Failed)
• Last import timestamp
• Which migration(s) created the entity

The module dynamically discovers which migrations target each entity type, so it works with any migration configuration.

Permission required: administer migrations

2. Quick status

Check the status of all migrations without the overhead of HTTP requests or row counting (unlike drush migrate:status):

# Status for all migrations
drush migrate-helper:status-all

# Filter by migration group
drush migrate-helper:status-all --group=my_group

Shows the internal migration status (Idle, Importing, Rolling back, Stopping, Disabled) for each migration.

Aliases: mh-status, migrate-status-all

3. Migration info

Display information about a migration's tables and configuration:

drush migrate-helper:info my_migration

Output shows:

• Associated database tables (migrate_map_*, migrate_message_*)
• Row counts for each table
• Whether a migration config entity exists
• Whether key-value state exists

Aliases: mh-info, migrate-info

4. List tables

List all migration tables in the database:

# List all tables
drush migrate-helper:list-tables

# List only orphaned tables (tables without corresponding config)
drush migrate-helper:list-tables --orphaned

Aliases: mh-tables, migrate-tables

5. Cleanup stubs

Remove orphaned stub entities left over after migrations complete. Stubs are placeholder entities created when a migration references content that hasn't been migrated yet. After all migrations complete, remaining stubs indicate broken references.

# Preview what would be deleted
drush migrate-helper:cleanup-stubs --dry-run

# Delete all unresolved stub entities
drush migrate-helper:cleanup-stubs

For each stub found, this command:

• Deletes the placeholder entity from Drupal
• Removes the row from the migrate_map_* table
• Removes related entries from the migrate_message_* table

Aliases: mh-stubs, migrate-cleanup-stubs

6. Rename migrations

Modern Drupal migrations are typically defined in YAML files (in migrations/ or config/install/). The migration definition (ID, source, process, destination) lives in code/YAML, but the data (source-to-destination mappings, messages, status) lives in the database:

• migrate_map_{id} - Maps source IDs to destination entity IDs
• migrate_message_{id} - Stores migration warnings/errors
• key_value entries - Stores last import times and status

Typical workflow when renaming a migration:

1. Update your YAML file with the new migration ID (e.g., rename old_migration.yml to new_migration.yml and change id: new_migration)
2. Deploy the code change
3. Run drush migrate-helper:rename old_migration new_migration
4. The database tables and state are renamed to match the new ID
5. The migration continues where it left off with all mappings preserved

This is safe because the migration plugin is discovered from YAML, and this tool just ensures the database tables match the new ID.

Single migration: rename one ID and its tables.

# Preview the rename operation
drush migrate-helper:rename old_migration_id new_migration_id --dry-run

# Execute the rename
drush migrate-helper:rename old_migration_id new_migration_id

Aliases: mh-rename, migrate-rename

Bulk rename: rename every migration whose ID starts with a prefix (string replace on the prefix).

# Preview bulk rename
drush migrate-helper:bulk-rename old_prefix new_prefix --dry-run

# Execute bulk rename
drush migrate-helper:bulk-rename old_prefix new_prefix

Aliases: mh-bulk, migrate-bulk-rename

What gets renamed

When you rename a migration (single or bulk), this module handles:

1. Database tables: migrate_map_{id} and migrate_message_{id} are renamed
2. Key-value state: Entries in migrate_last_imported and migrate_status collections are migrated
3. Config entities (optional): If a migrate_plus.migration.{id} config entity exists in active config, it's cloned with the new ID

All source-to-destination mappings and messages are preserved, so rollbacks and incremental imports continue to work correctly.

Service API

You can use the service programmatically, which is useful for update hooks:

/** @var \Drupal\migrate_helper\Service\MigrateRenameService $service */
$service = \Drupal::service('migrate_helper.migrate_rename');

// Get migration info
$info = $service->getMigrationInfo('my_migration');

// Rename a migration
$result = $service->renameMigration('old_id', 'new_id');

// Dry run (returns what would be changed)
$result = $service->renameMigration('old_id', 'new_id', dryRun: TRUE);

// List all migration tables
$tables = $service->listMigrationTables();

PostgreSQL Table Name Limit

PostgreSQL truncates identifiers to 63 characters. Since migration tables use prefixes like migrate_message_ (16 chars), the maximum recommended migration ID length is 47 characters.

If you try to rename to a longer ID, you'll see a warning:

WARNING: Migration ID 'very_long_migration_name_that_exceeds_the_limit' (47+ chars)
may cause issues on PostgreSQL. See https://www.drupal.org/project/drupal/issues/2845340