AWS RDS migration guide
Learn how to import your database from AWS RDS into PlanetScale.
This document will demonstrate how to migrate a database from AWS Relational Database Services (RDS) to PlanetScale. We’ll also address some common issues associated with migrating from RDS and how to resolve them.
This guide assumes you are using MySQL on RDS. Other database systems available through RDS will not work with the PlanetScale import tool.
Before you can perform a migration, you’ll need to make sure the following is configured:
You’ll also need to gather the following pieces of information from the AWS Console:
Master username & password
The endpoint address and port number are located in the database view under “Connectivity & security”.
The Connectivity & security tab of the database in RDS.
The master username can be located under the “Configuration” tab. The master password will be the password used when the database was first created.
The Configuration tab of the database in RDS.
If you don’t know the admin password, you can create a new set of credentials using the information on the Import tool user permissions page to create an account that can be used to import your database.
Configuring the RDS security group
In order for PlanetScale to connect to your RDS database, you must allow traffic into the database through the associated security group. The specific IP addresses you will need to allow depend on the region you plan to host your PlanetScale database. Check the Import tool public IP addresses page to determine the IP addresses to allow before continuing. This guide will use the AWS us-east-1 (North Virginia) region so we’ll allow the following addresses:
To allow traffic to your database in AWS, navigate to the “Connectivity & security" tab of the database, and click the link under VPC security groups.
The Connectivity & security tab of the database view in RDS.
In the lower pane of the next page, select the “Inbound rules” tab, then “Edit inbound rules”.
The view of security groups associated with the RDS instance.
Click the “Add rule” button, and a new line will be added to the list of rules. Select “MYSQL/Aurora” as the Type and enter the first IP address from the list for your region. AWS will automatically reformat it to
x.x.x.x/32, so you can select that when it appears. You’ll need to repeat this for every IP address you need to allow.
The Edit inbound rules view where source traffic can be allowed.
Once you are finished adding all of the necessary IP addresses for the selected region, click “Save rules” to apply the changes.
Importing your database
In the PlanetScale dashboard, click “New database”, then “Import database”.
The default view of all databases in the PlanetScale organization.
At the time of this writing, the Import database feature is in beta. If this is your first time accessing this feature, you will be prompted to opt into using the feature. Click “Join beta” to proceed.
The Join beta view.
Complete the form using the information gathered in the previous section. Click “Connect to database” and the import tool will attempt to connect to your RDS instance.
The Import external database form.
If the connection was successful, you’ll see the following message. Click “Begin database import” to start importing data.
The message that shows at the bottom of the form indicating that the connection was successful.
If you receive an error, check the Troubleshooting section for information on correcting common configuration issues.
The following view will show you the progress of your data being imported.
The Database import view during the initial import process.
Once your database has finished importing, the view will update to show the database that was created in PlanetScale, as well as the option to enable primary mode. This button will make the PlanetScale version of the database the primary replica. Clicking “Enable primary mode” will display a modal where you can confirm that you want to make this change.
The Database import view once the initial import has been completed.
After primary mode is enabled, the third card in the flow will update to give you two options:
- Enable replica mode — Reverts the change performed in the previous step, making RDS your primary once again.
- Finish import — Detaches the databases from replication. Future changes to either the PlanetScale database or the RDS database will not be replicated to each other.
Click “Finish import” to complete the import process. Confirm in the modal that will be displayed.
The Database import view after the PlanetScale database has been flagged as the primary database.
This concludes the process used to import a database into PlanetScale from AWS RDS.
This will create an account that has full access to the database that you can use for the migration.
Configure gtid and binlog settings
One of the gtid errors that display in the PlanetScale Import database form when the connection is not successful.
Navigate to your RDS instance and check the parameter group in the “Configuration” tab. If you are using the default, you’ll need to create a new parameter group to reconfigure the GTID settings.
The Configuration tab of the database view in RDS.
To create a parameter group, select “Parameter groups” from the left nav and then “Create parameter group”.
The Parameter groups view in RDS.
Specify the Parameter group family, Type, Group name, and Description. All fields are required.
The form used to create a parameter group.
When you save, you’ll be brought back to the list of available parameter groups. Select your new parameter group from the list to modify the settings.
The list of parameter groups in RDS.
Click “Edit parameters” to unlock editing.
The header of the view when editing a parameter group.
Search for “binlog_format” in the search box. Update that setting to match:
- binlog_format: ROW
The binlog_format configuration required.
Search for “gtid” in the search box, and update the following settings to match:
Click “Save changes” once you are done.
The gtid configurations that are required.
Now you need to associate the parameter group to the database. Select “Databases” from the left nav, check the select box next to your database, and click “Modify” from the toolbar.
The list of databases in RDS.
Scroll about halfway down the page and find the section titled Additional configuration. Update the DB parameter group to match the new group created earlier in this section. Scroll to the bottom and click “Continue”.
The Additional configuration section of the database configuration view.
You’ll be presented with options to apply the changes at the next maintenance window or immediately.
If you select Apply during the next scheduled maintenance window, the updated configuration group will be applied during that window.
If you select Apply immediately, the group will be applied immediately but you must manually reboot the database for the changes to take effect.
Once you’ve selected your desired option, click “Modify DB instance” to apply the changes.
The confirmation view that is displayed when modifying RDS database settings.
If you opted to apply the changes immediately, you can monitor the status on the “Configuration” tab of the database view. The page does not automatically update, so you’ll need to refresh the page to check the status when it updates.
The configuration tab with the new parameter group applying.
The configuration tab with the Pending reboot status.
To reboot the database, click the “Modify” button near the top of the screen, then “Reboot”.
This will disconnect any users who are actively using the database! Proceed with caution.
The database view & where the option to reboot the database is located.
You’ll be presented with a page to confirm the database you want to reboot. Click "Confirm” and the database will begin rebooting.
The confirmation dialog to reboot the database.
You can view the status of the database in the primary list of databases for this account/region. This view does not refresh automatically, click the “Refresh” button to update the view.
A view of the databases in RDS with status & the refresh button highlighted.