upgrade-preflight

Run `lightdash upgrade-check --from <current> --to <target> --json` first to verify the version span, then run `pnpm -F backend migrate-production preflight --json` inside the image against the live database. Gate on the `safe` field and the `decision` field respectively.

upgrade-check answers whether a version span is safe in principle by reading the public release-safety index, with no database needed. migrate preflight answers whether this specific database will take the upgrade right now, checking locks, transactions, disk, and PostgreSQL version.

Not necessarily. Exit codes are binary: 0 for success, 1 for everything else including unsafe verdicts, aborted decisions, and errors like an unreachable index. Always parse the JSON payload on stdout to find the actual reason.

Severity is the class of a check, not its result. A check like postgres-version is always red-class, so a healthy server reports severity red with outcome pass, rendered as [RED PASS]. Only severity red paired with outcome fail counts toward summary.red and an abort.

It means the image has no baked release-safety artifact, so required-stop verification was skipped. The held-locks, long-transactions, and disk-headroom checks then pass vacuously because they have no table list to examine, so describe them as unverified rather than clear.

Run `migrate status --json` to see the state: migrating with a recent heartbeat means wait, stale recovers on its own, and parked means the migrator stopped deliberately and needs an operator decision. The upgrade runbook's recovery section covers unlock and retry procedures.