Rolling back migrations in Supabase - Step-by-Step Execution

Process Flow - Rolling back migrations

Start: Current DB state

↓

Identify last migration applied

↓

Run rollback command

↓

Undo changes from last migration

↓

Update migration history

↓

DB state restored to previous version

↓

End

This flow shows how the system finds the last migration applied, undoes its changes, updates the history, and restores the database to the previous state.

Execution Sample

Supabase

supabase migration rollback
-- Rolls back the last applied migration

This command reverses the last migration applied to the database, restoring its previous state.

Process Table

Step	Action	Migration Target	DB State Before	DB State After	Notes
1	Check applied migrations	migration_003	Version 3 applied	Version 3 applied	Last migration is migration_003
2	Run rollback command	migration_003	Version 3 applied	Rolling back migration_003	Start undoing changes
3	Undo schema changes	migration_003	Version 3 applied	Version 2 applied	Schema reverted to version 2
4	Update migration history	migration_003	Version 3 applied	Version 2 applied	Migration_003 marked as rolled back
5	Confirm rollback	migration_003	Version 2 applied	Version 2 applied	Rollback complete, DB at version 2

💡 Rollback stops after last migration is undone and DB state matches previous version

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Current Migration	migration_003	migration_003	migration_003	migration_003	migration_002
DB Version	3	3	2	2	2
Migration History	[1,2,3]	[1,2,3]	[1,2]	[1,2]	[1,2]

Key Moments - 3 Insights

Why does the rollback only undo the last migration and not all migrations?

Because the rollback command targets the most recent migration applied, as shown in execution_table step 1 and 2. It stops after undoing that migration to avoid losing all changes.

What happens if the rollback command fails during undoing schema changes?

The database state would remain inconsistent. The execution_table step 3 shows the schema reverting; if this fails, the rollback stops and manual fix is needed.

How does the system know which migration to rollback?

It checks the migration history to find the last applied migration, as seen in execution_table step 1 and variable_tracker 'Current Migration'.

Visual Quiz - 3 Questions

Look at the execution_table, what is the DB version after step 3?

A Version 3 applied

B Version 1 applied

C Version 2 applied

D Version 4 applied

💡 Hint

Check the 'DB State After' column in row for step 3 in execution_table

At which step is the migration history updated to reflect the rollback?

A Step 3

B Step 4

C Step 2

D Step 5

💡 Hint

Look at the 'Action' column in execution_table for when migration history changes

If the last migration was migration_004 instead of migration_003, what would change in the variable_tracker?

A Current Migration would start as migration_004

B DB Version would start as 2

C Migration History would be empty

D DB Version would be 5

💡 Hint

Refer to the 'Current Migration' row in variable_tracker and how it tracks the last migration

Concept Snapshot

Rolling back migrations:
- Finds last applied migration
- Runs rollback to undo its changes
- Updates migration history
- Restores DB to previous version
Use 'supabase migration rollback' command
Stops after undoing one migration

Full Transcript

Rolling back migrations means undoing the last set of changes made to the database by the most recent migration. The system first checks which migration was applied last. Then it runs a rollback command that reverses the schema or data changes from that migration. After undoing, it updates the migration history to mark that migration as rolled back. Finally, the database is restored to the previous version state. This process stops after one migration is undone to avoid losing all changes. If rollback fails during undoing, the database may become inconsistent and need manual fixing. The command used is 'supabase migration rollback'.