From a Docker container

A database in a local container moves to Databasezy without opening any port to the internet: zb streams a dump from your machine to a pre-signed upload URL.

Docker container migration at a glance, from the migration source catalogue

Status	Available
Target engines	PostgreSQL , TimescaleDB , MySQL , MariaDB , Valkey , Redis (compat) , MongoDB (Percona Server)
How we read it	Local tools (zb migrate --from local)
Continuous sync	No, copy only
Provider preset	None yet (generic)

Before you start

• A Databasezy instance of the matching engine, or use --create.
• The container running. zb migrate --container uses the dump tool inside the container’s image, so only docker is needed on your machine. The official postgres, mysql, mariadb, valkey, redis and mongo images ship their tools.

Find the connection string

There is no connection string to hand over. Name the container with --container <name|id> (as docker ps shows it) and zb runs the dump inside it with docker exec, using the credentials the container was started with. If the container publishes its port (-p 5432:5432) and the dump tool is installed locally, zb migrate --from local without --container runs it against localhost using the tool’s own environment variables (PGHOST, MYSQL_HOST and so on).

Docker container notes

• --container runs pg_dump (Postgres, TimescaleDB), mysqldump or mariadb-dump (MySQL, MariaDB), valkey-cli or redis-cli --rdb (Valkey, Redis) or mongodump --archive (MongoDB) inside the container and uploads its output. The CLI reference lists the exact flags.
• Credentials come from the container’s own environment (POSTGRES_PASSWORD, MYSQL_ROOT_PASSWORD, MARIADB_ROOT_PASSWORD, REDIS_PASSWORD, MONGO_INITDB_ROOT_USERNAME/MONGO_INITDB_ROOT_PASSWORD) and reach the tool through its environment, never its command line. To use other credentials, export ZB_DB_USER and ZB_DB_PASSWORD; zb passes them as docker exec -e ZB_DB_PASSWORD, so the value is read from your environment.
• Without --db, Postgres dumps POSTGRES_DB, MySQL and MariaDB dump MYSQL_DATABASE / MARIADB_DATABASE, and MongoDB dumps every database.
• If pg_dump (or the engine’s tool) is not installed locally and you run --from local without --container, the CLI prints the install command and names any running container whose image matches the engine, with the --container flag to rerun with. It never picks a container on its own.
• SQLite and ClickHouse containers are not supported with --container: copy the file out with docker cp my-app:/data/app.db ./app.db and run zb migrate --from ./app.db --engine libsql.
• Local sources are copy only. Stop the application container while you dump if it writes continuously.

Migrate

Portal

1. Open the target PostgreSQL instance (create one first if you need to) and choose the Migrate in tab.
2. Under Source, pick Upload a dump and drop the file. The format is detected from the file name.
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

# Dump inside the container with docker exec (only docker needed locally)
zb migrate --from local --engine postgres --container my-postgres --db app --create --dry-run
zb migrate --from local --engine postgres --container my-postgres --db app --create

# Other engines
zb migrate --from local --engine mysql --container my-mysql --db app --create
zb migrate --from local --engine valkey --container my-valkey --create
zb migrate --from local --engine mongodb --container my-mongo --db app --create

# Or, with pg_dump installed locally and the port published on localhost
PGHOST=localhost PGPORT=5432 PGUSER=postgres PGPASSWORD=pw \
zb migrate --from local --engine postgres --db app --create

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": "upload",
    "filename": "app.dump"
  },
  "mode": "copy"
}'

# The response carries a pre-signed upload_url; PUT the file to it
curl -sS -T app.dump "$UPLOAD_URL"

# 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"

Verify

Verification compares what the engine exposes: row counts per table for SQL engines, document counts per collection for document engines, key counts for key-value engines. Mismatches are listed in zb migrate status <mig_id> and the Verify step. Run your application’s 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

zb says the dump tool is not installed

Install it with the printed command, or add --container <name> to run the tool inside the container. The message lists the running containers whose image matches the engine.

zb says the container is not running, or is not found

--container takes the name or id from docker ps. Start a stopped container with docker start <name>. If the message says Docker cannot be reached, start Docker Desktop or the Docker daemon. These errors exit with code 6.

zb says the tool is not available inside the container

The image has no dump tool (FerretDB and many slim or distroless images), or no sh. Publish the port and run zb migrate --from local with the tool installed locally, or dump with a sidecar container that has the tools.

The restore stops on an extension

The source uses an extension Databasezy does not ship. Drop it on the source if it is unused, or exclude the objects that depend on it with --exclude.

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