Migrating from Drupal 7 to Backdrop

Before migrating from Drupal 7 to Backdrop, we recommend to read through the official documentation page on Upgrading from Drupal 7 and it's sub-sections:

• Features added to core
• Features removed from core
• Top 100 Drupal 7 modules

There is also very nice slideshow available on https://backdrop-ops.github.io/slides/upgrade.html.

For complete upgrade instructions, please see the documentation on Upgrading from Drupal 7 on the API site.

There are few nuances to add if you are developing using AltaGrade Developer Stack for Backdrop:

1. Prepare Drupal 7 website for migration

Turn of all the contributed modules on your Drupal 7 website and dump its database with drush sql-dump > db.sql command. Compress the files directory and the database dump and place them in the /var/www/drupal7 directory of your Backdrop development setup (see step 2). That's all you need to take from your Drupal 7 website.

2. Create a new Backdrop website

Create a new Backdrop website using the AltaGrade Developer Stack for Backdrop, switch into service's container shell running the fin bash command and empty the website's database:

brush sql-drop -y

3. Copy the files directory and the database

Copy the files directory and the database dump-file to your Backdrop codebase and import the database.

rm -rf /var/www/docroot/files
mv /var/www/drupal7/* /var/www/docroot
cd /var/www/docroot
brush sql-cli < db.sql
rm -f db.sql

4. Create a temporary symlink

Create a temporary symlink to be able to run the upgrade script:

mkdir /var/www/docroot/sites/default
ln -s /var/www/docroot/files /var/www/docroot/sites/default

5. Open access to update script

Set the $settings['update_free_access'] option in settings.php file to TRUE by running the following one-liner:

sed -i -e "s@$settings\['update_free_access'\] = FALSE;@$settings\['update_free_access'\] = TRUE;@" /var/www/docroot/settings.php

If didn't work, then just do the replacement manually with nano editor:

nano /var/www/docroot/settings.php

then press CTRL+x, then y and exit nano.

6. Run the update script

Open https://backdrop.docksal/update.php in your browser and proceed with the update.

7. Change the file system path

After the upgrade script completes, login to your new Backdrop website using the one-time login URL generated with the brush uli command, go to https://backdrop.docksal/admin/config/media/file-system and update the Public file system path setting to files.

8. Clean the database and remove the symlink

This step is optional and not required if you decide to leave the temporary symlink created on step 4 forever. In that case, your Backdrop site will be serving all the links to files directory created on your old Drupal 7 website using the symlink.

However, if you would like to get rid of the symlink, then you need to find all the occurrences of sites/default/files in database and replace them all with just files. Usually, the following database tables might contain the old Drupal 7 style links:

field_data_body
field_revision_body
field_data_comment_body
field_revision_comment_body
files
locales_source
menu_router

Since each of the above database tables may have multiple columns containing occurrences of sites/default/files, you need to find all of them (for example, using the phpMyAdmin interface located at http://pma.YourBackdropSite.docksal) and run the UPDATE db_table SET db_column = REPLACE(db_column, 'sites/default/files', 'files').

Alternatively, you can just fire up the following brush commands on the command line:

brush sql-query "UPDATE field_data_body SET body_value = REPLACE(body_value, 'sites/default/files', 'files')"
brush sql-query "UPDATE field_data_body SET body_summary = REPLACE(body_summary, 'sites/default/files', 'files')"
brush sql-query "UPDATE field_revision_body SET body_value = REPLACE(body_value, 'sites/default/files', 'files')"
brush sql-query "UPDATE field_revision_body SET body_summary = REPLACE(body_summary, 'sites/default/files', 'files')"
brush sql-query "UPDATE field_data_comment_body SET comment_body_value = REPLACE(comment_body_value, 'sites/default/files', 'files')"
brush sql-query "UPDATE field_revision_comment_body SET comment_body_value = REPLACE(comment_body_value, 'sites/default/files', 'files')"
brush sql-query "UPDATE files SET filepath = REPLACE(filepath, 'sites/default/files', 'files')"
brush sql-query "UPDATE locales_source SET location = REPLACE(location, 'sites/default/files', 'files')"
brush sql-query "UPDATE menu_router SET path = REPLACE(path, 'sites/default/files', 'files')"

Now, finally you can delete the symlink:

rm -rf /var/www/docroot/sites/default/files