https://github.com/baikho/drupal-migrate_helper
Provides utilities for managing Drupal migrations
https://github.com/baikho/drupal-migrate_helper
drupal drupal-10 drupal-11 drupal-developers drupal-development drupal-migrate drupal-migration drupal-mod drupal-plugin
Last synced: about 18 hours ago
JSON representation
Provides utilities for managing Drupal migrations
- Host: GitHub
- URL: https://github.com/baikho/drupal-migrate_helper
- Owner: baikho
- Created: 2026-03-13T23:13:15.000Z (5 months ago)
- Default Branch: 1.0.x
- Last Pushed: 2026-03-24T17:36:20.000Z (4 months ago)
- Last Synced: 2026-07-23T08:24:43.984Z (4 days ago)
- Topics: drupal, drupal-10, drupal-11, drupal-developers, drupal-development, drupal-migrate, drupal-migration, drupal-mod, drupal-plugin
- Language: PHP
- Homepage: https://www.drupal.org/project/migrate_helper
- Size: 18.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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
```bash
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`):
```bash
# 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:
```bash
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:
```bash
# 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.
```bash
# 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.
```bash
# 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).
```bash
# 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:
```php
/** @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
```