Why migrations version your database schema in Supabase

Introduction

Migrations keep track of changes to your database structure. This helps you update your database safely and in order.

When you add a new table to your database.

When you change a column's type or name.

When you remove a table or column.

When you want to share database changes with your team.

When you deploy updates to your app that need database changes.

Syntax

Supabase

CREATE TABLE table_name (
  column_name data_type constraints
);

-- Migration files are usually named with a version number or timestamp, like:
-- 001_create_users_table.sql
-- 002_add_email_to_users.sql

Each migration file represents one step or change in your database.

Versioning helps apply migrations in the right order.

Examples

This migration creates a new table called users with two columns.

Supabase

-- 001_create_users_table.sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

This migration adds a new column email to the existing users table.

Supabase

-- 002_add_email_to_users.sql
ALTER TABLE users ADD COLUMN email TEXT;

Sample Program

First migration creates a products table. Second migration adds a price column.

Supabase

-- 001_create_products_table.sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

-- 002_add_price_to_products.sql
ALTER TABLE products ADD COLUMN price NUMERIC;

Important Notes

Always test migrations on a copy of your database before applying to production.

Versioning prevents conflicts when multiple people change the database.

Summary

Migrations track changes to your database step-by-step.

Version numbers or timestamps keep migrations in order.

This helps teams update databases safely and consistently.