Migration des relations de base de données plusieurs-à-plusieurs vers Drupal : Guide complet

Ce guide parcourt le processus complet de migration de ces relations en utilisant l'API Migrate de Drupal. Vous apprendrez comment gérer les tables de jonction, créer des références d'entités appropriées et éviter les pièges courants qui peuvent faire dérailler votre projet de migration.

Basé sur des travaux de projets avec des clients en transition depuis des systèmes hérités, nous avons constaté que comprendre les différences fondamentales entre les structures de bases de données relationnelles et le système d'entités de Drupal est crucial pour le succès. Les techniques couvertes ici fonctionnent avec Drupal 11 et s'appliquent aux migrations depuis MySQL, PostgreSQL et autres bases de données relationnelles.

Comprendre les relations de base de données plusieurs-à-plusieurs dans le contexte de migration Drupal

Les bases de données relationnelles traditionnelles utilisent des tables de jonction pour gérer les relations plusieurs-à-plusieurs. Par exemple, un système de commerce électronique pourrait avoir :

• table products : `id`, `name`, `description`
• table categories : `id`, `name`, `slug`
• table product_categories : `product_id`, `category_id`

Cette structure permet aux produits d'appartenir à plusieurs catégories et aux catégories de contenir plusieurs produits. La table de jonction stocke les paires de relations.

Drupal aborde cela différemment. Au lieu de tables de jonction, Drupal utilise des champs de référence d'entité qui peuvent contenir plusieurs valeurs. Un type de contenu produit aurait un champ « Catégories » multi-valeur qui référence directement les termes de taxonomie.

Cette différence architecturale signifie que votre stratégie de migration doit transformer les données de table de jonction en données de champ multi-valeur. L'API Migrate fournit des outils pour gérer cette transformation, mais vous devez structurer votre approche correctement.

Préparer vos données source pour la migration Drupal

La clé du succès de la migration plusieurs-à-plusieurs réside dans la préparation des données. Plutôt que de migrer la table de jonction séparément, vous voudrez agréger les données liées directement dans votre requête source.

Voici comment préparer les relations article-vers-étiquette en utilisant l'agrégation SQL :

SELECT 
  a.id AS article_id,
  a.title,
  a.body,
  a.created,
  GROUP_CONCAT(at.tag_id ORDER BY at.tag_id) AS tag_ids
FROM articles a
LEFT JOIN article_tag at ON a.id = at.article_id  
GROUP BY a.id, a.title, a.body, a.created;

Cette requête produit une ligne par article avec tous les ID d'étiquettes liées comme une chaîne séparée par des virgules. La clause `ORDER BY` assure un ordre cohérent, ce qui aide avec le débogage et les tests.

Lors du travail avec des clients, nous recommandons de tester cette requête d'agrégation minutieusement avant de construire votre migration. Vérifiez les cas limites comme les articles sans étiquettes, les articles avec des attributions d'étiquettes dupliquées, ou des listes d'étiquettes inhabituellement longues qui pourraient atteindre les limites de base de données.

Configurer votre structure de migration Drupal

Les migrations plusieurs-à-plusieurs réussies nécessitent un ordre d'opérations spécifique. Vous devez migrer les entités référencées (étiquettes) avant les entités référençantes (articles). Cela assure que les champs de référence d'entité peuvent proprement lier aux entités existantes.

Migrer les entités référencées en premier

Commencez avec la migration plus simple pour vos entités référencées :

id: migrate_tags
label: Import Tags
migration_group: content_migration
source:
  plugin: table
  table_name: tags
  fields:
    - id
    - name
    - slug
  ids:
    id:
      type: integer
process:
  name: name
  field_slug: slug
destination:
  plugin: entity:taxonomy_term
  default_bundle: tags

Cela crée des termes de taxonomie pour chaque étiquette dans votre base de données source. L'ID de migration (`migrate_tags`) devient important pour l'étape suivante : la migration d'article référencera cette migration par nom.

Migrer les articles avec des références d'entité

La migration d'article gère la relation plusieurs-à-plusieurs à travers le processus `field_tags` :

