Migrate Upgrade
Proporciona comandos Drush para realizar actualizaciones completas desde sitios Drupal 6 o Drupal 7 a sitios Drupal 8+.
migrate_upgrade
Install
composer require 'drupal/migrate_upgrade:^4.0'
composer require 'drupal/migrate_upgrade:8.x-3.2'
Overview
Migrate Upgrade es un potente módulo de migración que permite actualizaciones automatizadas desde versiones antiguas de Drupal (6 y 7) a sitios Drupal modernos (8, 9, 10, 11+). A diferencia de la interfaz de actualización del núcleo de Drupal que opera a través de una interfaz web, este módulo proporciona herramientas completas de línea de comandos Drush para realizar migraciones, otorgando a los administradores mayor control y flexibilidad sobre el proceso de actualización.
El módulo se integra con el framework de migración del núcleo de Drupal y el módulo Migrate Plus para generar y ejecutar migraciones. Puede ejecutar migraciones inmediatamente para realizar una actualización completa del sitio, o generar entidades de configuración de migración que pueden personalizarse antes de la ejecución. Este flujo de trabajo de solo configuración es particularmente valioso para migraciones complejas que requieren mapeos de campos personalizados o transformaciones de datos.
Las capacidades principales incluyen soporte para múltiples métodos de conexión a base de datos (URL directa o clave de settings.php), migración de archivos con soporte tanto para HTTP como para rutas de archivos locales, manejo de prefijos de base de datos para instalaciones de Drupal con prefijos, y una función completa de reversión para deshacer contenido y configuración importados.
Features
- Realiza migración completa de contenido y configuración desde Drupal 6 o 7 a Drupal 8+
- Soporta tanto conexiones directas por URL de base de datos como claves de base de datos preconfiguradas en settings.php
- Maneja migraciones de archivos vía HTTP desde sitios remotos o directorios de archivos locales
- Modo de solo generación exporta migraciones como entidades de configuración migrate_plus para personalización
- Prefijos de ID de migración personalizables para prevenir conflictos con plugins de migración del núcleo
- Funcionalidad completa de reversión para eliminar contenido importado y entidades de configuración creadas
- Expansión automática de migraciones derivadas para migraciones específicas por tipo de contenido
- Modo de depuración con registro detallado de mensajes del mapa de IDs
- Integración con el modo de simulación de Drush para pruebas en seco
Use Cases
Actualización completa del sitio desde Drupal 7
Realizar una migración completa de contenido, usuarios, configuración y archivos desde un sitio Drupal 7 a Drupal 10. Instalar un sitio Drupal 10 nuevo, habilitar todos los módulos a los que desea migrar datos, luego ejecutar: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d7db' --legacy-root=https://old-site.com
Flujo de trabajo de migración personalizado
Generar configuraciones de migración para revisión y personalización antes de la ejecución. Ejecutar con --configure-only, exportar configuraciones a un módulo personalizado, modificar archivos YAML para ajustar mapeos de campos o agregar plugins de proceso, luego usar migrate_tools para ejecutar: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d7db' --configure-only --migration-prefix=custom_
Migración con conexión de base de datos preconfigurada
Cuando la conexión de base de datos heredada ya está definida en settings.php (útil para entornos donde las credenciales no deben pasarse vía línea de comandos), usar la clave de base de datos: drush migrate-upgrade --legacy-db-key=legacy_drupal --legacy-root=/mnt/legacy_files
Reversión de migración después de pruebas
Después de ejecutar una migración de prueba en un entorno de staging, eliminar completamente todo el contenido importado y entidades de configuración para empezar de nuevo: drush migrate-upgrade-rollback
Actualización de Drupal 6 a Drupal 10 con base de datos con prefijos
Migrar desde un sitio Drupal 6 que usa prefijos de tabla: drush migrate-upgrade --legacy-db-url='mysql://user:pass@host/d6db' --legacy-db-prefix='drupal_' --legacy-root=https://old-site.com
Tips
- Siempre ejecute actualizaciones en un sitio de destino recién instalado con solo los módulos que necesita habilitados
- Use --configure-only para migraciones complejas que necesitan personalización antes de la ejecución
- El módulo config_devel es útil cuando se itera en configuraciones YAML de migración
- Pruebe las migraciones en un entorno de staging antes de ejecutar en producción
- Haga una copia de seguridad de su sitio de destino antes de ejecutar migraciones, aunque la reversión esté disponible
- Habilite todos los módulos de destino antes de ejecutar la actualización para asegurar el descubrimiento adecuado de migraciones
- Use la opción --debug para ver progreso detallado e información de errores durante las migraciones
- Los IDs de migración tienen el prefijo 'upgrade_' por defecto para evitar conflictos con plugins de migración del núcleo
Technical Details
Drush Commands 2
drush migrate:upgrade
Realiza una importación completa de la configuración y contenido del sitio Drupal 6 o 7 de origen al sitio Drupal 8+ de destino. También puede usarse con --configure-only para generar entidades de configuración de migración sin ejecutarlas.
drush migrate:upgrade-rollback
Revierte y elimina todo el contenido y entidades de configuración que fueron importados por una operación de actualización anterior. Identifica las actualizaciones por la clave de estado migrate_drupal_ui.performed. Nota: Los cambios de configuración simple (como el título del sitio) no se revierten ya que los valores originales no se preservan.
Troubleshooting 6
El comando requiere información de conexión a la base de datos. Proporcione --legacy-db-url con una URL de base de datos completa, o --legacy-db-key referenciando una conexión definida en settings.php (array $databases).
Asegúrese de que --legacy-root esté correctamente configurado. Para sitios remotos, use la URL completa (https://example.com). Para archivos locales, use la ruta absoluta del sistema de archivos al directorio raíz de Drupal. Los archivos deben ser accesibles en las ubicaciones estándar de archivos de Drupal (sites/default/files).
Ejecute migrate-upgrade en un sitio Drupal recién instalado. Si ya existe contenido, use migrate-upgrade-rollback primero, o reinstale el sitio.
Aumente el límite de memoria de PHP. Considere ejecutar migraciones en lotes usando --configure-only para generar configuraciones, luego usando migrate_tools con la opción --limit.
Las configuraciones se almacenan en la base de datos, no como archivos. Use drush cex para exportarlas, o verifique las entradas migrate_plus.migration.* en la tabla de configuración.
Cuando use esquemas PostgreSQL, establezca --legacy-db-prefix con el nombre del esquema con un punto al final, ej., --legacy-db-prefix='myschema.'
Security Notes 3
- Las credenciales de base de datos pasadas vía --legacy-db-url son visibles en listas de procesos e historial del shell. Use --legacy-db-key con settings.php para entornos de producción.
- Al exportar migraciones con --configure-only, las credenciales de base de datos pueden almacenarse en la configuración del grupo de migración. Revise y elimine credenciales antes de hacer commit a control de versiones.
- El módulo requiere acceso a la base de datos heredada que puede contener información sensible de usuarios. Asegúrese de que existan controles de acceso apropiados.