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'.

Practice

1. What does the command supabase db rollback do?

easy

A. It creates a new migration file.

B. It undoes the last applied database migration.

C. It applies all pending migrations to the database.

D. It deletes the entire database.

Solution

1. Step 1: Understand the purpose of rollback

   Rollback means undoing changes, so this command reverses migrations already applied.

2. Step 2: Identify the command effect

   supabase db rollback specifically undoes the last migration applied to the database.

3. Final Answer:

   It undoes the last applied database migration. -> Option B

4. Quick Check:

   Rollback = undo last migration [OK]

Hint: Rollback means undo last migration applied [OK]

Common Mistakes:

• Confusing rollback with applying migrations
• Thinking rollback creates new migrations
• Assuming rollback deletes the database

2. Which of the following is the correct syntax to rollback the last 3 migrations using Supabase CLI?

easy

A. supabase db rollback --steps 3

B. supabase db rollback -n 3

C. supabase rollback db 3

D. supabase db undo 3

Solution

1. Step 1: Recall the rollback command syntax

   The Supabase CLI uses --steps to specify how many migrations to rollback.

2. Step 2: Match the correct option

   supabase db rollback --steps 3 uses supabase db rollback --steps 3, which is the correct syntax.

3. Final Answer:

   supabase db rollback --steps 3 -> Option A

4. Quick Check:

   Use --steps to rollback multiple migrations [OK]

Hint: Use --steps to specify rollback count [OK]

Common Mistakes:

• Using incorrect flags like -n instead of --steps
• Wrong command order like 'rollback db'
• Using 'undo' instead of 'rollback'

3. Given the following commands run in order:
supabase db push
supabase db push
supabase db rollback --steps 1
What is the state of migrations after these commands?

medium

A. All migrations are rolled back except the last one.

B. No migrations are applied.

C. Both migrations are still applied.

D. Only the first migration is applied.

Solution

1. Step 1: Apply two migrations

   Running supabase db push twice applies two migrations in order.

2. Step 2: Rollback one migration

   The rollback with --steps 1 undoes the last applied migration, leaving the first migration applied.

3. Final Answer:

   Only the first migration is applied. -> Option D

4. Quick Check:

   Rollback 1 step removes last migration applied [OK]

Hint: Rollback with --steps 1 undoes last migration only [OK]

Common Mistakes:

• Assuming rollback removes all migrations
• Thinking rollback does not affect applied migrations
• Confusing push and rollback order

4. You run supabase db rollback --steps 2 but get an error saying no migrations to rollback. What is the most likely cause?

medium

A. There are fewer than 2 migrations applied to rollback.

B. The migrations folder is missing.

C. The database connection is not configured.

D. Rollback command requires a --force flag.

Solution

1. Step 1: Understand rollback error

   The error indicates no migrations to rollback, meaning none or fewer than requested are applied.

2. Step 2: Identify cause

   If fewer than 2 migrations are applied, trying to rollback 2 steps causes this error.

3. Final Answer:

   There are fewer than 2 migrations applied to rollback. -> Option A

4. Quick Check:

   Rollback steps > applied migrations causes error [OK]

Hint: Check applied migrations count before rollback steps [OK]

Common Mistakes:

• Assuming rollback always works without applied migrations
• Thinking rollback needs --force flag
• Ignoring database connection issues

5. You have applied 5 migrations but want to rollback only the 3rd migration without affecting others. Which approach is best?

hard

A. Delete the 3rd migration file and run supabase db push.

B. Use supabase db rollback --steps 3 to rollback only the 3rd migration.

C. Rollback all migrations from the 3rd onwards, then reapply the ones after it.

D. Directly edit the database to remove changes from the 3rd migration.

Solution

1. Step 1: Understand migration order

   Migrations apply in order; you cannot rollback a middle migration without undoing later ones first.

2. Step 2: Plan rollback and reapply

   Rollback migrations after the 3rd (steps 2), then rollback the 3rd, then reapply the later migrations.

3. Final Answer:

   Rollback all migrations from the 3rd onwards, then reapply the ones after it. -> Option C

4. Quick Check:

   Rollback middle migration requires undoing later ones first [OK]

Hint: Undo later migrations first, then rollback target migration [OK]

Common Mistakes:

• Trying to rollback a single middle migration directly
• Deleting migration files without rollback
• Editing database manually causing inconsistency