Drupal Migrations with Probo

Search Results

When migrating a site from an older version of Drupal to newer, Probo.CI lets you run the full migration on every pull request. Each build imports your legacy database alongside your new Drupal site, runs your migrations and gives you a live environment to review the results before anything touches production.

This page covers the build steps to run migrations - the migration modules and scripts themselves are assumed to already be part of your codebase.

Requirements

Your Drupal codebase needs the core migration modules and, if you use them, the contributed helpers in your composer.json file:

1	composer require drupal/migrate_plus drupal/migrate_tools

The core migrate, migrate_drupal and migrate_upgrade modules ship with Drupal. Upload your legacy site’s database as a build asset along with the database for the destination Drupal site.

Importing the Legacy Database

Use the Drupal plugin to install the Drupal site, then import the legacy database as a second database in a Script step:

type: lamp
php: 8.4
database: mariadb:11.4

assets:
  - drupal.sql.gz
  - legacy.sql.gz

steps:
  - name: Install Destination Drupal Site
    plugin: Drupal
    composer: true
    database: drupal.sql.gz
    databaseGzipped: true
    databaseUpdates: true
    clearCaches: true
    subDirectory: web
    drupalVersion: 11

  - name: Import Legacy Database
    plugin: Script
    script: |
      gunzip $ASSET_DIR/legacy.sql.gz
      mysql -uroot -pstrongpassword -e "CREATE DATABASE legacy;"
      mysql -uroot -pstrongpassword legacy < $ASSET_DIR/legacy.sql
      # Be sure to do housekeeping on your database assets
      rm $ASSET_DIR/legacy.sql

The migration system finds the legacy database through a named connection in your settings.php file. Add it inside a Probo.CI condition:

if (getenv('PROBO_ENVIRONMENT') === 'TRUE') {
  $databases['migrate']['default'] = [
    'database' => 'legacy',
    'username' => 'root',
    'password' => 'strongpassword',
    'prefix' => '',
    'host' => 'localhost',
    'port' => '3306',
    'namespace' => 'Drupal\Core\Database\Driver\mysql',
    'driver' => 'mysql',
  ];
}

Running the Migrations

Add a Script step after the database imports that enables the migration modules and runs the migrations with Drush:

  - name: Run Migrations
    plugin: Script
    script: |
      drush -r /var/www/html pm:enable migrate migrate_drupal migrate_upgrade migrate_plus migrate_tools -y
      drush -r /var/www/html migrate:upgrade --legacy-db-key=migrate --configure-only
      drush -r /var/www/html migrate:import --all
      drush -r /var/www/html migrate:status
      drush -r /var/www/html cr

The migrate:upgrade --configure-only command generates the migrations from your legacy site using the migrate database connection defined above. The migrate:import --all command then runs them, and migrate:status prints a summary of every migration into your build log so you can verify the counts on each build.

Migrations can take a while on large legacy databases. If your builds time out, consider using a trimmed copy of the legacy database as your build asset - enough content to prove the migrations work without importing every node.

Running Custom Migration Modules

If your migrations live in a custom module with its own migration group, enable your module and import by group or by individual migration ID instead of --all:

  - name: Run Custom Migrations
    plugin: Script
    script: |
      drush -r /var/www/html pm:enable my_custom_migrations -y
      drush -r /var/www/html migrate:import --group=my_migration_group
      drush -r /var/www/html migrate:import my_users,my_articles --update
      drush -r /var/www/html migrate:status --group=my_migration_group

If a migration fails partway through a build, migrate:reset-status and migrate:rollback are available in the same way:

1 2	drush -r /var/www/html migrate:reset-status my_articles drush -r /var/www/html migrate:rollback --group=my_migration_group

If any step in your migration fails, you can open a shell directly in the build’s container using the SSH Terminal link under the Advanced Functions section of the build page. From there you can manually run your migrations and commands to triage problems - check drush migrate:status, review errors with drush migrate:messages [migration_id], and re-run individual migrations until you find the fix to apply to your .probo.yaml file or migration code.

Migrating Files

If your migration imports files from the legacy site, upload them as a compressed build asset and extract them in a step before the migrations run. Point the migration at the extracted directory with the --legacy-root option:

assets:
  - drupal11.sql.gz
  - legacy.sql.gz
  - legacy-files.tar.gz

steps:
  - name: Extract Legacy Files
    plugin: Script
    script: |
      mkdir -p /var/www/legacy
      tar -xzf $ASSET_DIR/legacy-files.tar.gz -C /var/www/legacy
      rm $ASSET_DIR/legacy-files.tar.gz

  - name: Run Migrations
    plugin: Script
    script: |
      drush -r /var/www/html pm:enable migrate migrate_drupal migrate_upgrade migrate_plus migrate_tools -y
      drush -r /var/www/html migrate:upgrade --legacy-db-key=migrate --legacy-root=/var/www/legacy --configure-only
      drush -r /var/www/html migrate:import --all
      drush -r /var/www/html cr