Moving a MySQL database in Drupal is about keeping everything structured while upgrading, switching servers, or merging databases.
A well-planned approach ensures a smooth and well-executed transition.
Preparation is key:
Drupal provides tools like Drush and the Migrate API to simplify the process. The right approach depends on the site's size, structure, and hosting environment.
With careful planning and the right tools, the migration process keeps everything intact and running smoothly.
Let us walk through the key steps to ensure a seamless transition.
Understanding the source data
Before migrating, take a close look at the database. Check how tables are organized, how they connect, and where different fields come from. A clear database map helps everything move smoothly.
Start by identifying tables, primary keys, and relationships. Some data, like user accounts and content, is easy to migrate, while others—like custom fields, revisions, or module-specific tables—might need extra attention.
Look at the code and configurations to see where certain data is stored. If custom modules save information in unique ways, noting these details early makes the migration process easier.
Finally, match the source tables with Drupal’s content types, users, taxonomy, and configurations. This ensures everything ends up in the right place, keeping the site running as expected.
Setting up the migrate source database
Since the data is coming from a MySQL database, Drupal’s database source plugin allows for direct migration.
To get started, the source database needs to be added to Drupal’s configuration, ensuring that the migration process has access to both the original and destination databases.
This setup involves defining key details such as the database name, username, password, host, and driver. Once these details are configured, Drupal can connect to the source database and pull data without affecting the live site.
With the source database properly set up, the next step is to configure the migration to map data correctly from its current structure to the new one in Drupal.
Source database structure
Assume the source database has the following tables and fields:
articles Table
Target Drupal content type
In Drupal, the target content type for articles will map to the following fields:
Title: Mapped from articles.Title.
Article Type: Mapped from articles.ArticleType.
Body: Mapped from articles.Body.
Status: Mapped from articles.Status.
Defining the source database plugin
To migrate an article table into Drupal’s article content type, a source database plugin is needed. This plugin connects to the source database, retrieves the data, and prepares it for migration.
It ensures that each field from the original database matches the right place in Drupal. If the data structure is different, the plugin helps adjust it so everything fits correctly.
Once the plugin is set up, the migration process can use it to pull data smoothly, making sure nothing is missed or misplaced.
Here's how to properly define the source database plugin in src/Plugin/migrate/source/Article.php:
Setting up the migration plugin
To migrate data from the source database, a custom source plugin needs to be set up. This helps Drupal recognize and process the data correctly.
Once these steps are in place, the plugin can pull data smoothly and ensure everything is migrated properly into Drupal.
Define the migration YAML file
With the source database connection and plugin set up, the next step is creating the migration YAML file. This file outlines how data will be moved from the source database to Drupal, specifying the structure and field mappings.
The YAML file includes:
This file is placed in the module’s config/install directory. Once configured, it allows Drupal’s migration system to understand how to process and transfer data efficiently.
ID and label:
Migration group:
Source:
Process:
Destination:
Running the migration
After setting up the migration YAML file, the next step is to import the configuration and run the migration using Drush.
First, import the migration configuration so Drupal recognizes it.
Then, check the list of available migrations to ensure everything is set up correctly.
Once confirmed, run the migration to transfer data from the source database into Drupal.
This process moves the content while keeping its structure intact, ensuring a smooth transition.
Import the migration configuration
Use the following drush command to import the migration configuration:
Run the migration
Execute the migration with the following Drush command:
Verifying the migration
Once the migration is complete, check your Drupal site to make sure everything has been imported correctly.
Go to the content listing page and look for the migrated articles. Verify that all the data is there and matches the source database.
This step ensures that the migration was successful and that the content appears as expected.
Quick recap
Wrapping up
Migrating a MySQL database to Drupal is all about taking it step by step. With a clear understanding of the data structure, a well-planned migration setup, and the right tools, the process becomes smooth and predictable.
Each migration brings something new—sometimes a unique data structure or an unexpected format.
These details help refine the approach and build a deeper understanding of how data moves. Over time, recognizing patterns makes migrations even more efficient.
Here’s something useful: Drupal’s migration system is repeatable, allowing multiple test runs before finalizing, ensuring accuracy and fine-tuning the process without affecting the live site.
Next, we’ll look at one-to-many relationships in migrations— Migrating relational data into Drupal paragraphs.