Skip to content

CLI reference ​

Use migrate --help or migrate <command> --help to confirm the flags in your installed version. Use migrate version to identify the binary.

Global flags ​

FlagDefaultMeaning
--config, -cAutomatic searchSelect a file; see search order when omitted
--working-dir, -wCurrent directoryResolve config from this directory and override migration working directory
--non-interactivefalseFail instead of requesting secrets or approval for unknown SSH host keys

new config ​

sh
migrate new config [filename] [--format yaml|json] [--multi] [--shards N] [--ssh-tunnel] [--force]
migrate new config shards.yml --multi --shards 4
migrate new config shards-ssh.yml --multi --ssh-tunnel --proxy socks5

Generate migration_config.yml. Use --multi for multiple databases, --shards N to set how many, --ssh-tunnel to add SSH settings and --proxy socks5|http to add an SSH upstream proxy. Choose SSH authentication with --ssh-auth agent|private_key|password. --shards N requires --multi and a positive count, numbered from 0. --proxy requires --ssh-tunnel. --force permits overwriting an existing file. A .json filename or --format json selects JSON output. Run migrate new config --help for all options; see configuration for common setups.

new version ​

sh
migrate new version <description> [-v <version>] [--format sql|js|ts|mjs]

Create a version file in the migration directory. --version / -v overrides the generated version; --format defaults to sql. Quote descriptions with spaces, as in migrate new version "init users"; spaces become underscores in filenames. See SQL migrations or script migrations.

Multiple databases ​

With data_sources configured, create/baseline/status/up/down visit every source. Each accepts --parallel N (default 8). One failure does not cancel other targets; results are grouped by source and any failure yields a nonzero exit. See multiple databases for shared files and SSH settings. status --output json returns results sorted by data-source name. Each item has data_source and status, plus migrations on success or error on failure.

create ​

sh
migrate create

Idempotently create the history table. User migration files are not applied.

baseline ​

sh
migrate baseline

Record pending migrations as baseline without executing them. First confirm the existing database already matches those files. See History and baseline.

up ​

sh
migrate up [--dry-run]

Apply pending versions in order. Dry-run prints SQL or script plans without executing user migrations; it may connect to read history. See Apply migrations.

down ​

sh
migrate down <to-version> [--dry-run]
migrate down --all [--dry-run]

Reverse versions above the target, keeping the target applied, or reverse all applied versions. The target and --all are mutually exclusive; one is required. See Rollback.

status ​

sh
migrate status [--output table|json]

Compare files and database history. --output / -o defaults to table. See status values.

capabilities ​

sh
migrate capabilities [--output text|json]

Report build formats, aliases, script verification and transaction limits without reading config or connecting to a database. --output / -o defaults to text. See Supported databases.

version ​

sh
migrate version

Print the CLI version without reading config or opening a database connection. This reports the tool version, not the database's latest migration version.