Migrate Tools
Proporciona interfaz de usuario y comandos Drush para ejecutar y gestionar migraciones de Drupal.
migrate_tools
Install
composer require 'drupal/migrate_tools:^6.1'
Overview
Migrate Tools es un módulo complementario esencial para la API Migrate del núcleo de Drupal. Proporciona tanto una interfaz administrativa basada en web como potentes comandos Drush para gestionar procesos de migración.
El módulo permite a los administradores del sitio ver el estado de las migraciones, ejecutar importaciones y reversiones, monitorear el progreso e inspeccionar los mensajes de migración, todo a través de una interfaz intuitiva o línea de comandos. Funciona perfectamente con el módulo Migrate Plus para proporcionar gestión de migraciones basada en entidades con grupos de migración.
Las capacidades clave incluyen soporte de procesamiento por lotes para migraciones grandes, funcionalidad de sincronización para mantener el origen y destino alineados, configuración compartida para definiciones de migración DRY, y registro completo con indicadores de progreso.
Features
- Interfaz web para ver y gestionar grupos de migración y migraciones individuales con estado, conteos y marcas de tiempo de última importación
- Comandos Drush para todas las operaciones de migración incluyendo importar, revertir, detener, restablecer, deshabilitar y verificar estado
- Soporte de procesamiento por lotes para ejecutar migraciones grandes a través de la interfaz web sin problemas de tiempo de espera
- Funcionalidad de sincronización para eliminar automáticamente registros de destino que ya no existen en los datos de origen
- Visualización de barra de progreso durante la ejecución de comandos Drush con actualizaciones de estado en tiempo real
- Visor de mensajes de migración que muestra errores, advertencias y avisos de las ejecuciones de migración
- Páginas de inspección de pipelines de origen, proceso y destino para depurar migraciones
- Sistema de configuración compartida que permite reutilizar configuraciones comunes de migración en múltiples migraciones
- Visualización del árbol de dependencias mostrando relaciones de migración y orden de ejecución
- Filtrado por lista de IDs para importar o revertir registros de origen específicos
Use Cases
Migrar contenido de Drupal 7 a Drupal 10
Usar Migrate Tools con Migrate Upgrade para generar configuraciones de migración, luego usar comandos Drush para importar contenido. Ejecutar 'drush migrate:status' para ver migraciones disponibles, luego 'drush migrate:import --all' para ejecutarlas. Usar bandera '--update' para actualizaciones incrementales.
Importar datos desde archivos CSV
Combinado con el módulo Migrate Source CSV, crear configuraciones de migración apuntando a archivos CSV. Usar el formulario de ejecución en la UI para ejecutar importaciones con procesamiento por lotes para archivos grandes. Monitorear progreso y verificar mensajes para cualquier problema.
Sincronizar contenido entre entornos
Usar la opción '--sync' con migrate:import para mantener el destino sincronizado con el origen. Esto elimina elementos de destino que ya no existen en el origen, útil para mantener un sitio de pruebas sincronizado con datos de producción.
Depurar problemas de migración
Usar la UI de administración para inspeccionar campos de origen, pipelines de proceso y configuración de destino. Verificar la pestaña de Mensajes para errores y advertencias. Usar 'drush migrate:messages' con '--format=csv' para exportar problemas para análisis.
Ejecutar migraciones parciales durante desarrollo
Usar '--limit' para procesar solo un subconjunto de elementos para pruebas. Usar '--idlist' para importar registros específicos. Usar '--feedback' para monitorear progreso en migraciones grandes.
Compartir configuración de migración entre múltiples migraciones
Crear configuración compartida en MODULE.migrate_shared_configuration.yml o en archivos migrate_shared_configuration/*.yml. Referenciar configuración compartida usando clave 'include' en migraciones para secar configuraciones comunes de origen, proceso o destino.
Tips
- Usar 'drush migrate:reset-status' cuando una migración está atascada en estado 'Importando' o 'Revirtiendo'
- La opción '--sync' es poderosa pero destructiva - eliminará contenido de destino que no esté en el origen
- Usar '--continue-on-failure' en scripts automatizados para prevenir que una migración fallida detenga todo el lote
- El formulario de ejecución de UI usa procesamiento por lotes que es mejor para migraciones grandes que la ejecución directa de PHP
- Instalar el módulo Migrate Plus para funcionalidad completa de UI - sin él, solo los comandos Drush están disponibles
- Usar '--skip-progress-bar' en entornos CI/CD donde la salida interactiva no está soportada
- Verificar dependencias de migración con 'drush migrate:tree' antes de ejecutar importaciones para entender el orden de ejecución
- La opción '--idlist-delimiter' permite delimitadores personalizados cuando los IDs de origen contienen dos puntos
Technical Details
Admin Pages 10
/admin/structure/migrate
Lista todos los grupos de migración definidos en el sistema. Muestra etiqueta del grupo, nombre de máquina, descripción y tipo de origen. Proporciona operaciones para listar migraciones dentro de cada grupo, editar configuraciones del grupo o eliminar grupos.
/admin/structure/migrate/add
Formulario para crear un nuevo grupo de migración. Los grupos de migración ayudan a organizar migraciones relacionadas juntas y pueden compartir configuración común.
/admin/structure/migrate/manage/{migration_group}
Formulario para editar la configuración de un grupo de migración existente incluyendo etiqueta, descripción y tipo de origen.
/admin/structure/migrate/manage/{migration_group}/migrations
Lista todas las migraciones dentro de un grupo de migración específico. Muestra estado de migración, conteo total de origen, conteo importado, conteo sin procesar, conteo de mensajes y marca de tiempo de última importación.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}
Muestra información de resumen para una migración específica incluyendo asignación de grupo, descripción y dependencias (tanto requeridas como opcionales).
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/source
Muestra la configuración del plugin de origen y los campos de origen disponibles para la migración. Muestra la consulta/configuración de origen y una tabla de nombres de máquina de campos con descripciones.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/process
Muestra la configuración del pipeline de proceso mostrando cómo los campos de origen se mapean y transforman a campos de destino.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/destination
Muestra información del plugin de destino incluyendo el tipo de destino y campos de destino disponibles.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/execute
Formulario para ejecutar operaciones de migración incluyendo importar, revertir, detener y restablecer. Proporciona opciones para actualizar elementos existentes, ignorar dependencias, limitar elementos y filtrar por lista de IDs.
/admin/structure/migrate/manage/{migration_group}/migrations/{migration}/messages
Muestra lista paginada de mensajes generados durante la importación de migración. Muestra IDs de origen, nivel de severidad, texto del mensaje, ID de destino y estado de la fila.
Permissions 1
Hooks 2
hook_migration_plugins_alter
Permite a los módulos alterar definiciones de plugins de migración. Migrate Tools usa esto para procesar directivas 'include' para configuración compartida.
hook_migrate_prepare_row
Permite a los módulos alterar una fila antes del procesamiento. Migrate Tools usa esto para rastrear IDs de origen para funcionalidad de sincronización.
Drush Commands 9
drush migrate:status
Lista todas las migraciones con su estado actual incluyendo grupo, ID de migración, estado, total de elementos, conteo importado, conteo sin procesar, conteo de mensajes y marca de tiempo de última importación.
drush migrate:import
Realiza una o más operaciones de importación de migración. Importa registros de origen no procesados en entidades de destino Drupal.
drush migrate:rollback
Revierte (elimina) entidades de destino creadas por una o más migraciones.
drush migrate:stop
Detiene limpiamente una operación de migración activa, permitiendo que el elemento actual se complete antes de detenerse.
drush migrate:reset-status
Restablece el estado de una migración a Inactivo. Usar cuando una migración está atascada en estado Importando o Revirtiendo.
drush migrate:disable
Deshabilita una migración, previniendo que se ejecute hasta que se vuelva a habilitar.
drush migrate:messages
Muestra mensajes (errores, advertencias, avisos) asociados con una importación de migración.
drush migrate:fields-source
Lista todos los campos de origen disponibles para una migración, mostrando nombre de máquina y descripción.
drush migrate:tree
Muestra un árbol de dependencias mostrando qué migraciones dependen de otras.