PlanetScale Database Migration - How to Not Screw This Up

Check if your binlogs are enabled first or you'll waste half a day wondering why nothing works. Took me maybe 3 hours to figure this out because I'm an idiot and didn't read the prereqs.

SHOW VARIABLES WHERE Variable_name IN ('log_bin', 'gtid_mode', 'binlog_format');

If log_bin returns OFF, you can't use PlanetScale's Import Tool. You're stuck with manual migration and downtime. If gtid_mode is OFF, same problem. And if binlog_format isn't ROW, fix it or you'll get weird replication bugs that make no sense.

Here's What Nobody Tells You About PlanetScale Migration

Your foreign keys are completely fucked. All of them. PlanetScale doesn't support foreign key constraints because Vitess can't handle them across shards. Found this out when constraint violations started flooding our error logs after the first test migration.

Your stored procedures are also dead. Triggers too. If you have business logic in the database, start extracting it now because PlanetScale won't run any of it.

Option 1: Import Tool (Works Great Until It Doesn't)

The PlanetScale Import Tool is your best bet if your binlogs work. It's "zero downtime" but there's still connection drops during cutover. I've done this maybe 6 times now - budget 30 seconds of connection drops, not zero. Their marketing oversells the "zero downtime" part.

How it actually works:

• Copies your data while serving traffic (this part actually works if your binlog retention holds up)
• Keeps syncing changes via binlog replication (can lag if you have heavy writes)
• Switches traffic over in one scary moment (you'll hold your breath)
• Keeps your old database synced for rollback (which you'll probably need)

Real requirements nobody mentions:

• Binary logging enabled (log_bin = ON) - check with that query above
• GTID mode enabled (gtid_mode = ON) - pain in the ass to enable on existing replicas
• Row-based binlog format (binlog_format = ROW) - statement-based won't work with Vitess
• Binlog retention of at least 3 days (expire_logs_days >= 3) - learned this when migration failed due to log gap
• Database user with specific permissions (they don't tell you SUPER privilege is needed)

When it'll break:

• Your binlog retention is too short and gap appears during migration
• Network hiccups between your database and PlanetScale's ingest - their status page won't help you here
• Your database has weird MySQL features that confuse Vitess (like spatial indexes)
• You're using MyISAM tables (convert to InnoDB first or it won't work at all)

Option 2: pscale CLI (For Control Freaks)

The pscale CLI is decent when the web interface isn't cutting it. You can script it, which means you can also break it in creative ways.

Why you'd use this:

• The Import Tool doesn't work for your edge case
• You need to migrate multiple databases and want to script it
• You're testing migrations and need to iterate quickly
• You want detailed logs when everything goes wrong

Reality check:

• pscale database dump is just mysqldump under the hood with some flags
• Progress reporting is optimistic at best
• Network interruptions will make you restart from scratch
• The restore process is slower than you think

Actual CLI workflow:

## Install CLI and authenticate (this part never works smoothly)
brew install planetscale/tap/pscale
pscale auth login

## Create target database (pick your region wisely)
pscale database create prod-migration --region us-east

## Dump your source (this will take forever)
pscale database dump source-db main > migration.sql
## Pro tip: pipe through gzip or you'll run out of disk space

## Restore to PlanetScale (pray nothing times out)
pscale database restore-dump prod-migration main migration.sql

## Check if it actually worked
pscale shell prod-migration main

Where this goes wrong:

• Authentication expires mid-migration
• Dump fails with Error 2013: Lost connection for large databases
• Restore times out after 2 hours (yes, there's a timeout)
• You realize you picked the wrong region and have to start over

Option 3: Manual Migration (Accept Your Downtime Fate)

Sometimes you just need to mysqldump everything and deal with the downtime. Usually because your binlogs aren't configured or your database is small enough that you don't care.

When you're stuck with this:

• Your database is under 10GB and downtime is acceptable
• Your MySQL is old and doesn't have GTID support
• You tried the Import Tool and it broke in a weird way
• It's 3 AM and you just want to get this done

Real timelines (not marketing bullshit):

• Export: maybe 10-20 minutes per GB, could be way longer if you have lots of indexes
• Transfer: However long it takes to upload a huge file (your internet sucks more than you think)
• Import: 15-30 minutes per GB on PlanetScale, sometimes longer for no obvious reason
• Testing: at least 2 hours if you're being responsible, probably more like 4-6 hours

The reality of manual migration:

## This will take longer than you think
mysqldump --single-transaction --routines --triggers \\
    --opt --verbose --lock-tables=false \\
    production_db > migration.sql

## Upload to PlanetScale however you can
## (Their web interface has a file size limit)

## Import and cross your fingers
mysql -h your-planetscale-host.psdb.cloud \\
    -u username -p new_database < migration.sql

What'll definitely go wrong:

• Export hangs on a big table and you restart with --where=\"1 LIMIT 1000000\"
• Import fails halfway through because of some weird character encoding
• You forgot to drop foreign keys first and everything breaks
• The connection times out during import because PlanetScale has limits

Which Migration Method Will Screw You Over Least

What You Need to Check Before You Start

Run this query to see what you're dealing with:

-- Count your foreign keys (these all need to be handled in code)
SELECT COUNT(*) as foreign_key_count
FROM information_schema.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_NAME IS NOT NULL;

-- Find your stored procedures (these need to be rewritten)
SELECT ROUTINE_TYPE, ROUTINE_NAME
FROM information_schema.ROUTINES
WHERE ROUTINE_SCHEMA = 'your_database';

-- Check for triggers (also need rewriting)
SELECT TRIGGER_NAME, EVENT_MANIPULATION, EVENT_OBJECT_TABLE
FROM information_schema.TRIGGERS
WHERE TRIGGER_SCHEMA = 'your_database';

-- Find FULLTEXT indexes (not supported, need external search)
SELECT TABLE_NAME, INDEX_NAME
FROM information_schema.STATISTICS
WHERE INDEX_TYPE = 'FULLTEXT' AND TABLE_SCHEMA = 'your_database';

If any of these return results, you have work to do before migration. Check what Vitess actually supports because it's not everything MySQL can do.

The Shit That Always Goes Wrong

Your connection string will change. Update your config management, environment variables, and any hardcoded connections. Test this in staging first.

Query performance will be different. Vitess adds routing overhead. Some queries get faster (especially with sharding), others get slower. Monitor everything for the first 48 hours.

Your monitoring will break. Database metrics work differently in PlanetScale. Set up their monitoring before you migrate, not after.

Someone will try to connect to the old database. Keep it running for at least a week after migration. Set up alerts when anything connects to it so you can hunt down the stragglers.

The migration will take longer than estimated. Whatever timeline you give your boss, multiply by 2. If it's mission-critical, multiply by 3. If it's end-of-quarter crunch time, just quit now and save yourself the pain.

Here's what the migration actually looks like when you're doing it, not when you're reading about it on the marketing page.

The Part Where You Realize How Fucked You Are

I ran that foreign key query and got back like 800 results or something crazy like that. Which explained why the test migration kept breaking in weird ways.

Run this query and prepare to hate your life:

-- How many foreign keys will ruin your weekend?
SELECT COUNT(*) FROM information_schema.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_NAME IS NOT NULL;

-- What business logic did some genius put in the database?
SELECT ROUTINE_TYPE, ROUTINE_NAME FROM information_schema.ROUTINES
WHERE ROUTINE_SCHEMA = 'your_database';

-- Triggers that will need complete rewrites
SELECT TRIGGER_NAME, EVENT_MANIPULATION FROM information_schema.TRIGGERS
WHERE TRIGGER_SCHEMA = 'your_database';

-- FULLTEXT indexes that just don't work in Vitess
SELECT TABLE_NAME, INDEX_NAME FROM information_schema.STATISTICS
WHERE INDEX_TYPE = 'FULLTEXT';

If those return anything substantial, multiply your timeline by 3. Some poor bastard before you decided to put application logic in the database, and now it's your problem.

The inventory reality check:

• Count your tables: If it's over 50, you're looking at a multi-week project
• Check your largest table: If it's over 100GB, the Import Tool will probably hang at some point
• Find who wrote stored procedures: They're probably not at the company anymore
• Document your triggers: You'll need to rewrite all of them in application code

Killing Your Foreign Keys (This Takes Forever)

Every foreign key constraint needs to die. All of them. This isn't negotiable.

Generate the death sentences:

SELECT CONCAT('ALTER TABLE ', TABLE_NAME, ' DROP FOREIGN KEY ', CONSTRAINT_NAME, ';')
FROM information_schema.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_NAME IS NOT NULL;

But here's the fun part: dropping them is easy. Rewriting your application to handle referential integrity is the nightmare. PlanetScale's guide makes it sound simple, but it's not.

What you'll actually need to do:

• Rewrite every ON DELETE CASCADE as application logic
• Add validation checks before every insert/update
• Handle race conditions your foreign keys were preventing (this is harder than it sounds)
• Test edge cases that never happened because the database stopped them

Real timeline: If you have more than 20 foreign keys, budget a month just for this. I spent like 6 weeks on one app because Eloquent ORM was doing magical things with relationships that I didn't understand.

Dealing With Stored Procedures (If You Have Them, You're Screwed)

Got stored procedures? You're basically rewriting part of your application. PlanetScale doesn't support them at all.

The questions that'll keep you up at night:

• Is this business logic or just convenience code?
• Does this procedure handle edge cases we forgot about?
• What happens if we move this to application code and it breaks under load?
• Why did someone put a 500-line procedure in the database?

Pro tip: Document everything before you delete it. You'll need to reference the original logic when your rewrite breaks in production.

Week 4-8: The Migration Attempts (Yes, Plural)

Attempt 1: The Import Tool
Will probably fail the first time. Common failures:

• Your binlogs aren't configured right (even though you checked)
• Network timeout during large table copy
• Your database has some weird MySQL feature that confuses Vitess
• The progress bar lies to you and stalls at 90%

Attempt 2: pscale CLI
Might work if you're lucky. Will definitely take longer than estimated:

• pscale dump fails halfway through your largest table
• Upload times are optimistic (multiply by 2)
• Import process times out after 2 hours
• Authentication expires mid-migration

Attempt 3: Manual Migration + Prayer
When all else fails:

• mysqldump with --single-transaction and cross your fingers
• Upload a 50GB file over sketchy hotel wifi
• Import takes all night and you discover an encoding issue at 3am
• Rollback because something broke and you can't figure out what

The Day Of: Migration Execution

T-minus 1 hour: Everything that can break will break

• Backup verification fails because of disk space
• Your connection string changes broke something you didn't test
• The team member with production access is on vacation
• PlanetScale's dashboard is slower than usual

T-0: Start the migration

• Initial data copy starts (this is the only part that actually works as advertised)
• You realize you forgot to handle that one edge case
• The progress indicators are completely useless
• Your database is 50% bigger than you thought

T+30 minutes to 48 hours later: Still copying data

• The Import Tool says "5 minutes remaining" for 3 hours (lying bastard)
• Your largest table hasn't even started yet
• Network blip causes a restart from checkpoint (hopefully, sometimes it just dies)
• You're googling "PlanetScale migration stuck" at 2am while questioning your career choices

The cutover moment: 30 seconds of terror

• Brief connection drops (not zero downtime, just low downtime)
• You hold your breath while applications reconnect
• First query after cutover takes forever because of cold caches
• Error spike in your monitoring that may or may not be related

Week 1-2 After: Fixing What Broke

Things that definitely broke:

• Query performance is different (usually slower initially)
• Connection pooling behaves differently
• Some edge case in your foreign key logic that you missed
• Monitoring dashboards show weird spikes
• That one integration that nobody remembered uses the database

Things you'll discover:

• Your application was relying on MySQL-specific behaviors
• JOIN queries work differently across shards
• AUTO_INCREMENT values jumped and confused your application
• Connection string changes broke more things than you tested

The Actual Timeline (Not Marketing Bullshit)

Small database (< 10GB):

• Planning: 2-4 weeks if you're thorough
• Foreign key rewrite: 1-2 weeks, maybe longer
• Migration: anywhere from 1 day to 1 week depending on failures
• Fixing stuff: 1-2 weeks minimum

Medium database (10GB - 1TB):

• Planning: 1-2 months, lots of complexity
• Application rewrites: 1-2 months, could be way longer
• Migration attempts: 1-2 weeks of multiple tries
• Stabilization: at least 1 month

Large database (> 1TB):

• You're looking at 6+ months total, maybe a year
• Call PlanetScale support, don't wing it
• Plan for multiple migration weekends
• Have a solid rollback plan

The Truth About Success

You'll know it worked when:

• Your application stops throwing weird errors
• Performance stabilizes (may be better or worse)
• You're not getting paged at 3am
• The business stops asking when you're "done" fixing the migration

You'll know you fucked up when:

• Data inconsistencies start appearing
• Performance is noticeably worse after a week
• You're spending more time debugging than before
• The team starts talking about rolling back

Most migrations work eventually. The question is how much pain you'll endure getting there.

Here's what really happens when you migrate to PlanetScale, based on people who've done it and lived to tell about it. Spoiler: it's messier than the marketing materials suggest.

Reality Check: Why FeatureOS Escaped PlanetScale

FeatureOS documented their migration AWAY from PlanetScale in early 2025. They'd been using PlanetScale since 2021 but got fed up with vendor lock-in bullshit and pricing games.

Why they bailed:

• PlanetScale discontinued their Scalar plan (pricing rug-pull)
• 100,000 row query limit made data export hell
• No binary log access = zero-downtime migration impossible
• Password restrictions broke standard migration tools
• CPU was expensive compared to self-hosting MySQL

The migration nightmare they endured:

Attempt 1: Airbyte (Official PlanetScale recommendation)
Failed spectacularly with ResourceExhausted and timeout errors. PlanetScale support basically said "use this tool" then disappeared when it didn't work.

Attempt 2: pscale dump
Worked great until they realized dump sizes varied every time. Running in debug mode showed silent errors that were being ignored. Classic.

Attempt 3: mydumper (What actually worked)
Had to reverse-engineer how pscale dump worked, discovered it used mydumper under the hood:

## What finally worked to escape PlanetScale
mydumper --user="$SOURCE_DB_USER" \
         --password="$SOURCE_DB_PASSWORD" \
         --host="$SOURCE_DB_HOST" \
         --port="$SOURCE_DB_PORT" \
         --database="$SOURCE_DB_NAME" \
         --outputdir="$DUMP_DIR" \
         --ssl \
         --ssl-mode=REQUIRED \
         --rows=5000 \
         --clear \
         --trx-tables \
         --verbose 3

The plot twist: They used this opportunity to escape MySQL entirely and move to PostgreSQL. Export to bridge MySQL instance, then pgloader to PostgreSQL.

Migration downtime: About 10 minutes, way less than the hour they'd planned for (sometimes you get lucky)

Results after escaping:

• Everything got faster and cheaper. Like, noticeably faster - page loads that took 2 seconds now take like 300ms
• Cut their hosting costs in half, no more row-based billing nightmare
• Better backups, hourly vs PlanetScale's twice daily bullshit
• No more vendor lock-in anxiety keeping them up at night

The lesson: Sometimes the best PlanetScale migration strategy is migrating away from PlanetScale entirely.

The Performance Shit Nobody Warns You About

Your app will be slower after migration. Not permanently, but definitely initially, and maybe permanently if you don't fix things.

Connection pooling weirdness:

• VTTablet handles thousands of connections, which sounds great until you realize your app's connection pool is configured wrong for a distributed setup
• You'll spend a week tweaking pool sizes because what worked for single MySQL doesn't work for Vitess
• Query routing adds maybe 10-20% latency that never goes away
• Your indexes matter way more now - queries that were "fast enough" become noticeably slow

Query optimization becomes mandatory:

• SELECT * queries that were fine before now suck because data travels across shards
• JOINs across shards are painful - prepare to denormalize some tables
• Batch operations help, but batch sizes that worked before might be too big now
• Query Insights becomes your best friend for finding bottlenecks

The Common Ways This Goes Wrong

The Foreign Key Massacre

Your foreign keys are dead. All of them. Period.

Apps that depend on database referential integrity are fucked. Teams typically spend 2-4 weeks rewriting this logic, but I've seen it take 2+ months when the foreign key relationships were complex and undocumented.

First, figure out what you're dealing with:

-- See how screwed you are
SELECT
    TABLE_NAME,
    COLUMN_NAME,
    CONSTRAINT_NAME,
    REFERENCED_TABLE_NAME,
    REFERENCED_COLUMN_NAME
FROM information_schema.KEY_COLUMN_USAGE
WHERE REFERENCED_TABLE_NAME IS NOT NULL;

Then rewrite it all in application code:

## This is now your job, not the database's
def validate_order_customer(customer_id, order_data):
    if not Customer.exists(customer_id):
        raise ValidationError("Invalid customer ID")
    return create_order(customer_id, order_data)

Pro tip: Test this shit thoroughly. Orders with invalid customer IDs will slip through if you miss an edge case.

Stored Procedure Hell

Got stored procedures? You're basically rewriting part of your application.

Reality check: Teams report 1-6 months of development time. If your procedures are complex, budget closer to 6 months. And pray the original dev documented them properly (they didn't).

What you're actually going to do:

• Document every procedure (the original dev probably left 2 years ago and took their knowledge with them)
• Pray the business logic is documented somewhere (it's not)
• Rewrite everything in application code while crying softly
• Discover edge cases the procedures handled that nobody remembered (or documented)
• Break something in production because you missed a detail and get paged at 3am

Learning PlanetScale's Special Snowflake Workflow

No more ALTER TABLE in production. PlanetScale has their own branching workflow that you have to learn.

The adjustment period:

• Your devs will hate the deploy request workflow initially and probably forever
• CI/CD pipelines need complete rewrites, budget 2 weeks for this
• Emergency schema hotfixes become a bureaucratic nightmare, good luck with that urgent production fix
• Someone will try to run DDL directly and nothing will happen and they'll blame you

The new workflow you're stuck with:

## This is your life now
pscale branch create my-app feature-branch
pscale deploy-request create my-app feature-branch
## Wait for review and approval (hope it's not urgent)
pscale deploy-request deploy my-app 123 --wait

It's actually better than traditional migration hell once your team adjusts, but the learning curve sucks.

If You're Big Enough to Have "Enterprise" Problems

Don't migrate everything at once unless you enjoy career-limiting incidents.

Phase 1: The Practice Round

• Internal tools nobody cares about
• Dev/staging environments (where breaking things is acceptable)
• Analytics databases (if they break, analysts complain, not customers)
• Learn how PlanetScale actually works without customer impact

Phase 2: Customer-Adjacent Stuff

• Background jobs and processing systems
• Secondary services with fallbacks
• Things where you can route traffic away if needed
• Build confidence before touching the scary databases

Phase 3: The Scary Shit

• Primary customer databases
• Payment processing (do this last, seriously)
• Anything that pages you at 3am when it breaks
• Only do this when you're 100% confident in your process

Who's Going to Do All This Work?

You need people who know what they're doing, not just whoever's available.

Database Team (the people who actually understand this stuff):

• Figure out what breaks when you remove foreign keys
• Test migration tools until they find one that works
• Set up monitoring so you know when things go wrong
• Establish performance baselines (so you can prove it wasn't your fault later)

Application Developers (the ones who have to rewrite everything):

• Rip out foreign key dependencies and rewrite them in code
• Convert stored procedures to application logic
• Update connection strings and pray nothing else breaks
• Write tests for edge cases that database constraints used to handle

DevOps Team (the ones who get paged when it breaks):

• Make sure networks can actually reach PlanetScale
• Set up alerts for when the migration goes sideways
• Rewrite CI/CD for PlanetScale's workflow
• Plan rollback procedures (you'll probably need them)

Project Manager (the one who has to explain delays to executives):

• Coordinate schedules and dependencies
• Manage expectations (multiply all estimates by 2)
• Handle blame when timelines slip
• Define what "success" means (hint: it's not just "data moved")

Your New Operational Reality

Everything you knew about database operations is different now.

Schema changes work differently:

• No more direct ALTER TABLE statements, branching workflow only
• Deploy requests replace your old migration scripts
• Emergency schema changes take longer, hope it's not actually an emergency

Monitoring needs to be relearned:

• PlanetScale Insights replaces your old query monitoring
• Alert thresholds are wrong now, prepare for false alarms
• Prometheus integration if you're into that sort of thing

Backups are someone else's problem:

• Automated backups happen whether you want them or not
• Disaster recovery is mostly PlanetScale's problem now
• Test restores in staging, you don't get to test in prod anymore

What You Get After 6 Months (If You're Lucky)

The good stuff:

• No more 3am pages for database maintenance windows
• Scaling happens automatically (when it works)
• Schema changes don't require downtime planning
• Someone else deals with MySQL security patches

The reality check:

• You're still responsible when the application breaks
• Performance optimization is still your job
• Cost optimization becomes critical (row-based pricing adds up)
• You're now dependent on PlanetScale's uptime

Most teams are happy they migrated after 6 months. The question is whether you'll survive those 6 months.