Creating migrations in Supabase - Visual Walkthrough

Process Flow - Creating migrations

Write migration SQL file

↓

Run migration command

↓

Supabase applies changes

↓

Database schema updated

↓

Migration recorded in history

↓

Ready for next migration

This flow shows how you write a migration, run it, and Supabase updates the database and records the change.

Execution Sample

Supabase

supabase migration new add_users_table
-- edit migration SQL file
supabase db push

Create a new migration file, edit it to add a users table, then apply it to update the database.

Process Table

Step	Action	Command/SQL	Result	Notes
1	Create new migration file	supabase migration new add_users_table	New SQL file created	File named with timestamp and description
2	Edit migration file	CREATE TABLE users (id UUID PRIMARY KEY, name TEXT);	SQL ready to run	Defines new users table
3	Run migration	supabase db push	Migration applied	Database schema updated
4	Record migration	Internal Supabase process	Migration logged	Prevents reapplying same migration
5	Verify schema	SELECT * FROM users;	Empty users table exists	Schema change confirmed
6	Exit	No more migrations	Process complete	Ready for next migration

💡 All migration steps completed and database schema updated

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
migration_file	none	created empty file	contains CREATE TABLE SQL	unchanged	unchanged	exists with SQL
database_schema	original schema	unchanged	unchanged	users table added	unchanged	users table present
migration_history	empty	unchanged	unchanged	unchanged	new migration recorded	contains migration record

Key Moments - 3 Insights

Why do we need to edit the migration file after creating it?

Creating the migration file only makes an empty template. You must add SQL commands to define the changes you want, as shown in step 2 of the execution_table.

What happens if you run 'supabase db push' without editing the migration file?

No changes will be applied because the migration file has no SQL commands. The database schema stays the same, as implied between steps 1 and 3.

How does Supabase prevent applying the same migration twice?

Supabase records each applied migration in its history (step 4). This log ensures migrations are only applied once.

Visual Quiz - 3 Questions

Look at the execution_table, what is the result after running 'supabase migration new add_users_table'?

A Database schema updated

B Migration applied

C New SQL file created

D Migration logged

💡 Hint

Check step 1 in the execution_table for the result of the migration new command.

At which step does the database schema get updated with the new users table?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look at the 'Result' column in the execution_table to find when the schema changes.

If you forget to add SQL commands to the migration file, what will happen when you run 'supabase db push'?

A Migration applies but no schema changes

B Migration applies and updates schema

C Migration fails with error

D Migration file is deleted

💡 Hint

Refer to key_moments about running migration without editing the file.

Concept Snapshot

Creating migrations in Supabase:
1. Run 'supabase migration new <name>' to create a new migration file.
2. Edit the file to add SQL commands for schema changes.
3. Run 'supabase db push' to apply changes to the database.
4. Supabase records the migration to avoid duplicates.
This process updates your database schema safely and trackably.

Full Transcript

Creating migrations in Supabase involves making a new migration file with 'supabase migration new', editing it to add SQL commands like creating tables, then running 'supabase db push' to apply these changes to the database. Supabase updates the schema and records the migration to prevent reapplying it. This step-by-step process ensures your database evolves in a controlled way.