Skip to content

Help

Before you migrate: a checklist

Tested with:Databasezy API v1 · zb CLI 0.1

Most failed migrations fail for reasons you can check in advance: the source cannot be reached from our side, it lacks a setting that continuous sync needs, or the target is too small. Run through this list, then do a dry run. How migrations work explains each step in detail, and each source provider has its own guide under Migration sources.

  • Migrate into the same engine where you can. Moves between engines are covered in Engine conversions.
  • Check the target version is supported for your engine on its engine page. Preflight reads the source and target versions.
  • PostgreSQL extensions: preflight lists the extensions the source uses. Check the ones you need are available on Databasezy in Extensions before you start.
  • With --create, the new instance gets the size you pass with --size, or your plan’s default. It is not derived from the source.
  • Preflight recommends a storage size (about 1.5 times the source), but does not apply it. Grow the target’s storage first if it is too small: storage can grow but never shrink.
  • Check the target’s connection limit covers your application’s pools.
  • --mode copy (the default) copies once. Writes must stop on the source before the copy starts, so the downtime is the whole copy.
  • --mode copy_and_sync keeps the target in step until you cut over, so downtime is usually seconds. It works for PostgreSQL, TimescaleDB and MySQL targets, from a connection string or another Databasezy instance, and needs a target on a paid plan. MariaDB is copy only.

PostgreSQL:

  • wal_level = logical (changing it usually needs a restart of the source).
  • A user with the replication privilege (REPLICATION, or rds_replication on RDS). Not needed when the source is another Databasezy instance: Databasezy creates a replication-only login for the migration.
  • A primary key on every table, or ALTER TABLE ... REPLICA IDENTITY FULL on the ones without.
  • No schema changes (DDL) between the copy and cutover: logical replication does not carry them, nor large objects.

MySQL:

  • Binary logging on, binlog_format = ROW, gtid_mode = ON, and the REPLICATION SLAVE grant for the user. The grant is not needed when the source is another Databasezy instance (Databasezy creates the replication user).
  • The copy connects out from the cell hosting your target, not from your computer. Allow its egress addresses on the source’s firewall or IP access list before you start: the migration wizard lists them, as do zb migrate ... --to <instance> --dry-run and GET https://api.databasezy.com/v1/regions/<region>/egress. If preflight reports egress.unknown, the region has none published yet: either let the source accept TLS connections from any address during the migration, or use --from local from a machine that can reach the source.
  • If the source’s certificate is self-signed or from a private CA (for example Heroku Key-Value), pass the CA with --ca-file ca.pem (copy mode); verification is never turned off.
  • Use the source’s public, direct endpoint, not a connection pooler or a private network name.
  • For a database on your laptop or in Docker, use zb migrate --from local (with --container <name> for Docker). No inbound access is needed.

Create a user that can read every table you move (and replicate, for continuous sync). Drop it or change its password after cutover. The source password is encrypted and deleted after the migration ends or after 24 hours, and it is never written to logs or events.

shell
zb migrate --from <source> --to <instance_id> --mode copy_and_sync --dry-run

This prints the offline checklist, with a code on each item, and the exact plan, without starting anything. Fix every blocking item first. See A migration failed for what the codes mean.

  • Decide how you will stop writes to the source (maintenance mode, scale writers to zero, or revoke the app user).
  • Put the new connection details in your secret store ahead of time, and add your application’s addresses to the target’s IP allow-list.
  • For PostgreSQL --reverse-sync, the old source connects back to the instance, so its address must be on the allow-list too.
  • Keep the source until you are confident in the new instance.
  • One migration at a time per target instance.
  • --include and --exclude take up to 200 entries each.
  • Uploaded files: up to 500 GiB on paid plans, 50 MiB on Free. Files above 64 MiB go in parts and an interrupted upload resumes (zb migrate resume <id>, or pick the same file again in the portal); an upload not finished within 48 hours is discarded.
  • When a migration completes, fails or is cancelled you get a short report by email (turn it off, or copy your organization’s owners and admins, on the project’s Migrations page). Each database’s migrations, with their progress and reports, are under that database’s Migrate in tool.

Search the help center or ask the assistant in the portal Help panel. If that does not solve it, open a support ticket from the portal (Help → Open a ticket). Include the target instance id, the source provider and engine version, the output of the dry run (with any password removed), and the time it happened in UTC. Never paste passwords, connection strings with passwords, API keys or patient data (PHI) into a ticket. See How to get help.