Commands and metrics

The 27 commands, every option they take, and the metrics the dashboard serves.

Every command

CommandWhat it does
initSet 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.
doctorWhat this machine can do, and whether the configured hops connect.
scopeSay 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.
leftoversGive 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.
drainDrain 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-sheetWrite 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.
adviseShow the migration playbook for this hop's service.
assessPremigration readiness check: CDC prerequisites, risky tables, encoding, extensions, accounts.
schemaTarget schema workflows: preparation plan (default), cross-engine DDL conversion (--convert), versioned migration files (--migration).
checkRead-only validation of target vs source.
syncMake target equal to source, or run a whole migration flow.
migrateTwo 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).
moveMove data for this hop.
cutoverThe cutover: live switch with --go, or rehearse with --dry-run.
watchWatch a running migration load: row counts, rate, ETA, replication state.
reportRender 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).
historyAudit trail: saved rollback states and every write migkit made, read from the local changelog and state journals.
autopilotExecute turn-key autonomous end-to-end migration pipeline.
failbackExecute zero-loss reverse failback to source within 48h post-cutover.
rollbackRestore 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.
usersSync logins source -> target keeping the same password.
telemetryProduct telemetry: what migkit did, never what it carried.
secretsThe user's own keys: replace the masking key, describe it.
export-manifestExport neutral portable manifest package for exit portability (Row 668: NEED20).
diagnostics-bundleGenerate bounded, sanitized support diagnostic bundle (Row 671: NEED23).
verify-partial-accessVerify partial access export against upstream objects with honest coverage (Row 672: NEED24).
estateEvery 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.

OptionWhat it does
--herewrite ./conf/hops.yaml in this directory instead of the user config directory
--forceoverwrite 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.

OptionWhat it does
--installauto-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.

OptionWhat it does
--dbsingle 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.

OptionWhat it does
--dbsingle database
--listsay 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.

OptionWhat it does
--dbone database of the hop
--tothe position to drain the change tail to, written the way the engine writes it, or now
--waitseconds the tail may take to reach it
--godrain 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.

OptionWhat it does
--dbone database of the hop's scope; default all of them
--backa step's id: write the run's evidence back to it instead of exporting the plan
--statuswith --back: done, failed, ...
--secondswith --back: the seconds the step took
--proofwith --back: what it stands on
--rowswith --back: rows a phase that wrote into the target wrote
--unitwith --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).

OptionWhat it does
--dbsingle database
--converttranspile source DDL to the target dialect (hetero hops)
--migrationgenerate versioned V/U migration files from the live schema diff
--applywith --convert: execute the DDL on target
--outwith --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.

OptionWhat it does
--dbsingle database
--tablesingle table (schema.table)
--onlycomma list: schema,counts,autoinc,data,deep,params
--deepadd deep checks: fk orphans, disabled triggers, column drift, matview/grants parity, boundary freshness
--drillcolumn-level sample diff for one table (needs --db and --table)
--limitwith --drill: sample rows
--consistentchecksum every table of a db inside one repeatable-read transaction per side, with the src LSN captured as the convergence fence (postgres)
--workersparallel databases, default from conf
--resumeskip checks already ok in last summary
--excludecomma list of db or db.schema.table patterns to skip, added to the hop's
--samplea 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.

OptionWhat it does
--dbone database, or all diffed dbs if omitted
--kind-
--moderun 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
--applyexecute the repair plan, default is dry-run
--gocheckpointed check+repair sweep with rollback state
--servestream and migrate: run the verify loop forever (VM/service)
--interval--serve: seconds between cycles
--on-conflictrows 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
--tagwith --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).

OptionWhat it does
--goalcopy once, keep in sync, or move and prepare the switch
--hopa hop already set up, instead of two addresses
--gowrite; default shows the plan
--switcha cutover proved ready switches the applications; without it the switch is asked
--whythe 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).

OptionWhat it does
--db-
--tableschema.table (full mode)
--modefull = bulk copy, cdc = follow live changes, full+cdc = initial load plus stream until cutover
--chunkrows per resumable chunk, when a resumable copy is used
--dropcdc modes: tear down replication
--goactually run, default shows the plan

cutover

migkit cutover [OPTIONS] HOP_NAME

The cutover: live switch with --go, or rehearse with --dry-run.

OptionWhat it does
--dbone database of the hop
--dry-runrun shadow cutover flight simulator
--goexecute 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.

