docs: explain which SQLMesh version to use with rollback

[tripleaceme]

Description

Closes #4285.

The docs for sqlmesh rollback did not say what to do about the installed SQLMesh version. Rollback restores the state tables from the _backup tables that migrate creates, but it does not touch the installed package, so the newer version refuses to run against the restored state until it is migrated again.

Changes:

• docs/guides/migrations.md: add a "Rolling back a migration" section. It covers how the backups work, the order of steps (roll back with the version that ran the migration, then reinstall the previous version), and three things to know before rolling back:
  • only the most recent migration can be rolled back, because restoring renames the backup tables back into place
  • metadata changes made after the migration are discarded
  • like migrate, it affects all users of the project
• docs/reference/cli.md: add one line under rollback linking to the new section.

The guide recommends one order to keep things simple. Context.rollback calls _new_state_sync() directly and skips the version check, so in practice the command also works after downgrading first.

Test Plan

Docs only. I tested the behaviour described with two PyPI releases, 0.230.0 and 0.236.2 (the upgrade applies migrations v0101 and v0102), on a sqlmesh init duckdb project planned with 0.230.0:

• migrate with 0.236.2, rollback with 0.236.2, then plan with 0.230.0: works, no changes
• migrate with 0.236.2, then rollback with 0.230.0: works
• migrate and rollback with 0.236.2, then plan with 0.236.2: SQLMesh (local) is using version '0.236.2' which is ahead of '0.230.0' (remote). Please run a migration
• a second rollback: There are no prior migrations to roll back to.
• migrate, plan dev with 0.236.2, rollback: _environments goes from prod, dev back to prod

Checklist

• I have run make style and fixed any issues
• I have added tests for my changes (if applicable) (not applicable, docs only)
• All existing tests pass (make fast-test) (not run, no code changes)
• My commits are signed off (git commit -s) per the DCO

[mday-io]

Thanks! Especially for verifying the behavior against two real releases. The steps and the "latest migration only" behavior match MigratorMixin.rollback.

Please address these two inline comments before merge:

1. Scope the opening sentence to migrations that actually take a backup. The backup is conditional and can be disabled with --skip-backup.
2. Add a bullet stating that rollback is unavailable or misleading when no backup was taken.

Both are small doc-only edits, and I've included ready-to-apply suggestions. Once they're in, this is good to go.

[mday-io]

@tripleaceme looks like the DCO checks failed

[tripleaceme]

Thanks @mday-io — both suggestions are in, and the DCO failure is fixed in b0435f9.

The two doc edits were applied as you wrote them: the opening sentence is now scoped to migrations that actually change something and mentions --skip-backup, and there's a bullet for the two cases where no usable backup exists.

On the DCO failure — worth recording the cause, because it will otherwise keep happening. Four commits on this branch were made through the GitHub web UI: the two "Update docs/guides/migrations.md" commits from applying suggestions in the browser, and two "Update branch" merges. The web UI authors them as "Adegbite Ayoade Abel" (my GitHub display name, not my git config name) with committer: GitHub <[email protected]> and no sign-off.

Which is also why I applied your suggestions locally rather than using the "Apply suggestion" button — that button commits through the same path and would have re-broken the check immediately.

All six commits now carry Signed-off-by: Adegbite Ayoade <[email protected]> with the author matching, and the tree is byte-identical to before the rewrite.