Skip to main content

​
Overview

This document will demonstrate how to migrate a database from AWS Relational Database Services (RDS) to PlanetScale.
This guide assumes you are using MySQL on Amazon RDS. If you are using Amazon Aurora (MySQL compatible) on RDS, follow the Amazon Aurora migration guide. Other database systems (non-MySQL or MariaDB databases) available through RDS will not work with the PlanetScale import tool.
We recommend reading through the Database import documentation to learn how our import tool works before proceeding.

​
Prerequisites

Gather the following information from the AWS Console:
  • Database endpoint address - Located in “Connectivity & security” tab of your database instance
  • Port number - Typically 3306
  • Master username and password - Your RDS root credentials
The Connectivity & security tab of the database in RDS.

​
Step 1: Configure server settings

Your RDS database needs specific server settings configured before you can import. Follow these steps to configure GTID mode, binlog format, and sql_mode.

​
Check your current parameter group

Your Amazon RDS database is either using the default DB parameter group (e.g., default.mysql8.0) or a custom one. You can view it in the “Configuration” tab of your database instance.
The Configuration tab of the database view in RDS.

​
Configure the parameter group

1
If you are using the default DB parameter group, you’ll need to create a new parameter group to reconfigure settings.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.
  • Parameter group family: mysql8.0 (or your MySQL version)
  • Type: DB Parameter Group (Note: Not “DB Cluster Parameter Group” type)
  • Group name: psmigrationgroup (or your choice)
  • Description: Parameter group for PlanetScale migration
The form used to create a parameter group.
You’ll be brought back to the list of available parameter groups when you save.
2
Edit the settings in your custom DB parameter group. Select your parameter group from the list.
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” and update:
  • binlog_format: ROW
The binlog_format configuration required.
Search for “gtid” and update:
  • gtid-mode: ON
  • enforce_gtid_consistency: ON
Search for “sql_mode” and update:
  • sql_mode: NO_ZERO_IN_DATE,NO_ZERO_DATE,ONLY_FULL_GROUP_BY
The GTID configurations that are required.
Click “Save changes”.
3
Associate the parameter group to your database. Select “Databases” from the left nav, check the select box next to your database instance, and click “Modify”.
The list of databases in RDS.
Scroll to Additional configuration section. Update the DB parameter group to your new parameter group. Click “Continue”.
The Additional configuration section of the database configuration view.
Choose when to apply:
  • Apply during the next scheduled maintenance window - Applied during maintenance window
  • Apply immediately - Applied now, but requires manual reboot
The confirmation view that is displayed when modifying RDS database settings.
Click “Modify DB instance”.
4
Reboot your database instance to apply the settings. Click “Actions” > “Reboot”.
This will briefly disconnect active users! The parameter group changes won’t take effect without a reboot.
You’ll be presented with a page to confirm the database you want to reboot. Click “Confirm” and the database will begin rebooting.If you opted to apply changes immediately, monitor the status on the “Configuration” tab. The page does not automatically update, so refresh to check status.
The configuration tab with the new parameter group applying.

​
Step 2: Enable binary logging

Binary logging must be enabled for the import to work. On RDS, binary logging is tied to automated backups. To enable binary logging, enable automated backups by setting the backup retention period to any value greater than zero days. Verify binary logging is enabled: 
mysql> show variables like 'log_bin';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| log_bin       | ON    |
+---------------+-------+

​
Step 3: Configure binlog retention

Set the binary log retention period to ensure logs aren’t purged during the import. For most cases, 48 hours is sufficient, but larger imports may need more time.
Longer retention periods use more disk space. Evaluate your binlog size to avoid running out of disk space. Contact PlanetScale Support if you need assistance.
Set the retention period using the mysql.rds_set_configuration() procedure: 
CALL mysql.rds_set_configuration('binlog retention hours', 48);
Verify the setting: 
CALL mysql.rds_show_configuration;
Expected output: 
+------------------------+-------+-----------------------------------------------------------------------------------------------------------+
| name                   | value | description                                                                                               |
+------------------------+-------+-----------------------------------------------------------------------------------------------------------+
| binlog retention hours | 48    | binlog retention hours specifies the duration in hours before binary logs are automatically deleted.      |
+------------------------+-------+-----------------------------------------------------------------------------------------------------------+

​
Step 4: Ensure database is publicly accessible

PlanetScale needs to connect to your RDS database over the internet. Check that your database is publicly accessible. In your database instance, go to “Connectivity & security” tab. Under “Security”, check if Publicly accessible is set to “Yes”. If it says “No”, you’ll need to modify the database settings to enable public access. If you cannot make the database publicly accessible, contact us to discuss alternative import options.

​
Step 5: Create a migration user

Create a dedicated user with limited privileges for the import process. Connect to your RDS database using the MySQL command line with your master credentials: 
mysql -u admin -p -h [your-rds-endpoint]
Run the following script, replacing the placeholders:
  • <SUPER_STRONG_PASSWORD> - Password for the migration_user account
  • <DATABASE_NAME> - Name of the database you’re importing
CREATE USER 'migration_user'@'%' IDENTIFIED BY '<SUPER_STRONG_PASSWORD>';
GRANT PROCESS, REPLICATION SLAVE, REPLICATION CLIENT, RELOAD ON *.* TO 'migration_user'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, SHOW VIEW, LOCK TABLES ON `<DATABASE_NAME>`.* TO 'migration_user'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER ON `ps\_import\_%`.* TO 'migration_user'@'%';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER ON `_vt`.* TO 'migration_user'@'%';
GRANT EXECUTE ON PROCEDURE mysql.rds_show_configuration TO 'migration_user'@'%';
GRANT SELECT ON mysql.db TO 'migration_user'@'%';
GRANT SELECT ON mysql.func TO 'migration_user'@'%';
GRANT SELECT ON mysql.tables_priv TO 'migration_user'@'%';
GRANT SELECT ON mysql.user TO 'migration_user'@'%';
GRANT SELECT ON performance_schema.* TO 'migration_user'@'%';
FLUSH PRIVILEGES;
Save the username and password securely - you’ll need them for the import.

​
Step 6: Configure RDS security group

Allow PlanetScale to connect by adding PlanetScale’s IP addresses to your security group. The specific IP addresses depend on your PlanetScale database region. These will be shown during the import workflow on the Connect to external database step. See the Import public IP addresses page for more details.

​
Add IP addresses to security group

Navigate to “Connectivity & security” tab of your database instance and click the VPC security group link.
The Connectivity & security tab of the database view in RDS.
Select “Inbound rules” tab, then “Edit inbound rules”.
The view of security groups associated with the RDS instance.
Click “Add rule”, then:
  • Type: Select MYSQL/Aurora
  • Source: Enter the first PlanetScale IP address (AWS will format it as x.x.x.x/32)
Repeat for each IP address in your region, then click “Save rules”.
The Edit inbound rules view where source traffic can be allowed.

​
Importing your database

Now that your RDS database is configured, follow the Database Imports guide to complete your import. When filling out the connection form in the import workflow, use:
  • Host name - Your RDS endpoint address (from Prerequisites)
  • Port - 3306 (or your custom port)
  • Database name - The exact database name to import
  • Username - migration_user
  • Password - The password you set in Step 5
  • SSL verification mode - Select based on your RDS SSL configuration
The Database Imports guide will walk you through:
  • Creating your PlanetScale database
  • Connecting to your RDS database
  • Validating your configuration
  • Selecting tables to import
  • Monitoring the import progress
  • Switching traffic and completing the import

​
Need help?

Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.