From fc575eacd54b26dee65dea938f4f62ccaadacda2 Mon Sep 17 00:00:00 2001 From: Adegbite Ayoade Date: Thu, 24 Sep 2026 01:27:47 +0100 Subject: [PATCH 1/4] docs: explain which SQLMesh version to use with rollback The rollback docs did not say what to do about the installed version. Rollback restores the state tables from the backups taken by migrate, but leaves the installed package alone, so the newer version refuses to run against the restored state until it is migrated again. Add a rollback section to the migrations guide covering the order of steps, that only the latest migration can be rolled back, and that metadata changes made after the migration are discarded. Link to it from the CLI reference. Closes #4285 Signed-off-by: Adegbite Ayoade --- docs/guides/migrations.md | 22 ++++++++++++++++++++++ docs/reference/cli.md | 2 ++ 2 files changed, 24 insertions(+) diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md index 222bc4cdb8..f5459bfeaf 100644 --- a/docs/guides/migrations.md +++ b/docs/guides/migrations.md @@ -36,3 +36,25 @@ Migrations should ideally run when no one will be running plan/apply. Migrations should not be run in parallel. Due to these constraints, it is better for a person responsible for managing SQLMesh to manually issue migrations. Therefore, it is not recommended to issue migrations from CI/CD pipelines. + +## Rolling back a migration + +Before `sqlmesh migrate` changes the project metadata, it copies each state table to a backup table with a `_backup` suffix. The `sqlmesh rollback` command restores the metadata from those backups, returning it to the format used by the SQLMesh version that was installed before the migration. If a migration fails partway through, SQLMesh rolls it back automatically. + +To undo a migration: + +1. Run `sqlmesh rollback` with the SQLMesh version that performed the migration still installed. The command does not print any output when it succeeds. +2. Reinstall the SQLMesh version the project used before the upgrade, for example by reverting the version change in your requirements file. + +The second step is required. Rolling back does not change the installed version of SQLMesh, and the newer version will refuse to run against the restored metadata until it is migrated again: + +```bash +> sqlmesh plan +Error: SQLMesh (local) is using version '2' which is ahead of '1' (remote). Please run a migration ('sqlmesh migrate' command). +``` + +Keep the following in mind before rolling back: + +- Only the most recent migration can be rolled back. Restoring consumes the backup tables, so running `sqlmesh rollback` a second time fails with `There are no prior migrations to roll back to.` +- The backups are taken at the moment of migration. Any changes made to the project metadata after the migration, such as plans applied with the newer version, are discarded. +- Like `sqlmesh migrate`, rolling back affects all users of the project and should be issued manually by a single user. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f7943e2f71..460b6e520b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -494,6 +494,8 @@ Options: The `rollback` command affects all SQLMesh users. Contact your SQLMesh administrator before running. +Run `rollback` with the SQLMesh version that performed the migration, then reinstall the previous version. See [Rolling back a migration](../guides/migrations.md#rolling-back-a-migration) for details. + ## run ``` From 8355f58d56706a03e896cca9fc6e3d81a817b685 Mon Sep 17 00:00:00 2001 From: Adegbite Ayoade Date: Thu, 24 Sep 2026 02:41:28 +0100 Subject: [PATCH 2/4] docs: drop the note that rollback prints nothing #6088 makes rollback report the versions it moved between, so the note would go stale as soon as that merges. Signed-off-by: Adegbite Ayoade --- docs/guides/migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md index f5459bfeaf..76eed9a33d 100644 --- a/docs/guides/migrations.md +++ b/docs/guides/migrations.md @@ -43,7 +43,7 @@ Before `sqlmesh migrate` changes the project metadata, it copies each state tabl To undo a migration: -1. Run `sqlmesh rollback` with the SQLMesh version that performed the migration still installed. The command does not print any output when it succeeds. +1. Run `sqlmesh rollback` with the SQLMesh version that performed the migration still installed. 2. Reinstall the SQLMesh version the project used before the upgrade, for example by reverting the version change in your requirements file. The second step is required. Rolling back does not change the installed version of SQLMesh, and the newer version will refuse to run against the restored metadata until it is migrated again: From a3ecc6f7661bdd9604e50cb79d3a74e36947c7e1 Mon Sep 17 00:00:00 2001 From: Adegbite Ayoade Date: Tue, 29 Sep 2026 18:08:41 +0100 Subject: [PATCH 3/4] Update docs/guides/migrations.md Co-authored-by: Michael Day Signed-off-by: Adegbite Ayoade --- docs/guides/migrations.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md index 76eed9a33d..f45ace387f 100644 --- a/docs/guides/migrations.md +++ b/docs/guides/migrations.md @@ -58,3 +58,4 @@ Keep the following in mind before rolling back: - Only the most recent migration can be rolled back. Restoring consumes the backup tables, so running `sqlmesh rollback` a second time fails with `There are no prior migrations to roll back to.` - The backups are taken at the moment of migration. Any changes made to the project metadata after the migration, such as plans applied with the newer version, are discarded. - Like `sqlmesh migrate`, rolling back affects all users of the project and should be issued manually by a single user. +- Rollback is not possible if the migration was run with `--skip-backup`. It also does nothing useful after an upgrade that required no migration, such as a patch release, because no new backup was taken. In that case the backup tables, if present, come from an earlier migration. From 35013b77f8b69bbcb353d97dab25bea6e4483e8c Mon Sep 17 00:00:00 2001 From: Adegbite Ayoade Date: Tue, 29 Sep 2026 18:09:36 +0100 Subject: [PATCH 4/4] Update docs/guides/migrations.md Co-authored-by: Michael Day Signed-off-by: Adegbite Ayoade --- docs/guides/migrations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/migrations.md b/docs/guides/migrations.md index f45ace387f..ed8a2d5411 100644 --- a/docs/guides/migrations.md +++ b/docs/guides/migrations.md @@ -39,7 +39,7 @@ Therefore, it is not recommended to issue migrations from CI/CD pipelines. ## Rolling back a migration -Before `sqlmesh migrate` changes the project metadata, it copies each state table to a backup table with a `_backup` suffix. The `sqlmesh rollback` command restores the metadata from those backups, returning it to the format used by the SQLMesh version that was installed before the migration. If a migration fails partway through, SQLMesh rolls it back automatically. +When `sqlmesh migrate` needs to change the project metadata, it first copies each state table to a backup table with a `_backup` suffix, unless `--skip-backup` is passed. The `sqlmesh rollback` command restores the metadata from those backups, returning it to the format used by the SQLMesh version that was installed before the migration. If a migration fails partway through, SQLMesh rolls it back automatically from the same backups. To undo a migration: