Actualización con Drush

Drush es una interfaz de línea de comandos y un entorno de scripting para Drupal. Actualizar a Drupal 8 usando Drush es una alternativa a utilizar la interfaz de usuario del navegador. Actualizar a Drupal 8 con Drush es muy útil al migrar sitios complejos, ya que permite ejecutar migraciones una por una y realizar reversiones.

Instalación de Drush usando Composer

Los sitios Drupal 8 pueden construirse con Composer. Si decides usar drupal-composer/drupal-project como plantilla de proyecto Composer, ya tendrás Drush porque está listado como dependencia en el archivo composer.json del proyecto.

Si Drush no está listado como dependencia en tu proyecto Composer, puedes instalar Drush desde la línea de comandos así:

composer require drush/drush

Nota: usa Drush 9 ahora

Debido a un problema con Drush 10, por el momento se recomienda instalar Drush 9 con composer, requiriendo drush/drush: ^9.0, lo que lleva a la versión 9.7.2. 

Esto te dará la última versión estable de Drush, que debería ser compatible con la última versión de Drupal. Más detalles están en la matriz de compatibilidad de versiones entre Drush y Drupal.

Para comprobar tu versión de Drush, usa

drush --version

Módulos requeridos de Drupal

Para migrar usando Drush, necesitas descargar e habilitar los siguientes módulos añadidos:

• Migrate Upgrade: proporciona soporte para Drush para actualizar de Drupal 6 o 7 a Drupal 8.
• Migrate Plus: ofrece extensiones para la funcionalidad básica del mecanismo de migración.
• Migrate Tools: provee comandos Drush que se usan más adelante en esta página.

¡IMPORTANTE! Presta especial atención a elegir la versión correcta para cada uno de estos tres módulos. Por favor, consulta la página del proyecto para elegir la versión compatible con tu versión del núcleo Drupal 8.

Para más información sobre los distintos módulos de actualización, por favor consulta la lista de módulos de actualización.

Define la base de datos fuente

Este es un ejemplo de cómo definir los detalles de conexión a la base de datos para tu sitio Drupal 6/7 fuente. Si tu sitio fuente usa prefijos en la base de datos, asegúrate de incluirlos. Necesitarás conectarte tanto a la base de datos local de desarrollo (default/por defecto) como a la base de datos fuente (D6 o D7). Abajo hay un ejemplo usando Lando. El ejemplo incluye la base de datos por defecto configurada para mayor completitud.

Nota. Para evitar problemas, es importante nombrar la clave de la base de datos migratoria correctamente, véase la sección "Obtención de error de campo para el núcleo Drupal versión 7" durante la migración.

Ejemplo de conexión a base de datos en settings.php