OptionWhat it does
--db-
--intervalseconds between samples (default 30, or 300 with --verify)
--countsamples/cycles then exit, 0 = forever
--verifyre-run read-only checks each cycle instead of sampling row counts (continuous validation)
--onlywith --verify: the checks each cycle runs (decided from their measured time against the interval when not named)
--deltawith --verify: O(changes) mode - each cycle re-verifies only the rows touched since the last verified point (WAL slot / binlog / change stream driven)
--teardowndrop 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).

OptionWhat it does
--openopen in browser
--refreshrender the report again from the last check's answers on disk (no re-check); the answers stay as the check took them
--serveserve the web view and the API for every hop - signed in, with roles - instead of writing a file
--metricsprint Prometheus metrics for every hop and exit (the dashboard also exposes them at /metrics)
--portwith --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.

OptionWhat it does
--db-
--showprint one state in detail

autopilot

migkit autopilot [OPTIONS] HOP_NAME

Execute turn-key autonomous end-to-end migration pipeline.

OptionWhat it does
--dry-runRehearse migration flight sim and stages without applying live cutover
--skip-tuningSkip target hardware parameter tuning profile
--skip-flight-simSkip pre-cutover shadow flight simulator rehearsal
--auto-approveAuto-approve verified stages
--timeoutOverall migration timeout in seconds

failback

migkit failback [OPTIONS] HOP_NAME

Execute zero-loss reverse failback to source within 48h post-cutover.

OptionWhat it does
--forceForce failback even if past 48h retention window
--timeoutFailback 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.

OptionWhat it does
--db-
--statestate 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.

OptionWhat it does
--applyexecute on the target (default is dry-run)
--passwordsyaml 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
OptionWhat it does
--schemaalso print every field an event may have
--endpointthe 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).

OptionWhat it does
--outoutput path for manifest JSON

diagnostics-bundle

migkit diagnostics-bundle [OPTIONS]

Generate bounded, sanitized support diagnostic bundle (Row 671: NEED23).

OptionWhat it does
--failure-classfailure class to reproduce
--outpath 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).

OptionWhat it does
--manifestpath 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.

OptionWhat it does
--accounta provider account's instances, provider:product:region (aws:rds:us-east-1), read through its own API
--userwho signs in where an address names nobody; the password is MIGKIT_SOURCE_PASSWORD's
--tothe target engine the moves are sized for (the same engine where not given)
--cloudprice on this cloud's types only
--regionprice in this region only

Older names

Names earlier versions used, kept so scripts written for them still run:

NameNow
hopsList configured hops - now part of migkit doctor.
setup-targetNow: migkit schema HOP.
repairNow: migkit sync HOP [--apply].
replicateNow: 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.
tailNow: migkit move HOP --mode cdc --db X - the move itself, with every guard it holds.
convert-schemaNow: migkit schema HOP --convert.
gen-migrationNow: migkit schema HOP --migration.
sample-diffNow: migkit check HOP --drill --db X --table Y.
uiNow: migkit report --serve.
stateNow: migkit history HOP.
monitorNow: migkit watch HOP --verify.

Metrics

migkit report --serve serves these at /metrics, for a scraper to alert on:

