Postgres Imports - Amazon DMS with CloudFormation
This method uses Infrastructure as Code with Step Functions workflow automation for a completely managed migration experience. Amazon Database Migration Service (DMS) provides a fully automated approach to migrate your PostgreSQL database to PlanetScale for Postgres.
Overview
This automated migration method:
- Deploys DMS infrastructure via CloudFormation template
- Configures source and target database endpoints automatically
- Creates Step Functions workflow for automated migration orchestration
- Provides built-in monitoring, notifications, and automated cleanup
- Requires minimal manual intervention - mostly console clicks
Note
This method requires an AWS account and will incur AWS DMS charges. The CloudFormation template includes cost optimization features. Review AWS DMS pricing before proceeding.
General Prerequisites
Before starting the migration:
- Have an active AWS user with CloudFormation, EC2, DMS, SNS, and Step Functions permissions
- Source PostgreSQL database accessible from AWS VPC
- Connection details for your PlanetScale for Postgres database from the console
- VPC with at least 2 subnets in different Availability Zones
Source database prerequisites
The Task that AWS DMS runs will automatically perform these 7 validation checks before starting the migration. Confirm before starting this process that they will succeed.
Check Name | What It Validates | Required Action (if needed) |
---|---|---|
Database Version Compatibility | Verifies your PostgreSQL version is supported by AWS DMS | Ensure you're running a supported PostgreSQL version (9.4+) |
Target Database Privileges | Confirms PlanetScale user has sufficient permissions | No action should be needed - PlanetScale credentials include required permissions |
Replication Slots Available | Checks that replication slots are available for CDC | Verify max_replication_slots >= 1 in Aurora parameter group |
Source Database Read Privileges | Validates source user can read all tables for migration | Ensure source user has SELECT privileges on all tables to migrate |
WAL Level Configuration | Confirms WAL level is set to 'logical' for CDC replication | Set wal_level = logical in Aurora parameter group (requires restart) |
WAL Sender Timeout | Ensures WAL sender timeout is at least 10 seconds | Set wal_sender_timeout >= 10000 (10 seconds) in parameter group |
Maximum WAL Senders | Verifies enough WAL sender processes for CDC | Set max_wal_senders >= 2 in Aurora parameter group |
Step 1: Check DMS IAM Roles
Before deploying, check if DMS service roles already exist in your AWS account:
- Go to IAM Console
- Click "Roles" in the left sidebar
- Search for these role names:
dms-vpc-role
dms-cloudwatch-logs-role
- If neither role exists: Set
CreateDMSRoles
parameter totrue
in Step 3 - If both roles exist: Set
CreateDMSRoles
parameter tofalse
in Step 3 - If one role exists but not the other: Consider manually creating the roles per guidance in the AWS DMS documentation and set
CreateDMSRoles
parameter tofalse
in Step 3
Step 2: Download CloudFormation Template
Get the CloudFormation template:
- Visit: https://github.com/planetscale/migration-scripts/tree/main/postgres-planetscale
- Right-click on
aurora-to-ps-dms.yaml
→ "Save link as" - Save the file to your computer
Step 3: Deploy CloudFormation Stack
- Navigate to AWS CloudFormation Console
- Click "Create stack" → "With new resources (standard)"
- Select "Upload a template file"
- Click "Choose file" and select the downloaded template
- Click "Next"
Configure Stack Parameters
Stack name: postgres2planetscale
or any name you want but note that overly-long names can cause resource creation issues
VPC Information
- VPC ID: Select your VPC from dropdown
- Subnet IDs: Select 2+ subnets in different AZs which are "public" subnets in that they have route tables through an Internet Gateway (IGW) and NACLs that allow outbound routing. See Subnet types in the AWS documentation for more information
Source Database (Your Aurora Postgres database)
- Source Endpoint Host: Your Aurora hostname (primary write endpoint is best, not a proxy)
- Source Port:
5432
(or your custom port) - Source Database Name: Your database name
- Source Username: Your database username
- Source Password: Your database password
Target Database (PlanetScale for Postgres)
From your PlanetScale console connection details:
- Target Endpoint Host: PlanetScale host
- Target Port:
5432
- Target Database Name: PlanetScale database name
- Target Username: PlanetScale username
- Target Password: PlanetScale password
Additional Features
- DMS Instance Class:
dms.c6i.large
(recommended) - Migration Type:
full-load-and-cdc
(recommended) - Enable Automation:
true
⭐ Important: This creates the Step Functions workflow - Create DMS Roles:
true
orfalse
(based on Step 1 findings) - Notification Email: Your email for status updates
- Click "Next" → "Next" → Check "I acknowledge that AWS CloudFormation might create IAM resources"
- Click "Submit"
Step 4: Wait for Stack Completion
- Stay on the CloudFormation console
- Click on your stack name to view details
- Watch the "Events" tab for progress
- Wait for stack status to show
CREATE_COMPLETE
(typically 5-10 minutes)
Step 5: Confirm your email notification subscription
- Check the inbox for the email used above
- You will get an email from
no-reply@sns.amazonaws.com
"DMS Migration Workflow Notifications" - Click the link for Confirm Subscription
Note that after the migration task completes and the stack is deleted, you would receive no further communications from this AWS SNS Topic, but other SNS topics may use the same address.
Step 6: Get Workflow Input Configuration
- In your completed CloudFormation stack, click the "Outputs" tab
- Find the output key
StepFunctionsPayloadTemplate
- Copy the entire JSON value (this contains the configuration for your migration) The JSON should look like the following example:
{ "replicationInstanceArn": "arn:aws:dms:us-east-2:1234567890:rep:YMZ2AH4YAJCRNJKOWBR7EEIRGE", "sourceEndpointArn": "arn:aws:dms:us-east-2:1234567890:endpoint:SIVNPTNFJZDCVK4ODTN6ZLONN4", "targetEndpointArn": "arn:aws:dms:us-east-2:1234567890:endpoint:MLSCVENBKVBWJKRVJ27EWB32IU", "replicationTaskArn": "arn:aws:dms:us-east-2:1234567890:task:QZCBNW565VH2JG2KE5UXX42LS4", "sourceEndpointHost": "prod-aurora-cluster.cluster-abc1234567.us-east-2.rds.amazonaws.com", "sourcePort": "5432" }
Step 7: Locate Step Functions Workflow
- While still in the "Outputs" tab find the key
StepFunctionsConsoleURL
- Click on the URL link to open the AWS Step Functions console for the workflow created here
The workflow includes these automated steps:
- Network Connectivity Check: Tests connections to both source and target databases
- Security Group Auto-Fix: Automatically corrects Aurora security group settings if DMS connectivity fails
- Pre-Migration Validation: Validates database schemas, table structures, and data types
- Migration Task Start: Launches the DMS full-load and CDC replication
- Progress Monitoring: Continuously monitors migration progress and handles errors
Step 8: Start Migration Workflow
- In the Step Functions state machine, click "Start execution"
- Execution name: Leave as auto-generated
- Input: Paste the JSON you copied from CloudFormation outputs
- Click "Start execution"
The workflow will automatically:
- Test database connections
- Start the DMS migration task
- Monitor progress
- Send notifications
- Handle errors and retries
Step 9: Monitor Migration Progress
There are several tools you can use to monitor the progress and if necessary troubleshoot potential failures.
DMS Console
- Go to DMS Console
- Click "Tasks"
- Select the task Identifier for this migration
- View your task for detailed table-level progress
Step Functions Console
- Watch the visual workflow progress in the Step Functions console
- Each step will show green (success), red (failure), or blue (in progress)
- Click on individual steps to see detailed logs
CloudWatch Dashboard
- Navigate to CloudWatch Console
- Click "Dashboards" → "Automatic Dashboards" → "DMS-Migration-Dashboard"
- Monitor key metrics:
- Full load progress percentage
- CDC latency
- Error counts
- Throughput
Wait for automated emails
You will receive an email once the migration has reached a 100% full load and CDC replication is ongoing.
If the workflow does fail at any point, you will instead receive an email with where the failure occurred and then you can review the previously mentioned tools for more information.
Step 10: Application Cutover
When the Step Functions workflow or DMS task itself indicates migration is ready (Status is "Load completed, replication ongoing"), then you can begin your cutover process.
Pre-Cutover Checklist (Automated)
AWS DMS ensures:
- ✅ Full load is 100% complete
- ✅ CDC latency is under 5 seconds
- ✅ Data validation passes
- ✅ Both databases are synchronized
Cutover Process
- Put application in maintenance mode, pause all writes from your application to the old database
- Wait for DMS to confirm final sync
- Update your application's database connection strings to use PlanetScale details
- Restart or redeploy your application
- Test critical functionality
Automated Cleanup (mostly)
Go to your CloudFormation stack
Click "Delete"
Click the "Delete" confirmation popup
Note
The first time you attempt to delete the stack, the full process will fail to delete some of the resources. Minimally the S3 bucket created to store the DMS pre-migration test reports will need to be manually emptied before it can be deleted. If the Step Functions workflow had to modify Aurora security group, then the rule added needs to be deleted as well. Both of these resources could be safely left behind, however the S3 bucket's data will incur ongoing charges.
In the CloudFormation stack "Resources" tab, find the resources where deletion failed
Find the Resource named PreMigrationAssessmentBucket
Click to open the link under the Physical ID heading for this resource
This will take you to the Amazon S3 console for this bucket. The assessment-folder is a versioned object in S3, which means that directly deleting it here does not actually remove it, but instead places a deleted marker on the version.
To fully empty the bucket you will need to navigate to the main console page. Click "Buckets" from the top nav, or "General purpose buckets" from the left nav
Select the bucket used, it will start with the name of the CloudFormation stack
Click "Empty"
Follow the prompt to permanently delete the pre-migration reports
You can now re-attempt the stack deletion from the 1st step here
Troubleshooting
Stack Creation Issues
Permission Errors:
- Ensure your AWS user has CloudFormation, DMS, Step Functions, and IAM permissions
- Check that you acknowledged IAM resource creation during stack creation
Network Issues:
- Verify your VPC allows internet access for DMS to reach PlanetScale
- Check security groups allow port 5432 access
- Ensure subnets are in different Availability Zones
Step Functions Workflow Issues
Workflow Creation Fails:
- Verify you copied the complete JSON from CloudFormation outputs
- Check that the Step Functions execution role exists
Migration Task Fails:
- Check Step Functions execution details for specific error messages
- Verify database connection details are correct
- Ensure source database has logical replication enabled
Connection Problems
Source Database:
- Verify hostname, port, username, and password
- Check that source database allows connections from DMS subnet
- Ensure database has logical replication enabled (
rds.logical_replication = 1
for RDS)
Target Database (PlanetScale):
- Double-check connection details from PlanetScale console
- Verify PlanetScale database is active and accessible
- Test connectivity from AWS region to PlanetScale
Step Functions Workflow Benefits
Using the automated Step Functions workflow provides:
- Visual Progress Tracking: See each migration phase in real-time
- Automatic Error Handling: Built-in retry logic and error notifications
- Audit Trail: Complete log of migration steps and timings
Advanced Options
Custom Migration Settings
Modify template parameters for:
- Different DMS instance sizes
- Custom migration types (full-load only, CDC only)
- Extended monitoring periods
- Custom notification settings
Multiple Database Migration
Deploy multiple stacks with different names to migrate multiple databases in parallel.
Migration Considerations
Before migration, review:
Support and Resources
- Template Issues: GitHub repository
- AWS Documentation: CloudFormation and Step Functions
- PlanetScale Support: Contact support for migration assistance
For simpler migrations, consider pg_dump/restore, or WAL streaming methods.
Need help?
Get help from the PlanetScale Support team, or join our GitHub discussion board to see how others are using PlanetScale.