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.
1. Choose the target engine and version
Section titled “1. Choose the target engine and version”- 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.
2. Size the target
Section titled “2. Size the target”- 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.
3. Copy only, or copy and sync?
Section titled “3. Copy only, or copy and sync?”--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_synckeeps 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.
4. Prepare the source for continuous sync
Section titled “4. Prepare the source for continuous sync”PostgreSQL:
wal_level = logical(changing it usually needs a restart of the source).- A user with the replication privilege (
REPLICATION, orrds_replicationon 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 FULLon 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 theREPLICATION SLAVEgrant for the user. The grant is not needed when the source is another Databasezy instance (Databasezy creates the replication user).
5. Make the source reachable
Section titled “5. Make the source reachable”- 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-runandGET https://api.databasezy.com/v1/regions/<region>/egress. If preflight reportsegress.unknown, the region has none published yet: either let the source accept TLS connections from any address during the migration, or use--from localfrom 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.
6. Use a dedicated source user
Section titled “6. Use a dedicated source user”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.
7. Do a dry run
Section titled “7. Do a dry run”zb migrate --from <source> --to <instance_id> --mode copy_and_sync --dry-runThis 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.
8. Plan the cutover
Section titled “8. Plan the cutover”- 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.
Limits to know
Section titled “Limits to know”- One migration at a time per target instance.
--includeand--excludetake 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.
Still stuck?
Section titled “Still stuck?”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.