Acquia Migrate Accelerate (AMA) lowers the barrier to entry for site builders to perform Drupal 7 to Drupal 9 migrations. However, your Drupal 7 site might have issues such as data model issues, which make the migration challenging and may need to be resolved. AMA provides insight into some of the changes that you need to make to your Drupal 7 site to migrate successfully, and insight into issues that you need to resolve on your Drupal 9 site. The changes in Drupal 7 tend to be data integrity problems that also affect the Drupal 7 site, such as missing values for the required fields.
Finally, after you complete the migration with AMA, custom modules and your custom theme need to be rebuilt as they cannot be migrated.
AMA extends Drupal’s powerful migration system by adding an intuitive user interface. It also provides support for hundreds of the most popular contrib modules. AMA automatically migrates you into Drupal 9 best practices, and includes data integrity checks with automatic suggestions on how to resolve migration messages to save your team’s countless hours.
For example, many competing files and media modules of Drupal 7 get their data migrated into Drupal 9 core’s media module. The data is then available through the Media Library.
Yes, you can do the following:
sites/sites.php file. If the file is
available, ensure that the default domain name of your source environment is
configured to use the site directory that you want to migrate. If there’s
only one site directory, AMA uses that one. Otherwise, it uses the default.
If there are multiple site directories and none is specified as default, the
migration environment fails to create successfully.WELCOME tag. If the tag is removed,
create a dummy “welcome” tag to avoid issues. The dummy tag can be empty
with only a text file.AMA does not officially support multi-site migrations. However, you can migrate one site at a time with AMA.
AMA is included with all Acquia Cloud Enterprise subscriptions. It is not available for Acquia Cloud Professional or Site Factory subscriptions. Reach out to your account manager to request the addition of AMA to your subscription. Then, ensure to set up the correct permissions for any non-admin users.
AMA generates a Drupal 9 codebase with the modules that you need to recreate your Drupal 7 site. After the codebase is generated, AMA helps you migrate your configuration, content types, and content to the new site. AMA does not migrate custom modules, views, or your custom theme. You can recreate them on your Drupal 9 site.
AMA includes a CD Environment specifically for your migration. This environment does not count against your CD Environment entitlements. AMA also includes a new Drupal 9 application with a new database and filesystem. You will also have access to the AMA module, and the Recommendations Engine that identifies the best Drupal 9 equivalents for your Drupal 7 modules.
The migration to Drupal 9 is a good opportunity to re-envision your site. AMA helps you perform a lift-and-shift migration from your Drupal 7 site to a new Drupal 9 site, and does not give you the opportunity to make big changes as part of the migration process. You can make changes to your site after you migrate everything you want to carry over to your Drupal 9 site.
The Recommendations Engine automatically includes the recommended migration path for every Drupal 7 module that is Drupal 9 compatible. Acquia updates this list regularly as more Drupal 7 modules are ported to Drupal 9. Acquia’s team has vetted the upgrade path for a subset of these modules, and includes patches to improve the migration as needed. The team has vetted over 200 Drupal 7 module upgrade paths so far, and is actively vetting new ones. Sometimes, certain modules claim to be Drupal 9 compatible, but they are actually not compatible. AMA’s Recommendation Engine also handles this for you.
Yes. After your Drupal 7 site runs through the Recommendations Engine, a Drupal 9 codebase is generated, and it includes the modules that you will need for your Drupal 9 site. The Modules tab in the AMA UI shows you the original Drupal 7 modules, with the Drupal 9 equivalents. The modules that are vetted by Acquia are automatically installed and enabled. Acquia is confident that they correctly migrate data for the vast majority of sites. You will have the opportunity to enable the recommended modules that are not vetted by Acquia. They are already downloaded using Composer, but not yet installed in Drupal.
Yes. AMA will automatically include these modules and automatically install the ones that Acquia’s team has vetted.
No, AMA cannot migrate views because Drupal cannot migrate views. However, it migrates everything you need to recreate your views.
No. AMA is specifically designed for Drupal 7 to Drupal 9 migration. Acquia recommends Acquia Migrate Re-Platform for migrations from other CMSes to Drupal 9.
AMA makes a copy of your Drupal 7 site’s production database and filesystem, and uses the copy as the migration source. Therefore, your production site does not have to support extra load during migrations.
Acquia knows that you’re always adding new content to your Drupal production site. To get the latest content to your in-progress Drupal 9 site, use the Refresh button in the Cloud Platform user interface to copy over the live production database and files to the migration environment. If you make significant changes to your Drupal 7 site (beyond adding/editing content), you may want to create a new migration environment to ensure that you include those changes in your Drupal 9 site.
No. Your Drupal 9 site remains in the “Read Only” mode until you promote your site to Dev or Stage, and remove the AMA module. This is by design — your Drupal 7 production site is the source of record for new content to prevent data loss on your new Drupal 9 site during the migration process.
You can create and tweak the configuration. For example, you can create views on your new Drupal 9 site. If you need to create a new migration environment, Acquia recommends that you export your configuration before doing so, to avoid having to repeat this work. You can re-import the exported configuration to your new migration environment.
When you click the Promote button, you can choose to promote your site to Dev or Stage. After selecting an environment, the Drupal 9 site is copied and promoted to the selected environment. The AMA module remains installed, but you cannot do migration activities on the promoted Drupal 9 site. The migration environment continues to exist, ready to do additional migration activities, if you choose to do so. For more information, see Finishing your Drupal 9 site.
When you are done with the migration, the AMA UI indicates that all migrations have completed. In addition, your migration should meet the following criteria:
At this point, you can promote your migration environment into your ACE subscription’s Dev or Staging environment using the Promote button in the Cloud Platform UI. After completing this step, uninstall the AMA Drupal module in the environment you promoted it to. This removes AMA-specific database tables and disables the “Read Only” mode.
The last 10-20% of a migration may require you to port your custom modules, or work through issues with your Drupal 7 site that are highlighted on the Messages tab in the Migrate UI. You may need to engage with Professional Services to work through these final pieces of the migration.
When you’ve finished migrating your site with AMA, you should do a final refresh of the content, and then promote your site to Dev or Stage using the Promote button in the Cloud Platform UI. For more information, see Finishing your Drupal 9 site.
Acquia CMS and AMA do not work together. AMA cannot transform data of existing sites to fit into Acquia CMS’s data model. You can use Acquia CMS, but it will not display your Drupal 7 data.
AMA is more than a module as it also includes auto-generating a Drupal 9 site based on your Drupal 7 site. However, there is an AMA module for Drupal and it runs in Drupal 9. Basically, AMA spins up a new Drupal 9 site, including the AMA module. You gradually migrate your Drupal 7 data to Drupal 9 by interacting with the AMA module.
There are several reasons why your migration environment might initially fail. Check for error messages in the task log in the Cloud Platform user interface, or go through the following checklist:
In your sites.php file, ensure that the default domain name of your
source environment is configured to use the site directory that you wish to
migrate. For more information, see I want to change the source database for my migration.
If your sites.php file is configured incorrectly, you might see an error
message similar the following:
Generating recommendations failed. If you have a docroot/sites/sites.php file, please make sure that the internal
Acquia domain https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the docroot/sites/ subdirectory that
you wish to migrate. See the documentation for details.
Some modules on Drupal.org claim to be compatible with Drupal 9. However, they actually cause issues when you install them in Drupal 9. The migration environment fails when one of these modules is installed. Acquia constantly monitors these modules, but new releases happen all the time. It’s possible that you’ve run into a recent regression. File a support ticket so that Acquia can block the module and help you move forward. You might see an issue similar the following:
Your requirements could not be resolved to an installable set of packages.
Check to ensure that your repository has a “welcome” tag. If you’ve removed it previously, you can recreate a dummy “welcome” tag (it can be empty with just a text file), and then the environment creation process should work as expected.
Check to ensure that you’re following Drupal and Acqiua best practices for Setting the private file directory on Acquia Cloud. If your site’s private file directory does not follow these best practices, it may cause issues.
The messages tab includes two types of messages that should be addressed differently:
Acquia Migrate Accelerate does not officially support multisite migrations. However, you can migrate one site at a time by changing the default database. Follow the steps in the section I want to change the source database for my migration to change the source database for your migration to do so.
Note
This is only necessary for sites that currently are or once were multisite.
If it’s a former multisite, Acquia recommends that you clean up your
codebase and delete the sites.php file.
Set up your internal Acquia FQDN to point to the same site as the one you want to migrate by doing the following:
In your sites.php file, ensure that the default domain name of your
source environment is configured to use the site directory that you want to
migrate. So, a line similar to the following is used if the multisite you
want to migrate resides in docroot/sites/foobar:
$sites['EXAMPLE.prod.acquia-sites.com] = 'foobar';
If there’s only one site directory, Acquia Migrate Accelerate uses that one. Otherwise, it uses the default.
If there’s more than one site directory and no default is specified, it fails with an error message similar the following:
Generating recommendations failed. If you have a ``docroot/sites/sites.php`` file, please make sure that the internal Acquia domain
https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the ``docroot/sites/`` subdirectory that you wish to migrate. See
the documentation for details.
Acquia Migrate Accelerate cannot migrate custom modules. However, you can port
the module to Drupal 9 and then add the module to the git branch that you’re
using for the AMA environment. Preferably using composer require companyname/modulename, to make it easy to version the module independently of the
migration environment, if it needs to be recreated.
If you do not see specific dependencies on the In Progress tab, check to see if you skipped them. If so, they appear on the Skipped tab. You must unskip them to add them back to the Migrations tab so that you can take action.
In other cases, there may be issues with the dependent migrations that you need to address before they can be successfully migrated. Click the module name to view the messages specifically related to that migration.
In some cases, you may have circular dependencies in your data model that prevent you from moving forward. In such a case, file a support ticket. You must provide a sanitized copy of your database so that the Acquia Support team can reproduce and troubleshoot your issue.
If you’ve encountered issues where using a new migration environment is the best course of action, you may need to destroy your existing environment and create a new one. Look for the trash can icon in the upper right corner of the migration environment.
When you create the new migration environment, you will get the latest version of the AMA module, the latest version of the Recommendations Engine will be applied to your Drupal 7 site, you’ll install a fresh D9 environment, and re-import the latest content from your D7 production site.
Before doing that, ensure that all of your code changes are committed to the Git branch that your AMA environment is using. The Git branch name is indicated on the AMA environment card, and starts with “ama-“.
The new migration environment creates a new branch that does not include any of
the work you did on your theme, your custom code, or any additional
configuration changes that you made previously. Incorporate the work that
you’ve already done by merging all the feature branches you were working on, or
by cherry picking the changes and adding them to the new branch. If you are
porting custom modules or themes, Acquia recommends to version each module or
theme individually so that you can use the composer require companyname/modulename command for each of them in your new migration environment. That
is simpler than moving over the work from the previous AMA branch.
If you need help with Git, see Resources for Learning Git in Acquia Knowledge Base.
For the AMA module, if there are new features or fixes that you need for your migration, you may be instructed to update to the latest version of the AMA module.
You do not need to start over with a new migration environment to take advantage of the latest features and fixes in the AMA module. Instead, run the following command on localhost or a Cloud IDE:
composer update acquia/acquia-migrate-accelerate --with-dependencies
Commit the result to Git. However, if you need to take advantage of features and fixes to the migrations recommendations or migration processing, you will need to recreate your migration environment.
With AMA’s Refresh function, you can copy over the live production database and file from your Drupal 7 site to the migration environment. After refreshing, you may see more content on the Refresh tab than what was changed. AMA is built upon Drupal’s migration system, which is unable to isolate the specific rows that were changed, so identifying the specific content types that were changed is definitely out of reach. The migration system knows which tables are changed, and so AMA identifies all of the migrations that rely on those tables as items to refresh.
For example, if a single node (an article, page, or blog) was created, the migration system does not know which of those types of content needs to be refreshed. Therefore, AMA marks them all as needing a refresh, and all appear on the Refresh tab.
Yes, the AMA-generated composer.json is restricting versions of just about every module, for two reasons:
After the migration is complete, you uninstall the acquia_migrate,
migrate_drupal, and migrate modules. After that, there is no more
need for patches that add or fix migrations. At this point, you can remove the
patches and also make all of the version constraints
less restrictive. For example, AMA currently recommends drupal/user_hash 2.0.0 with this patch:
"require": {
…
"drupal/user_hash": "2.0.0",
…
},
"extra": {
…
"patches": {
…
"drupal/user_hash": {
"Issue #3232037: Configuration missing while D7 to D9 migration": "https://www.drupal.org/files/issues/2021-09-09/configuration_missing-3232037-2.patch"
},
…
},
…
If you delete that patch, you end up with:
"patches": {
…
}
then you can also loosen the version constraint, which means you end up with:
"require": {
…
"drupal/user_hash": "^2",
…
},
"extra": {
…
"patches": {
…
},
…
Now, run composer install to see:
$ composer update drupal/user_hash
Gathering patches for root package.
Loading composer repositories with package information
Updating dependencies
Lock file operations: 0 installs, 1 update, 0 removals
- Upgrading drupal/user_hash (2.0.0 => 2.0.1)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 0 installs, 1 update, 0 removals
- Downloading drupal/user_hash (2.0.1)
Gathering patches for root package.
Gathering patches for dependencies. This might take a minute.
- Upgrading drupal/user_hash (2.0.0 => 2.0.1): Extracting archive
Generating autoload files
43 packages you are using are looking for funding.
Use the `composer fund` command to find out more!
In this example, composer found the newest version matching the constraint
^2. You’ll have to repeat this process for every package that has a
specific version pinned. Composer unfortunately makes this hard to automate.
Besides, you’ll want to do this gradually to ensure everything continues to
work. You may have added patches of your own, which you do not want to remove.
Every Drupal site is different, and so is every Drupal 7 to 9 migration. Your migration might run into an issue that Acquia Migrate Accelerate has not seen before. When this happens, the AMA team requests a “sanitized database” from your Drupal 7 site so that they can reproduce the issue and develop a resolution that will help you move forward, and ensure that others do not run into the same issue. The following are the instructions for creating a sanitized database on Acquia Cloud:
Back up your development environment database.
Copy your production database to your development environment.
SSH into your application and run the following command to generate the sanitized database:
drush sql-sanitize
Share the file with Acquia’s Support team by attaching it to the support ticket.
Restore the backed up database to your development environment.
53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842