id: migrate_articles
label: Import Articles with Tag References
migration_group: content_migration
migration_dependencies:
  required:
    - migrate_tags
source:
  plugin: table
  table_name: articles
  fields:
    - id
    - title
    - body
    - created
    - tag_ids
  ids:
    id:
      type: integer
process:
  title: title
  body/value: body
  body/format:
    plugin: default_value
    default_value: basic_html
  created: created
  field_tags:
    plugin: explode
    source: tag_ids
    delimiter: ','
    process:
      plugin: migration_lookup
      migration: migrate_tags
      source: '@value'
destination:
  plugin: entity:node
  default_bundle: article

Le processus `field_tags` fait deux choses :

• Explode divise les ID d'étiquettes séparées par des virgules en un tableau
• Migration lookup convertit chaque ID d'étiquette source vers l'ID d'entité Drupal correspondant

Les `migration_dependencies` assurent que les étiquettes sont migrées avant les articles, prévenant les erreurs de référence.

Gérer les relations de paragraphe complexes dans Drupal

Les relations plusieurs-à-plusieurs deviennent plus complexes quand elles impliquent des entités de paragraphe. Considérez un système de recettes où chaque recette a plusieurs ingrédients, et chaque ingrédient contient plusieurs champs (nom, quantité, unité).

Notre approche implique la création d'un plugin de processus personnalisé pour structurer les données agrégées correctement :

getSourceProperty($field_name));
      foreach ($field_values as $key => $field_value) {
        if (!empty($field_value)) {
          $aggregated_fields[$key][$field_name] = $field_value;
        }
      }
    }
    
    return array_values($aggregated_fields);
  }
}

Ce plugin prend plusieurs valeurs de champ séparées par des barres verticales et les structure en tableaux adaptés pour la création de paragraphe. La configuration de migration correspondante utilise ce plugin avec `entity_generate` :

process:
  _recipe_ingredients:
    plugin: recipe_related_fields_aggregator
    source: RecipeIngredientsFields
  field_ingredients:
    - plugin: sub_process
      source: '@_recipe_ingredients'
      process:
        _ingredient_name: ingredient_name
        _quantity: quantity
        _unit: unit
        target_id:
          plugin: entity_generate
          entity_type: paragraph
          bundle: recipe_ingredient
          values:
            field_ingredient_name/0/value: '@_ingredient_name'
            field_quantity/0/value: '@_quantity'
            field_unit/0/value: '@_unit'
        target_revision_id:
          plugin: entity_value
          source: '@target_id'
          entity_type: paragraph
          field_name: revision_id

Le plugin `entity_generate` crée des entités de paragraphe à la volée pendant la migration, ce qui est parfait pour les relations uniques qui n'ont pas besoin d'être partagées entre plusieurs entités parentes.

Exécuter et gérer votre migration Drupal

L'exécution de migration nécessite une attention minutieuse à l'ordre et aux dépendances. Nous recommandons ce flux de travail pour la plupart des projets :

Exécution initiale de migration

# Vérifier le statut de migration
drush migrate:status --group=content_migration

# Importer les entités référencées en premier
drush migrate:import migrate_tags

# Importer les entités principales avec les relations
drush migrate:import migrate_articles

# Vérifier les résultats
drush migrate:status --group=content_migration

Gérer les mises à jour et changements

Quand les données source changent, vous pouvez mettre à jour les migrations existantes plutôt que de recommencer :

# Mettre à jour seulement les enregistrements modifiés
drush migrate:import migrate_tags --update

# Synchroniser les changements vers les articles
drush migrate:import migrate_articles --update

L'indicateur `--update` compare les données source avec le contenu précédemment migré et ne traite que les changements. Cela économise un temps significatif sur les grands ensembles de données.

Résoudre les problèmes courants de migration Drupal

Références d'entité manquantes

Si vos champs de référence d'entité apparaissent vides après la migration, vérifiez ces causes communes :

Problèmes de données source : Vérifiez que votre requête d'agrégation produit les résultats attendus. Testez d'abord avec un petit sous-ensemble.

Dépendances de migration : Assurez-vous que les entités référencées sont migrées avant les entités référençantes. Utilisez `migration_dependencies` dans votre YAML.