$databases['default']['default'] = [
  'database' => 'drupal8',
  'username' => 'drupal8',
  'password' => 'drupal8',
  'prefix' => '',
  'host' => 'database',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

$databases['migrate']['default'] = [
  'database' => 'drupal7db',
  'username' => 'drupal7db',
  'password' => 'drupal7db',
  'prefix' => '',
  'host' => 'd7db',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

Ejemplo de .lando.yml

name: mywebsite
recipe: drupal8
config:
  webroot: web

# Crear servicio de base de datos Drupal 7, considera agregar phpmyadmin
services:
  d7db:
    type: mariadb
    creds:
      user: drupal7db
      password: drupal7db
      database: drupal7db
    portforward: true

Importa la base de datos Drupal 7, asumiendo que el archivo dump de la base de datos se llama mywebsite_db.sql.gz y está en la carpeta actual:

lando db-import --host=d7db --user=drupal7db mywebsite_db.sql.gz

Inspirado en https://github.com/thinktandem/migration_boilerplate.

Generación de migraciones usando migrate-upgrade

El módulo añadido Migrate Tools agregará comandos Drush como drush migrate-status y drush migrate-import. La lista completa de comandos Drush relacionados con migración está al final de esta página.

Si intentas ejecutar el comando drush migrate-status sin hacer nada más, no verás migraciones disponibles para ejecutar. Esto es porque las migraciones individuales deben crearse primero basándose en tu base de datos fuente. Como Migrate no sabe qué fuente usar, aún no existen migraciones.

Para generar migraciones necesitarás el comando Drush drush migrate-upgrade, que proporciona el módulo de actualización Migrate Upgrade.

Lo más probable es que quieras generar solo migraciones individuales para poder ejecutarlas una por una. Para esto, necesitas usar el parámetro --configure-only

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://example.com --configure-only 

donde

• 'user' es el nombre de usuario de la base de datos fuente.
• 'password' es la contraseña del usuario de la base de datos fuente.
• 'server' es el servidor de la base de datos fuente.
• 'db' es la base de datos fuente.
• 'http://example.com' es la raíz de tu sitio fuente. Si el sitio antiguo está en el sistema de archivos local, puedes usar la ruta al directorio raíz de Drupal como valor para esta opción. El valor que pongas aquí se añadirá a las rutas de archivos individuales para encontrarlos e importarlos.

La opción --legacy-db-key te permite usar el arreglo $database con la clave correspondiente definida en settings.php.

Si tu sitio fuente usa prefijo de tabla en los nombres de tablas de la base de datos, debes añadirlo como argumento adicional así. En este ejemplo, el prefijo de base de datos es "drupal_":

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-db-prefix=drupal_ --legacy-root=http://example.com --configure-only 

Si no usas la opción --configure-only, drush migrate-upgrade generará primero y luego ejecutará todas las migraciones.

Después de ejecutar migrate-upgrade con --configure-only, ejecuta migrate-status para ver la lista de migraciones posibles:

drush migrate-status

Luego puedes revisar y ejecutar esas migraciones de forma selectiva. Para ejecutar una migración individualmente usa:

drush migrate-import <migration name> 

Para ejecutar todas las migraciones en la lista, ejecuta:

drush migrate-import --all 

Ejecutar migraciones específicas usando migrate-manifest

También puedes usar un archivo manifest para configurar un conjunto específico de migraciones. Esto permite reproducir grupos de migraciones de manera repetible. Para este método también necesitarás el módulo Migrate Manifest. Con Migrate Manifest puedes obtener una lista completa de migraciones disponibles usando los siguientes comandos:

drush migrate-template-list # Drush 8

o

drush migrate:template:list # Drush 9

Nota: Actualmente el módulo Migrate Manifest no es completamente compatible con Drush 10+.

Las migraciones deseadas se definen como un archivo YAML, como muestra el ejemplo abajo. Solo necesitas listar las migraciones que requieres. Migrate Manifest te pedirá que agregues migraciones adicionales necesarias para resolver dependencias. Las migraciones pueden listarse en cualquier orden, se ejecutarán en el orden correcto basado en las dependencias.

# usuario 
- d6_user 
- d6_user_profile_field 
- d6_user_profile_field_instance 
- d6_user_profile_entity_display 
- d6_user_profile_entity_form_display 
- d6_profile_values:user 
- d6_filter_format 
- d6_user_role 
- d6_user_picture_entity_display 
- d6_user_picture_entity_form_display 
- d6_user_picture_file 
- d6_user_picture_field 
- d6_user_picture_field_instance 

# taxonomía 
- d6_taxonomy_vocabulary 
- d6_taxonomy_settings 
- d6_taxonomy_term 

# nodos 
- d6_node 
- d6_node_revision 
- d6_node_type 
- d6_view_modes 
- d6_filter_format 
- d6_field_instance_per_form_display 
- d6_field_instance_widget_settings 
- d6_field_formatter_settings 
- d6_field_instance 
- d6_field 
- d6_field_settings 
- d6_node_settings 
- d6_cck_field_values:* 
- d6_cck_field_revision:* 

# campos de taxonomía 
- d6_term_node_revision 
- d6_term_node 
- d6_vocabulary_entity_display 
- d6_vocabulary_entity_form_display 
- d6_vocabulary_field_instance 
- d6_vocabulary_field 

# bloques 
- d6_block 
- d6_menu 

# bloques personalizados 
- d6_custom_block 
- d6_filter_format 

# libro 
- d6_book 
- d6_book_settings 

# las migraciones de archivos son configurables, ver https://www.drupal.org/node/2257723 
- d6_file: 
    source: 
      conf_path: sites/assets 
    destination: 
      source_base_path: destination/base/path 
      destination_path_property: uri 

Coloca el archivo manifest en una ubicación accesible al ejecutar Drush. Se recomienda guardarlo en tu sistema de control de versiones para poder rastrear cambios en tus migraciones.

Asegúrate de que los módulos usados por las migraciones listadas en el archivo manifest existen y están habilitados en el sitio fuente (por ejemplo, el módulo de campo para d6_field). De lo contrario, se producirán errores al ejecutar las migraciones.

Las migraciones definidas en el archivo manifest se ejecutan desde la línea de comandos como se muestra abajo. Reemplaza la URL de la base de datos y la ruta al archivo manifest con los valores correspondientes (por ejemplo, migrate-upgrade, migrate-manifest aceptan URL MySQL o clave del arreglo en settings.php):

drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/drupal_6 manifest.yml 

Notas para usuarios de Acquia Dev Desktop

Si usas Acquia Dev Desktop y tienes un sitio Drupal 6 en Dev Desktop, las credenciales por defecto de la base de datos son drupaluser sin contraseña y puerto 33067 para la base de datos en la IP 127.0.0.1. Esto significa que en los comandos --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 se asume que el nombre de la base de datos es drupal_6. Ejecuta drush status si tienes problemas de conexión para verificar estos valores.

Guía de comandos de migración Drush

migrate-upgrade (sin alias)

Proporcionado por el proyecto Migrate Upgrade. Úsalo para iniciar la actualización de Drupal 6/7 a Drupal 8. Este comando generará configuraciones de migración basadas en la configuración y contenido del sitio fuente.

Consulta ejemplos más arriba en esta documentación.

Ejemplo principal

drush migrate-upgrade --legacy-db-key=migrate

Opciones

• legacy-db-url: información de conexión a la base de datos para la base de datos fuente.
• legacy-db-prefix: prefijo de tabla para la base de datos fuente.
• legacy-root: ruta al sitio fuente, usada para acceder al contenido en el directorio de archivos. Si los archivos son privados, debe usarse la ruta local, para archivos públicos también funciona http(s).
• configure-only: usa esto para crear solo las configuraciones de migración. Cuando esta opción está activada, las migraciones se generan para poder ejecutarse individualmente con "drush migrate-import".

migrate-status (ms)

Proporcionado por el módulo Migrate Tools. Úsalo para obtener una lista de todas las migraciones con su estado actual.

Ejemplo principal

drush migrate-status

migrate-import (mi)

Proporcionado por el módulo Migrate Tools. Úsalo para ejecutar una o varias migraciones. Normalmente se usa con migraciones personalizadas desde fuentes no Drupal. Por ejemplo, si has creado e importado una configuración de migración personalizada, este comando puede usarse para ejecutarla.

Ejemplos principales

drush migrate-import migration_id
drush migrate-import --group=files

Opciones

• all: ejecuta todas las migraciones configuradas.
• group: ejecuta todas las migraciones de un grupo específico.
• limit: límite en la cantidad de elementos procesados por migración.
• feedback: frecuencia de mensajes de progreso en elementos procesados.
• idlist: lista separada por comas de IDs de fuente para importar.
• update: migra nuevos elementos y también los previamente migrados que han cambiado en la fuente.
• force: fuerza la ejecución aunque haya dependencias no cumplidas.

Casos de uso comunes

• Cuando se usa migrate-upgrade --configure-only, se crean objetos de configuración. Como Drupal 8 por defecto no permite sobreescribir objetos existentes, migrate-upgrade no puede usarse para ejecutar migraciones después de migrate-upgrade --configure-only. En su lugar, usa migrate-import.
• Cuando una migración personalizada es creada e importada (por la UI de configuración o drush config-import), usa migrate-import para ejecutarla.

Consejo profesional: si importaste una configuración de migración personalizada y necesitas actualizarla y reimportarla, usa el módulo Configuration Update Manager.

migrate-rollback (mr)

Proporcionado por el módulo Migrate Tools. Úsalo para revertir una migración. Normalmente se usa para pruebas o si tuviste problemas y necesitas comenzar de nuevo. Usa con el ID o grupo de migración.

Ejemplos principales

drush migrate-rollback migration_id
drush migrate-rollback --group=files

migrate-stop (mst)

Proporcionado por el módulo Migrate Tools. Úsalo para detener una operación de migración activa.

Ejemplo principal

drush migrate-stop migration_id

migrate-reset-status (mrs)

Proporcionado por el módulo Migrate Tools. Úsalo para restablecer el estado de una migración activa a pendiente.

Ejemplo principal

drush migrate-reset-status migration_id

migrate-messages (mmsg)

Proporcionado por el módulo Migrate Tools. Úsalo para ver mensajes relacionados con una migración. Es útil cuando fallan migraciones, para saber la causa del fallo.

Ejemplo principal

drush migrate-messages migration_id

migrate-fields-source (mfs)

Proporcionado por el módulo Migrate Tools. Úsalo para listar los campos disponibles para mapeo en la fuente.

Ejemplo principal

drush migrate-fields-source migration_id