Running migrations locally and remotely in Supabase - Mini Project: Build & Apply

Running migrations locally and remotely

📖 Scenario: You are managing a database for a web application using Supabase. You need to apply database changes called migrations both on your local machine and on the remote Supabase project to keep the database structure consistent.

🎯 Goal: Learn how to create a migration file locally, configure the Supabase project reference, apply the migration locally, and then push the migration to the remote Supabase database.

📋 What You'll Learn

Create a migration file with a specific name

Set the Supabase project reference URL

Apply the migration locally

Push the migration to the remote Supabase project

💡 Why This Matters

🌍 Real World

Database migrations keep your database structure consistent across development and production environments, preventing errors and data loss.

💼 Career

Knowing how to manage migrations is essential for backend developers, DevOps engineers, and cloud architects working with databases and cloud services.

1

Create a migration file locally

Use the Supabase CLI command supabase migration new add_users_table to create a new migration file named add_users_table in your local migrations folder.

Supabase

# Your code here

Hint

This command creates a new migration file with the name add_users_table in your local migrations directory.

2

Configure the Supabase project reference URL

Set the Supabase project reference URL by running supabase link --project-ref your-project-ref where your-project-ref is your actual Supabase project reference string.

Supabase

supabase migration new add_users_table
# Your code here

Hint

This command links your local setup to the remote Supabase project using the project reference.

3

Apply the migration locally

Run supabase db migrate up to apply the migration changes to your local development database.

Supabase

supabase migration new add_users_table
supabase link --project-ref your-project-ref
# Your code here

Hint

This command applies your migration changes to the local database.

4

Push the migration to the remote Supabase project

Run supabase db push to push your local migration changes to the remote Supabase database.

Supabase

supabase migration new add_users_table
supabase link --project-ref your-project-ref
supabase db migrate up
# Your code here

Hint

This command pushes your local migration changes to the remote Supabase project database.

Practice

1. What is the main reason to run database migrations locally before running them remotely?

easy

A. To update the live database directly without testing

B. To test changes safely before applying them to the live database

C. To delete all existing data before migration

D. To backup the remote database automatically

Solution

1. Step 1: Understand migration purpose locally

   Running migrations locally allows you to check if changes work without risk to live data.

2. Step 2: Understand migration purpose remotely

   Running migrations remotely updates the live database after testing is successful.

3. Final Answer:

   To test changes safely before applying them to the live database -> Option B

4. Quick Check:

   Test locally first = Safe migration [OK]

Hint: Always test migrations locally before live update [OK]

Common Mistakes:

• Running migrations directly on live without testing
• Assuming local migrations update remote automatically
• Thinking migrations delete all data by default

2. Which command correctly runs migrations on your local Supabase project?

easy

A. supabase db reset

B. supabase db push

C. supabase db migrate

D. supabase migration run

Solution

1. Step 1: Identify the correct Supabase CLI command

   The command supabase db reset applies all migrations to the local database by resetting it.

2. Step 2: Check other options

   supabase migration run and supabase db migrate are invalid; supabase db push updates the remote database.

3. Final Answer:

   supabase db reset -> Option A

4. Quick Check:

   Local migration command = supabase db reset [OK]

Hint: Use 'supabase db reset' to run and test local migrations [OK]

Common Mistakes:

• Using remote commands like 'supabase db push' for local
• Using incorrect commands like 'supabase migration run'
• Trying to run migrations without Supabase CLI installed

3. Given this sequence of commands, what is the expected result?

supabase db push
supabase db remote commit
supabase db remote apply

medium

A. The commands will cause an error due to invalid syntax

B. Migrations are only applied locally, remote stays unchanged

C. Remote migrations are applied without local testing

D. Migrations are applied locally and then committed and applied remotely

Solution

1. Step 1: Analyze each command

   supabase db push applies local schema changes to remote; supabase db remote commit generates a migration from remote schema differences; supabase db remote apply applies pending migrations on remote.

2. Step 2: Understand the flow

   All commands target the remote database; no local application occurs in this sequence.

3. Final Answer:

   Remote migrations are applied without local testing -> Option C

4. Quick Check:

   db push + remote commit/apply = remote only [OK]

Hint: db push + remote commit/apply affects remote without local changes [OK]

Common Mistakes:

• Thinking 'supabase db push' applies locally
• Expecting local database changes from remote commands
• Believing commands have invalid syntax

4. You ran supabase db reset locally but forgot to run supabase db remote apply. What issue will you face?

medium

A. Local database will reset to remote state

B. Remote database will automatically update

C. Migration files will be deleted

D. Local and remote databases will be out of sync

Solution

1. Step 1: Understand local reset effect

   supabase db reset reapplies all migrations to the local database only.

2. Step 2: Understand remote apply necessity

   Without supabase db remote apply, the remote database remains unchanged, causing out-of-sync databases.

3. Final Answer:

   Local and remote databases will be out of sync -> Option D

4. Quick Check:

   Missing remote apply = databases out of sync [OK]

Hint: Always run remote apply after local reset to sync [OK]

Common Mistakes:

• Assuming remote updates automatically after local reset
• Thinking local reset affects remote database
• Believing migration files get deleted after reset

5. You want to update your live Supabase database with a new table but keep your local database unchanged for now. Which approach is correct?

hard

A. Run supabase db remote apply without running supabase db reset

B. Run supabase db push only

C. Run supabase db push then supabase db remote apply

D. Run supabase db reset locally then supabase db remote apply

Solution

1. Step 1: Understand local vs remote migration commands

   supabase db reset affects local; supabase db remote apply applies pending migrations to remote only.

2. Step 2: Apply only remote changes

   Create/edit migration file for new table, then run supabase db remote apply; skip local commands like supabase db reset.

3. Final Answer:

   Run supabase db remote apply without running supabase db reset -> Option A

4. Quick Check:

   Remote apply only = live DB updated, local unchanged [OK]

Hint: Use remote apply after creating migration file to update only remote [OK]

Common Mistakes:

• Running local reset or push which updates local DB unnecessarily
• Resetting local DB when not needed
• Assuming remote apply requires local reset first