FamilyTypeWhat it is
migkit_verdictgaugeThe 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_statusgaugeThe 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_answersgaugeAnswers the last check gave, by check and by each answer's status
migkit_check_passgaugeAnswers of a check that were the same (deprecated until 1.0: migkit_check_answers{status="ok"})
migkit_check_totalgaugeAnswers of a check (deprecated until 1.0: migkit_check_answers)
migkit_last_check_age_secondsgaugeAge of the last verdict
migkit_tail_runninggaugeA change tail is marked running here (0: its process is gone and it did not stop)
migkit_tail_pausedgaugeThe tail is holding still for a repair
migkit_tail_heartbeat_age_secondsgaugeSince the tail last went round its loop
migkit_tail_behind_secondsgaugeSince the tail last read to the end of the source's log
migkit_tail_changes_applied_totalcounterChanges this tail has applied since it started
migkit_tail_changes_appliedgaugeChanges this tail has applied since it started (deprecated until 1.0: migkit_tail_changes_applied_total)
migkit_tail_stoppedgaugeThe tail stopped on an error and has not been started again (1), or not (0)
migkit_tail_retention_margin_secondsgaugeHow much longer the source keeps what the tail has not read (MySQL, MongoDB)
migkit_tail_retention_margin_bytesgaugeWhat the source can still write before the tail's slot loses WAL (PostgreSQL)
migkit_tail_source_held_bytesgaugeLog the source holds for the tail
migkit_tail_commit_lag_secondsgaugeFrom the source's commit of the last change applied to the target's (the two clocks' difference included)
migkit_tail_applied_through_age_secondsgaugeSince the source committed the last change the tail applied
migkit_tail_tablesgaugeTables 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_bytesgaugeChanges the tail holds on this machine for tables being copied or parked
migkit_follow_applyinggaugeThe change leg run from here is applying (0: it waits to be told to)
migkit_follow_behind_bytesgaugeSource log the change leg run from here has not received yet
migkit_follow_held_bytesgaugeLog the change leg has received and not applied, by its own account (the target's origin is the proof)
migkit_move_rate_rows_per_secondgaugeA running move's recent rate (a moving average of its last windows)
migkit_move_workersgaugeHow many a running move carries at once
migkit_move_rows_donegaugeRows a running move has copied
migkit_move_time_left_secondsgaugeTime left of each phase of a move, by estimate: p50 and p90 as planned, live from the recent rate
migkit_move_eta_secondsgaugeTime left of each phase of a move (deprecated until 1.0: migkit_move_time_left_seconds)
migkit_move_phase_nevergaugeA 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_secondgaugeWhat each resource of a move allows, by its key and where the number came from
migkit_move_resource_bindinggaugeThe resource that sets a move's rate, by its key
migkit_move_resource_infogaugeA resource's key, and what an operator reads for it
migkit_resource_bytes_per_secondgaugeWhat each resource of a move allows (deprecated until 1.0: migkit_move_resource_bytes_per_second)
migkit_resource_bindinggaugeThe resource that sets a move's rate (deprecated until 1.0: migkit_move_resource_binding)
migkit_worker_memory_bytesgaugeWhat one worker of a move holds for its widest rows
migkit_move_rowsgaugeRows the copy has carried into a table
migkit_move_tablesgaugeTables the copy of a database holds a place for
migkit_move_tables_donegaugeTables the copy of a database finished
migkit_copy_way_rows_per_secondgaugeRows a second the last copy by a way went at, by the way's key
migkit_copy_way_secondsgaugeSeconds the last copy by a way took, by the way's key
migkit_way_infogaugeA way's key, and the words an operator reads for it
migkit_copy_rows_per_secondgaugeRows a second the last copy by a way went at (deprecated until 1.0: migkit_copy_way_rows_per_second)
migkit_copy_secondsgaugeSeconds the last copy by a way took (deprecated until 1.0: migkit_copy_way_seconds)
migkit_check_secondsgaugeSeconds a check of a database took in the last run
migkit_verify_ranges_donegaugeRanges of a table the verify in progress has proved equal
migkit_verify_rows_donegaugeRows in those ranges
migkit_table_rowsgaugeRows a table held on a side at its last digest
migkit_table_samegaugeA 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_secondsgaugeWrite outage the last cutover measured
migkit_cutover_phase_secondsgaugeSeconds a phase of the last cutover took
migkit_cutover_runninggaugeA cutover is under way (1), or not (0)
migkit_two_way_conflicts_totalcounterRows a two-way tail found both sides had changed, by table, kind and what was decided, since its reports began
migkit_two_way_conflictsgaugeRows 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_parkedgaugeRows a two-way conflict set aside until they are decided on both sides
migkit_stream_behind_source_secondsgaugeHow far the hop's change stream's reader is behind the source, by its own account
migkit_stream_events_seen_totalcounterChanges the hop's stream reader has read since it started
migkit_stream_events_seengaugeChanges the stream's reader has read since it started (deprecated until 1.0: migkit_stream_events_seen_total)
migkit_stream_queue_remaininggaugeRoom left in the stream reader's queue
migkit_stream_connectedgaugeThe stream's reader is connected to the source (1)
migkit_stream_snapshot_tables_remaininggaugeTables the stream's first read has still to read
migkit_stream_runninggaugeA part of the change stream is running (1) or not (0)
migkit_collect_age_secondsgaugeSince the snapshot these metrics are read from was taken
migkit_collect_secondsgaugeSeconds the last snapshot took to take
migkit_collect_errors_totalcounterReadings that failed while a snapshot was taken, by what was being read