Why migrations version your database schema in Supabase - Visual Breakdown

Process Flow - Why migrations version your database schema

Start Migration

↓

Check Current Schema Version

↓

Compare with Migration Version

↓

If Newer

→Apply Migration Changes

↓

Update Schema Version

↓

End Migration

↓

If Not Newer

→Skip Migration

↓

End Migration

The migration process checks the current schema version, applies changes only if the migration is newer, then updates the version to keep track.

Execution Sample

Supabase

-- Migration script example
BEGIN;
-- Add new column
ALTER TABLE users ADD COLUMN age INT;
-- Update version
INSERT INTO schema_migrations (version) VALUES ('20240601_add_age');
COMMIT;

This migration adds a new column and records its version to track schema changes.

Process Table

Step	Action	Current Version	Migration Version	Decision	Result
1	Start migration	20240530_initial	20240601_add_age	Check versions	Proceed
2	Compare versions	20240530_initial	20240601_add_age	Migration is newer	Apply changes
3	Apply changes	20240530_initial	20240601_add_age	Add column 'age'	Column added
4	Update version	20240530_initial	20240601_add_age	Record new version	Version updated
5	End migration	20240601_add_age	20240601_add_age	Migration complete	Schema up to date
6	Start migration	20240601_add_age	20240530_initial	Check versions	Skip migration
7	End migration	20240601_add_age	20240530_initial	Migration older or same	No changes applied

💡 Migration stops when the migration version is not newer than the current schema version.

Status Tracker

Variable	Start	After Step 2	After Step 4	Final
Current Schema Version	20240530_initial	20240530_initial	20240601_add_age	20240601_add_age
Migration Version	20240601_add_age	20240601_add_age	20240601_add_age	20240601_add_age
Schema Changes Applied	No	No	Yes	Yes

Key Moments - 2 Insights

Why do migrations check the current schema version before applying changes?

To avoid reapplying the same changes or applying older migrations, ensuring the database schema stays consistent as shown in steps 1 and 2 of the execution table.

What happens if a migration version is older than the current schema version?

The migration is skipped to prevent overwriting newer schema changes, as seen in steps 6 and 7.

Visual Quiz - 3 Questions

Look at the execution table, what is the Current Schema Version after step 4?

A 20240601_add_age

B 20240530_initial

C Not updated yet

D Migration version

💡 Hint

Check the 'Current Schema Version' column at step 4 in the execution table.

At which step does the migration decide to skip applying changes?

A Step 5

B Step 6

C Step 2

D Step 3

💡 Hint

Look for the step where the decision is 'Skip migration' in the execution table.

If the migration version was the same as the current version, what would happen?

A Migration applies changes again

B Migration version updates to a new value

C Migration skips applying changes

D Migration fails with error

💡 Hint

Refer to the logic in the concept flow and steps 6-7 in the execution table.

Concept Snapshot

Migrations track schema changes by versioning.
They check current schema version before applying.
Only newer migrations apply changes.
Version updates prevent repeated or outdated changes.
This keeps database schema consistent and safe.

Full Transcript

Migrations version your database schema to keep track of changes over time. When a migration runs, it first checks the current schema version stored in the database. If the migration's version is newer, it applies the schema changes like adding or modifying tables or columns. After applying, it updates the stored version to mark the schema as up to date. If the migration version is older or the same, it skips applying changes to avoid conflicts or repeated work. This process ensures the database schema evolves safely and consistently as your application grows.