From PlanetScale

PlanetScale databases are MySQL-compatible on top of Vitess. They move to a Databasezy MySQL instance with mysqldump; plan a short write freeze, because Vitess does not offer the binlog to outside replicas.

PlanetScale migration at a glance, from the migration source catalogue

Status	Available
Target engines	MySQL
How we read it	Connection string
Continuous sync	No, copy only
Provider preset	planetscale

Before you start

• A Databasezy MySQL instance, or use --create.
• A password for the branch you migrate, with read access.
• A maintenance window long enough for the copy.

Find the connection string

In the PlanetScale dashboard, open the database, pick the branch and create a password with read access. Note the host it shows (aws.connect.psdb.cloud or your region’s) and build a mysql://user:password@host/database URL.

PlanetScale notes

• Dumps run with --set-gtid-purged=OFF; Vitess does not expose GTIDs to outside replicas.
• Foreign keys are checked after import if the source had them disabled.

The preset adds ssl-mode=REQUIRED when the URL has no TLS setting, dumps with mysqldump --single-transaction --set-gtid-purged=OFF, and blocks copy and sync (planetscale.sync_unsupported).

Migrate

Portal

1. Open the target MySQL instance (create one first if you need to) and choose the Migrate in tab.
2. Under Source, pick Connection string and paste the URL. The host is recognised as PlanetScale; you can also pick it from the provider list.
3. Run Preflight and work through the checklist. Blocking items must be fixed before the copy starts.
4. Start the copy and follow Copy and Verify. Mismatches are listed per table or collection.
5. Point your application at the new instance. The Report step keeps the timings and verification results.

CLI

shell

# Dry run: print the preflight checklist and the plan, change nothing
zb migrate --from "mysql://abc123:[email protected]/app" --to inst_abc --dry-run

# Start it (or use --create --size s1 instead of --to to create the target)
zb migrate --from "mysql://abc123:[email protected]/app" --to inst_abc

zb migrate status mig_123

API

shell

curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/instances/inst_abc/migrations \
  -H "Authorization: Bearer $ZB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": {
    "kind": "connection_string",
    "url": "mysql://abc123:[email protected]/app",
    "provider": "planetscale"
  },
  "mode": "copy"
}'

# Follow progress, preflight report and verification
curl -sS https://api.databasezy.com/v1/orgs/$ZB_ORG/instances/inst_abc/migrations/mig_123 -H "Authorization: Bearer $ZB_API_KEY"

PlanetScale databases often have no FOREIGN KEY constraints. The copy recreates only the constraints present in the dump, so check for orphaned rows before you add constraints later. AUTO_INCREMENT values come across in each table definition. Branching and deploy requests have no Databasezy equivalent; use one instance per environment.

Verify

Verification runs automatically after the copy and compares source and target: row counts per table, sequence or AUTO_INCREMENT values, the number of indexes and a schema hash. A missing table or a short row count fails the migration and lists what differs. Check the result with zb migrate status <mig_id> or the Verify step in the portal, then run your application’s own smoke tests against the new instance before you switch traffic.

Cutover

This source is copy only. Writes that reach the source after the copy starts are not carried over, so for a database that changes, stop writes before you start the copy (maintenance mode, or scale writers to zero), run the migration, check verification, then point the application at the Databasezy connection string.

Roll back

A migration never deletes anything on the source. Until you decommission it, rolling back means pointing the application back at the source. Writes made on Databasezy after you switched are not on the source; if you need them, copy them back before switching. Cancel a running migration with zb migrate cancel <mig_id>; partially restored data stays on the target, so restart with --drop-target or delete the instance.

Troubleshooting

Preflight blocks copy and sync

That is expected for PlanetScale. Run a plain copy during a write freeze.

The restore fails on GTID statements

Dumps from Vitess must be taken with --set-gtid-purged=OFF. The preset does this; if you dumped by hand, dump again with that flag and upload the file.

Preflight cannot connect to the source

Check that the source accepts connections from the egress addresses preflight prints, that the host is the public one and that the password has not been rotated. zb migrate --dry-run shows the exact URL that will be used after any rewrites.

Preflight lists blocking items

Each item has a machine code and a fix. Nothing is written to the target until every blocking item is resolved; warnings do not block.

For anything else, zb migrate status <mig_id> shows the failing step and its message. How migrations work describes every step.