Commands and metrics
The 27 commands, every option they take, and the metrics the dashboard serves.
Every command
| Command | What it does |
|---|---|
init | Set up a hop: in a terminal, asks for the two addresses and the passwords, connects, says what it found and what it will do, and writes the hop. |
doctor | What this machine can do, and whether the configured hops connect. |
scope | Say what the hop takes and leaves out - its include and exclude lists, the rows, columns and names it narrows, the changes it does not carry - and the target's tables left out as a transfer service's own, by name and by whose they are. |
leftovers | Give back the writes a run held on a side and left behind: each exactly as its record took it, where its holder is gone; one whose holder still runs is left, with why. |
drain | Drain the running change tail to a position and hold it there: it cannot be taken back, so it is shown first and taken with --go against the target the plan named. |
change-sheet | Write the plan's steps as a change sheet (CSV and JSON beside the hop's reports) with stable ids a team's task sheet can hold, or, with --back, write a run's evidence back to one step. |
advise | Show the migration playbook for this hop's service. |
assess | Premigration readiness check: CDC prerequisites, risky tables, encoding, extensions, accounts. |
schema | Target schema workflows: preparation plan (default), cross-engine DDL conversion (--convert), versioned migration files (--migration). |
check | Read-only validation of target vs source. |
sync | Make target equal to source, or run a whole migration flow. |
migrate | Two addresses and a goal in; the whole migration run to a verified outcome: the assessment, the copy, the catch-up, the proof and the cutover's readiness, every way chosen by migkit, a database that fails held apart while the others go on, and asked only what migkit cannot find out (autonomous.QUESTIONS). |
move | Move data for this hop. |
cutover | The cutover: live switch with --go, or rehearse with --dry-run. |
watch | Watch a running migration load: row counts, rate, ETA, replication state. |
report | Render the HTML report from the last check run and export the hop's evidence (what moved, every verdict with both sides' counts and digests and how to take them again, decisions, approvals, repairs, outages - HTML, Markdown, JSON, CSV), or --serve the web view: every hop's outcomes, progress, approvals, offers and evidence for the people each hop names, the REST API, and a Prometheus /metrics endpoint (migkit.web). |
history | Audit trail: saved rollback states and every write migkit made, read from the local changelog and state journals. |
autopilot | Execute turn-key autonomous end-to-end migration pipeline. |
failback | Execute zero-loss reverse failback to source within 48h post-cutover. |
rollback | Restore target sequences from a saved state, put back the rows the repairs since it wrote, where the target still holds what they wrote; where the hop streamed back or cut over, the old source's counters raised past the new primary's. |
users | Sync logins source -> target keeping the same password. |
telemetry | Product telemetry: what migkit did, never what it carried. |
secrets | The user's own keys: replace the masking key, describe it. |
export-manifest | Export neutral portable manifest package for exit portability (Row 668: NEED20). |
diagnostics-bundle | Generate bounded, sanitized support diagnostic bundle (Row 671: NEED23). |
verify-partial-access | Verify partial access export against upstream objects with honest coverage (Row 672: NEED24). |
estate | Every database these addresses, networks and accounts reach: its engine, version and size, the time its move takes by migkit's own measured runs, and its cost on the catalog's machines. |
init
migkit init [OPTIONS]
Set up a hop: in a terminal, asks for the two addresses and the passwords, connects, says what it found and what it will do, and writes the hop. Without one, reads MIGKIT_SOURCE and MIGKIT_TARGET (MIGKIT_SOURCE_PASSWORD, MIGKIT_TARGET_PASSWORD, MIGKIT_GOAL, MIGKIT_HOP), or writes a template to edit.
Installed from a package there is no checkout to copy an example out of, so migkit writes the template itself. Mode 600, because what goes in it next can be a secret's reference.
| Option | What it does |
|---|---|
--here | write ./conf/hops.yaml in this directory instead of the user config directory |
--force | overwrite an existing file |
doctor
migkit doctor [OPTIONS]
What this machine can do, and whether the configured hops connect.
Safe to run before anything is configured - that is the point of it.
Every check/repair/move step migkit runs is a wrapper over a proven external program; --install pulls whichever are missing so any machine or teammate is one command from a full toolchain.
| Option | What it does |
|---|---|
--install | auto-install every missing external tool via the platform package manager (brew/apt) - get a fresh machine ready |
scope
migkit scope [OPTIONS] HOP_NAME
Say what the hop takes and leaves out - its include and exclude lists, the rows, columns and names it narrows, the changes it does not carry - and the target's tables left out as a transfer service's own, by name and by whose they are. Reads only; writes nothing.
| Option | What it does |
|---|---|
--db | single database |
leftovers
migkit leftovers [OPTIONS] HOP_NAME
Give back the writes a run held on a side and left behind: each exactly as its record took it, where its holder is gone; one whose holder still runs is left, with why.
| Option | What it does |
|---|---|
--db | single database |
--list | say each hold and what would be done, give none back |
drain
migkit drain [OPTIONS] HOP_NAME
Drain the running change tail to a position and hold it there: it cannot be taken back, so it is shown first and taken with --go against the target the plan named. Says where the tail really stopped.
| Option | What it does |
|---|---|
--db | one database of the hop |
--to | the position to drain the change tail to, written the way the engine writes it, or now |
--wait | seconds the tail may take to reach it |
--go | drain and hold the tail there; default shows the plan |
change-sheet
migkit change-sheet [OPTIONS] HOP_NAME
Write the plan's steps as a change sheet (CSV and JSON beside the hop's reports) with stable ids a team's task sheet can hold, or, with --back, write a run's evidence back to one step.
| Option | What it does |
|---|---|
--db | one database of the hop's scope; default all of them |
--back | a step's id: write the run's evidence back to it instead of exporting the plan |
--status | with --back: done, failed, ... |
--seconds | with --back: the seconds the step took |
--proof | with --back: what it stands on |
--rows | with --back: rows a phase that wrote into the target wrote |
--unit | with --back: the name of that write, if not the step's id |
advise
migkit advise [OPTIONS] HOP_NAME
Show the migration playbook for this hop's service.
assess
migkit assess [OPTIONS] HOP_NAME
Premigration readiness check: CDC prerequisites, risky tables, encoding, extensions, accounts. Run before starting any mover.
schema
migkit schema [OPTIONS] HOP_NAME
Target schema workflows: preparation plan (default), cross-engine DDL conversion (--convert), versioned migration files (--migration).
| Option | What it does |
|---|---|
--db | single database |
--convert | transpile source DDL to the target dialect (hetero hops) |
--migration | generate versioned V/U migration files from the live schema diff |
--apply | with --convert: execute the DDL on target |
--out | with --migration: output directory |
check
migkit check [OPTIONS] HOP_NAME
Read-only validation of target vs source. Never writes to either side.
When counts and data both run, row counts ride along with the checksum query, so nothing is scanned twice. Suspect rows are proven in-flight or real via the replication fence (LSN-based) instead of guesswork.
Ends 0 where the two are the same, 1 where they differ, 3 where the run could not say (an answer not taken, nothing compared, a narrowed run) - verdict.json says which and why.
| Option | What it does |
|---|---|
--db | single database |
--table | single table (schema.table) |
--only | comma list: schema,counts,autoinc,data,deep,params |
--deep | add deep checks: fk orphans, disabled triggers, column drift, matview/grants parity, boundary freshness |
--drill | column-level sample diff for one table (needs --db and --table) |
--limit | with --drill: sample rows |
--consistent | checksum every table of a db inside one repeatable-read transaction per side, with the src LSN captured as the convergence fence (postgres) |
--workers | parallel databases, default from conf |
--resume | skip checks already ok in last summary |
--exclude | comma list of db or db.schema.table patterns to skip, added to the hop's |
--sample | a quick signal in about this many seconds: random rows read by key on both sides, said as a sample - the full check still decides |
sync
migkit sync [OPTIONS] HOP_NAME
Make target equal to source, or run a whole migration flow.
Default (reconcile) shows/repairs the last check's diffs; --apply executes, --go checkpoints for rollback. --mode runs the whole flow end to end with verification wrapped around every step, so migkit can stand in for a managed migration service on a trusted VM - the same move, the same repair and the same check as the commands of their own, and the exit code the last check's.
| Option | What it does |
|---|---|
--db | one database, or all diffed dbs if omitted |
--kind | - |
--mode | run a whole flow: verify (read-only assurance), seed (initial load, then the check and a repair of what differs), stream (follow live changes + delta verify), migrate (load and follow, then the check). default reconcile = repair the last check's diffs |
--apply | execute the repair plan, default is dry-run |
--go | checkpointed check+repair sweep with rollback state |
--serve | stream and migrate: run the verify loop forever (VM/service) |
--interval | --serve: seconds between cycles |
--on-conflict | rows that differ: source-wins overwrites the target (the default, source is truth); keep-target preserves them and fixes only missing/extra. The hop's own on_conflict where not given |
--tag | with --go: label this state, e.g. pre-cutover |
migrate
migkit migrate [OPTIONS] [SOURCE] [TARGET]
Two addresses and a goal in; the whole migration run to a verified outcome: the assessment, the copy, the catch-up, the proof and the cutover's readiness, every way chosen by migkit, a database that fails held apart while the others go on, and asked only what migkit cannot find out (autonomous.QUESTIONS).
| Option | What it does |
|---|---|
--goal | copy once, keep in sync, or move and prepare the switch |
--hop | a hop already set up, instead of two addresses |
--go | write; default shows the plan |
--switch | a cutover proved ready switches the applications; without it the switch is asked |
--why | the decisions and evidence of the last run |
move
migkit move [OPTIONS] HOP_NAME
Move data for this hop. migkit picks how.
full: the fastest bulk path available for the engine, falling back to a chunked copy that resumes after a crash. A single table always takes the resumable path - restartability matters more than raw speed there. cdc: the engine's native change feed where it has one, otherwise migkit stands up its own streaming pipeline.
There is nothing to choose: the same command does the right thing on every engine, and migkit doctor says what this machine can do. Whatever moves the data, migkit verifies it.
Use only over a trusted network (or run migkit on a cloud VM).
| Option | What it does |
|---|---|
--db | - |
--table | schema.table (full mode) |
--mode | full = bulk copy, cdc = follow live changes, full+cdc = initial load plus stream until cutover |
--chunk | rows per resumable chunk, when a resumable copy is used |
--drop | cdc modes: tear down replication |
--go | actually run, default shows the plan |
cutover
migkit cutover [OPTIONS] HOP_NAME
The cutover: live switch with --go, or rehearse with --dry-run.
| Option | What it does |
|---|---|
--db | one database of the hop |
--dry-run | run shadow cutover flight simulator |
--go | execute live cutover |
watch
migkit watch [OPTIONS] HOP_NAME
Watch a running migration load: row counts, rate, ETA, replication state. --verify turns it into a continuous validation loop: transient diffs that heal next cycle are replication lag, persistent ones are real. --verify --delta verifies only what changed, so it can run forever against billion-row databases, and says when a flip is safe. With --count it ends as its last cycle's verdict does.
| Option | What it does |
|---|---|
--db | - |
--interval | seconds between samples (default 30, or 300 with --verify) |
--count | samples/cycles then exit, 0 = forever |
--verify | re-run read-only checks each cycle instead of sampling row counts (continuous validation) |
--only | with --verify: the checks each cycle runs (decided from their measured time against the interval when not named) |
--delta | with --verify: O(changes) mode - each cycle re-verifies only the rows touched since the last verified point (WAL slot / binlog / change stream driven) |
--teardown | drop the delta slot/position --delta keeps, and exit |
report
migkit report [OPTIONS] [HOP_NAME]
Render the HTML report from the last check run and export the hop's evidence (what moved, every verdict with both sides' counts and digests and how to take them again, decisions, approvals, repairs, outages - HTML, Markdown, JSON, CSV), or --serve the web view: every hop's outcomes, progress, approvals, offers and evidence for the people each hop names, the REST API, and a Prometheus /metrics endpoint (migkit.web).
| Option | What it does |
|---|---|
--open | open in browser |
--refresh | render the report again from the last check's answers on disk (no re-check); the answers stay as the check took them |
--serve | serve the web view and the API for every hop - signed in, with roles - instead of writing a file |
--metrics | print Prometheus metrics for every hop and exit (the dashboard also exposes them at /metrics) |
--port | with --serve: listen port |
history
migkit history [OPTIONS] HOP_NAME
Audit trail: saved rollback states and every write migkit made, read from the local changelog and state journals. migkit writes no bookkeeping into the destination, so the audit is local-only.
| Option | What it does |
|---|---|
--db | - |
--show | print one state in detail |
autopilot
migkit autopilot [OPTIONS] HOP_NAME
Execute turn-key autonomous end-to-end migration pipeline.
| Option | What it does |
|---|---|
--dry-run | Rehearse migration flight sim and stages without applying live cutover |
--skip-tuning | Skip target hardware parameter tuning profile |
--skip-flight-sim | Skip pre-cutover shadow flight simulator rehearsal |
--auto-approve | Auto-approve verified stages |
--timeout | Overall migration timeout in seconds |
failback
migkit failback [OPTIONS] HOP_NAME
Execute zero-loss reverse failback to source within 48h post-cutover.
| Option | What it does |
|---|---|
--force | Force failback even if past 48h retention window |
--timeout | Failback timeout in seconds |
rollback
migkit rollback [OPTIONS] HOP_NAME
Restore target sequences from a saved state, put back the rows the repairs since it wrote, where the target still holds what they wrote; where the hop streamed back or cut over, the old source's counters raised past the new primary's. With --apply, under one hold of the hop, the application's writes given back last - after everything they would write over is put back.
| Option | What it does |
|---|---|
--db | - |
--state | state timestamp or tag, default latest |
--apply | - |
users
migkit users [OPTIONS] HOP_NAME {test|create|verify|setpw|rollback}
Sync logins source -> target keeping the same password.
test compare users (read-only), write users.json to the report dir setpw mongo only: set the real passwords on users that already exist on the target, from --passwords (mongo credentials cannot be copied: SCRAM is one-way and DocumentDB blocks writes to system.users) create make the missing users on the target (dry-run unless --apply); mysql copies the password hash = same password, grants replayed from the source; postgres reads passwords from --passwords verify re-compare; exit 0 only when no gap remains rollback drop only the users this command created (dry-run unless --apply)
Cloud system accounts (AWS_*, rds*, tencent*) are excluded on both sides. Never touches the source.
| Option | What it does |
|---|---|
--apply | execute on the target (default is dry-run) |
--passwords | yaml file role: password for postgres create and for mongo setpw (managed sources lock password hashes; mysql needs no file - the hash is copied so the password stays identical) |
telemetry
migkit telemetry [OPTIONS] [show|off|on|push|receive] [BUCKET]
Product telemetry: what migkit did, never what it carried.
show the state, what is collected, and every event kept
off stop keeping events and delete those already kept, the
segments not yet pushed included
on keep events again, unless a policy or the environment says off
push send the sealed segments, once each, to BUCKET: an
S3-compatible bucket you run, signed in with its own
credentials (by hand only; nothing is ever sent on its own)
receive read BUCKET's segments back, check every event again, and
count them by kind, engine and way
| Option | What it does |
|---|---|
--schema | also print every field an event may have |
--endpoint | the bucket's store, where it is not the default one |
secrets
migkit secrets [OPTIONS] COMMAND [ARGS]...
The user's own keys: replace the masking key, describe it.
export-manifest
migkit export-manifest [OPTIONS] [HOP_NAME]
Export neutral portable manifest package for exit portability (Row 668: NEED20).
| Option | What it does |
|---|---|
--out | output path for manifest JSON |
diagnostics-bundle
migkit diagnostics-bundle [OPTIONS]
Generate bounded, sanitized support diagnostic bundle (Row 671: NEED23).
| Option | What it does |
|---|---|
--failure-class | failure class to reproduce |
--out | path to output zip bundle |
verify-partial-access
migkit verify-partial-access [OPTIONS]
Verify partial access export against upstream objects with honest coverage (Row 672: NEED24).
| Option | What it does |
|---|---|
--manifest | path to approved export manifest JSON |
estate
migkit estate [OPTIONS] [ADDRESSES]...
Every database these addresses, networks and accounts reach: its engine, version and size, the time its move takes by migkit's own measured runs, and its cost on the catalog's machines.
| Option | What it does |
|---|---|
--account | a provider account's instances, provider:product:region (aws:rds:us-east-1), read through its own API |
--user | who signs in where an address names nobody; the password is MIGKIT_SOURCE_PASSWORD's |
--to | the target engine the moves are sized for (the same engine where not given) |
--cloud | price on this cloud's types only |
--region | price in this region only |
Older names
Names earlier versions used, kept so scripts written for them still run:
| Name | Now |
|---|---|
hops | List configured hops - now part of migkit doctor. |
setup-target | Now: migkit schema HOP. |
repair | Now: migkit sync HOP [--apply]. |
replicate | Now: migkit move HOP --mode cdc / full+cdc. The move itself, with every guard it holds: this alias set a stream up on its own - into a hop that masks, a goal: verify hop, and torn down with no approval and outside the cutover. |
tail | Now: migkit move HOP --mode cdc --db X - the move itself, with every guard it holds. |
convert-schema | Now: migkit schema HOP --convert. |
gen-migration | Now: migkit schema HOP --migration. |
sample-diff | Now: migkit check HOP --drill --db X --table Y. |
ui | Now: migkit report --serve. |
state | Now: migkit history HOP. |
monitor | Now: migkit watch HOP --verify. |
Metrics
migkit report --serve serves these at /metrics, for a scraper to alert on:
| Family | Type | What it is |
|---|---|---|
migkit_verdict | gauge | The hop's last verdict as a state set: one sample a verdict, 1 for the one its last check ended as (none: never checked) |
migkit_hop_status | gauge | The hop's last verdict (0 same, 1 different, 2 could not verify, 3 not checked, 4 incomplete) (deprecated until 1.0: migkit_verdict) |
migkit_check_answers | gauge | Answers the last check gave, by check and by each answer's status |
migkit_check_pass | gauge | Answers of a check that were the same (deprecated until 1.0: migkit_check_answers{status="ok"}) |
migkit_check_total | gauge | Answers of a check (deprecated until 1.0: migkit_check_answers) |
migkit_last_check_age_seconds | gauge | Age of the last verdict |
migkit_tail_running | gauge | A change tail is marked running here (0: its process is gone and it did not stop) |
migkit_tail_paused | gauge | The tail is holding still for a repair |
migkit_tail_heartbeat_age_seconds | gauge | Since the tail last went round its loop |
migkit_tail_behind_seconds | gauge | Since the tail last read to the end of the source's log |
migkit_tail_changes_applied_total | counter | Changes this tail has applied since it started |
migkit_tail_changes_applied | gauge | Changes this tail has applied since it started (deprecated until 1.0: migkit_tail_changes_applied_total) |
migkit_tail_stopped | gauge | The tail stopped on an error and has not been started again (1), or not (0) |
migkit_tail_retention_margin_seconds | gauge | How much longer the source keeps what the tail has not read (MySQL, MongoDB) |
migkit_tail_retention_margin_bytes | gauge | What the source can still write before the tail's slot loses WAL (PostgreSQL) |
migkit_tail_source_held_bytes | gauge | Log the source holds for the tail |
migkit_tail_commit_lag_seconds | gauge | From the source's commit of the last change applied to the target's (the two clocks' difference included) |
migkit_tail_applied_through_age_seconds | gauge | Since the source committed the last change the tail applied |
migkit_tail_tables | gauge | Tables of the tail in each state: live, copying (added, copied beside the stream), parked (a DDL the target does not follow yet), removed |
migkit_tail_set_aside_bytes | gauge | Changes the tail holds on this machine for tables being copied or parked |
migkit_follow_applying | gauge | The change leg run from here is applying (0: it waits to be told to) |
migkit_follow_behind_bytes | gauge | Source log the change leg run from here has not received yet |
migkit_follow_held_bytes | gauge | Log the change leg has received and not applied, by its own account (the target's origin is the proof) |
migkit_move_rate_rows_per_second | gauge | A running move's recent rate (a moving average of its last windows) |
migkit_move_workers | gauge | How many a running move carries at once |
migkit_move_rows_done | gauge | Rows a running move has copied |
migkit_move_time_left_seconds | gauge | Time left of each phase of a move, by estimate: p50 and p90 as planned, live from the recent rate |
migkit_move_eta_seconds | gauge | Time left of each phase of a move (deprecated until 1.0: migkit_move_time_left_seconds) |
migkit_move_phase_never | gauge | A phase that cannot finish at the rates measured (1: a catch-up slower than the changes arriving), or can (0) |
migkit_move_resource_bytes_per_second | gauge | What each resource of a move allows, by its key and where the number came from |
migkit_move_resource_binding | gauge | The resource that sets a move's rate, by its key |
migkit_move_resource_info | gauge | A resource's key, and what an operator reads for it |
migkit_resource_bytes_per_second | gauge | What each resource of a move allows (deprecated until 1.0: migkit_move_resource_bytes_per_second) |
migkit_resource_binding | gauge | The resource that sets a move's rate (deprecated until 1.0: migkit_move_resource_binding) |
migkit_worker_memory_bytes | gauge | What one worker of a move holds for its widest rows |
migkit_move_rows | gauge | Rows the copy has carried into a table |
migkit_move_tables | gauge | Tables the copy of a database holds a place for |
migkit_move_tables_done | gauge | Tables the copy of a database finished |
migkit_copy_way_rows_per_second | gauge | Rows a second the last copy by a way went at, by the way's key |
migkit_copy_way_seconds | gauge | Seconds the last copy by a way took, by the way's key |
migkit_way_info | gauge | A way's key, and the words an operator reads for it |
migkit_copy_rows_per_second | gauge | Rows a second the last copy by a way went at (deprecated until 1.0: migkit_copy_way_rows_per_second) |
migkit_copy_seconds | gauge | Seconds the last copy by a way took (deprecated until 1.0: migkit_copy_way_seconds) |
migkit_check_seconds | gauge | Seconds a check of a database took in the last run |
migkit_verify_ranges_done | gauge | Ranges of a table the verify in progress has proved equal |
migkit_verify_rows_done | gauge | Rows in those ranges |
migkit_table_rows | gauge | Rows a table held on a side at its last digest |
migkit_table_same | gauge | A table's rows and digest equal on both sides as one run took them (1) or not (0); a table one run took one side of has none |
migkit_cutover_outage_seconds | gauge | Write outage the last cutover measured |
migkit_cutover_phase_seconds | gauge | Seconds a phase of the last cutover took |
migkit_cutover_running | gauge | A cutover is under way (1), or not (0) |
migkit_two_way_conflicts_total | counter | Rows a two-way tail found both sides had changed, by table, kind and what was decided, since its reports began |
migkit_two_way_conflicts | gauge | Rows a two-way tail found both sides had changed, by table, kind and what was decided, since its reports began (deprecated until 1.0: migkit_two_way_conflicts_total) |
migkit_two_way_rows_parked | gauge | Rows a two-way conflict set aside until they are decided on both sides |
migkit_stream_behind_source_seconds | gauge | How far the hop's change stream's reader is behind the source, by its own account |
migkit_stream_events_seen_total | counter | Changes the hop's stream reader has read since it started |
migkit_stream_events_seen | gauge | Changes the stream's reader has read since it started (deprecated until 1.0: migkit_stream_events_seen_total) |
migkit_stream_queue_remaining | gauge | Room left in the stream reader's queue |
migkit_stream_connected | gauge | The stream's reader is connected to the source (1) |
migkit_stream_snapshot_tables_remaining | gauge | Tables the stream's first read has still to read |
migkit_stream_running | gauge | A part of the change stream is running (1) or not (0) |
migkit_collect_age_seconds | gauge | Since the snapshot these metrics are read from was taken |
migkit_collect_seconds | gauge | Seconds the last snapshot took to take |
migkit_collect_errors_total | counter | Readings that failed while a snapshot was taken, by what was being read |