Configuration de champ : Confirmez que votre champ de référence d'entité permet plusieurs valeurs et référence le bon type d'entité.

Problèmes de performance

Les grands ensembles de données plusieurs-à-plusieurs peuvent causer des problèmes de mémoire. Notre équipe utilise ces stratégies :

Traitement par lots : Configurez votre migration pour traiter les enregistrements en plus petits lots :

source:
  plugin: table
  table_name: articles
  batch_size: 100

Optimisation de base de données : Ajoutez des index à vos tables de jonction source, surtout sur les colonnes de clé étrangère.

Surveillance de mémoire : Utilisez `drush migrate:import --feedback=100` pour surveiller le progrès et détecter les problèmes tôt.

Références dupliquées

Les tables de jonction contiennent parfois des relations dupliquées. Gérez cela dans votre requête d'agrégation :

SELECT 
  a.id AS article_id,
  a.title,
  GROUP_CONCAT(DISTINCT at.tag_id ORDER BY at.tag_id) AS tag_ids
FROM articles a
LEFT JOIN article_tag at ON a.id = at.article_id
GROUP BY a.id, a.title;

Le mot-clé `DISTINCT` élimine les doublons avant l'agrégation.

Modèles de migration avancés pour les relations complexes

Relations conditionnelles

Parfois vous devez migrer des relations basées sur des conditions. Utilisez le plugin de processus `skip_on_empty` :

field_tags:
  plugin: explode
  source: tag_ids
  delimiter: ','
  process:
    - plugin: skip_on_empty
      method: process
    - plugin: migration_lookup
      migration: migrate_tags
      source: '@value'

Cela ignore les références d'étiquette vides tout en traitant les valides.

Dépendances inter-migrations

Les systèmes complexes nécessitent souvent des relations entre différents groupes de migration. Utilisez `migration_dependencies` avec des migrations externes :

migration_dependencies:
  required:
    - migrate_users
    - migrate_tags
  optional:
    - migrate_media

Les dépendances requises doivent se compléter avec succès avant que votre migration s'exécute. Les dépendances optionnelles s'exécutent si disponibles mais ne bloquent pas votre migration.

Valider vos résultats de migration

Après la migration, validez que vos relations plusieurs-à-plusieurs ont été transférées correctement :

Vérification de base de données

Vérifiez que les champs de référence d'entité contiennent les données attendues :

SELECT 
  n.nid,
  n.title,
  GROUP_CONCAT(t.name) AS tags
FROM node n
JOIN node__field_tags ft ON n.nid = ft.entity_id
JOIN taxonomy_term_field_data t ON ft.field_tags_target_id = t.tid
WHERE n.type = 'article'
GROUP BY n.nid, n.title
LIMIT 10;

Vérification de contenu

Révisez un échantillon de contenu migré à travers l'interface Drupal pour vous assurer que les relations s'affichent correctement et que les flux de travail éditoriaux fonctionnent comme prévu.

Notre équipe valide typiquement 5-10% du contenu migré manuellement, en se concentrant sur les cas limites comme les entités avec plusieurs relations ou des structures de paragraphe complexes.

Planifier votre prochaine migration

Migrer avec succès les relations plusieurs-à-plusieurs nécessite de comprendre à la fois la structure de vos données source et le système d'entités de Drupal. Les techniques couvertes ici fonctionnent pour la plupart des migrations de bases de données relationnelles, mais les systèmes hérités complexes peuvent nécessiter des plugins personnalisés additionnels ou des étapes de transformation de données.

Lors de la planification de votre projet de migration, allouez du temps pour l'analyse des données, les tests avec de petits ensembles de données et la validation minutieuse. Les relations plusieurs-à-plusieurs révèlent souvent des problèmes inattendus de qualité de données qui nécessitent attention avant la migration complète.

Si vous faites face à une migration complexe avec des échéanciers serrés ou des structures de données inhabituelles, considérez travailler avec des développeurs expérimentés qui peuvent aider à naviguer les défis techniques tout en assurant que votre contenu transite en douceur vers Drupal.