Postgres Imports

July 18, 2025

For customers looking to migrate their Postgres databases to PlanetScale for Postgres, you have several options for how to make this the smoothest event for your business.

Use this guide if you are importing from platforms like Aurora Postgres, RDS Postgres, Neon, Supabase, and other Postgres instances.

Migration Options Overview

PlanetScale for Postgres provides three primary migration approaches to suit different business requirements, database sizes, and downtime tolerances:

• Migrate using pgdump/restore
• Migrate using WAL replication
• Migrate using Amazon DMS

You can also utilize our migration scripts directly if you prefer. These scripts can be used to migrate straight from any Postgres source that supports logical replication into PlanetScale for Postgres.

1. pg_dump and Restore

The pg_dump method is the simplest approach for migrating smaller PostgreSQL databases. This method involves creating a full backup of your source database using PostgreSQL's built-in pg_dump utility and then restoring it to your PlanetScale for Postgres database.

How it works:

• Export your entire database schema and data using pg_dump
• Transfer the dump file to PlanetScale for Postgres
• Restore the database using pg_restore or psql

This approach is straightforward and doesn't require additional infrastructure, making it ideal for databases that can tolerate some downtime during the migration process.

2. WAL Log Replication

Write-Ahead Logging (WAL) replication provides a near-zero downtime migration by continuously streaming transaction logs from your source PostgreSQL database to PlanetScale for Postgres.

How it works:

• Set up logical replication between your source database and PlanetScale for Postgres
• Stream WAL logs in real-time to keep the target database synchronized
• Perform a quick cutover when ready to switch to the new database

This method is ideal for production databases that require minimal downtime and need to maintain data consistency during the migration process.

3. Amazon Database Migration Service (DMS)

Amazon Database Migration Service (DMS) provides a managed migration service that can handle complex database migrations with built-in monitoring, error handling, and data validation.

How it works:

• Configure DMS replication instance and endpoints for source and target databases
• Set up full load and change data capture (CDC) for ongoing replication
• Monitor the migration process through the AWS console
• Perform cutover when the target database is fully synchronized

DMS is particularly useful for large, complex databases that require robust error handling, data transformation, and detailed migration monitoring.

Migration Method Comparison

Migration Considerations

Before migrating your PostgreSQL database to PlanetScale for Postgres, there are several important factors to consider to ensure a smooth migration process.

PostgreSQL Version Compatibility

PlanetScale for Postgres supports PostgreSQL version 17 at launch. If your source database is running an older version of PostgreSQL, you should verify compatibility and consider upgrading your source database before migration, or plan for potential compatibility issues during the migration process.

Version considerations:

• PostgreSQL 17: Fully supported
• Earlier versions: May require additional testing and validation
• Version-specific features: Newer features may not be available in older versions

For detailed information about PostgreSQL version differences, refer to the PostgreSQL version documentation.

Extension Support

PlanetScale for Postgres will have limited extension support at launch. Many PostgreSQL databases rely on extensions to provide additional functionality, and not all extensions will be available initially.

Important notes about extensions:

• Review your current database's installed extensions using \dx in psql or by querying pg_extension
• Identify which extensions are critical to your application's functionality
• Plan for alternative approaches if critical extensions are not supported
• Test your application thoroughly in a staging environment before migrating production data

Common extensions that may require attention:

• PostGIS for geospatial data
• pg_stat_statements for query statistics
• UUID extensions
• Full-text search extensions

Third-Party Enhancements and Tools

PlanetScale for Postgres does not support third-party enhancements to PostgreSQL's core capabilities at launch. This includes:

Currently unsupported:

• Custom background workers
• Third-party connection poolers (like PgBouncer)
• External procedural languages beyond the standard ones
• Third-party monitoring tools that require database-level access
• Custom shared libraries or plugins

Note: PlanetScale for Postgres includes connection pooling by default.

Alternatives to consider:

• Migrate custom functions to standard PostgreSQL syntax where possible
• Utilize Metrics, Insights, and 3rd party integrations for monitoring (LINKS HERE)

Pre-Migration Checklist

Before starting your migration:

1. Database Assessment

   • Document your current PostgreSQL version
   • List all installed extensions and their usage
   • Identify any third-party tools or enhancements in use
   • Review custom functions and stored procedures

2. Compatibility Testing

   • Test your application against PostgreSQL 17 if not already using it
   • Validate that critical extensions are supported or have alternatives
   • Identify any custom code that may need modification

3. Migration Planning

   • Choose the appropriate migration method based on your requirements
   • Plan for testing in a staging environment
   • Prepare rollback procedures if needed
   • Schedule migration during low-traffic periods if possible

For the most up-to-date information on supported features and extensions, refer to the PostgreSQL documentation and PlanetScale for Postgres release notes.

You got this!

Follow the migration guide that's right for you:

• Migrate using pgdump/restore
• Migrate using WAL replication
• Migrate using Amazon DMS

If you encounter issues while importing from a Postgres database, please reach out to support for assistance.

Need help?

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