Migrations: write and apply

Introduction

Schema trong Supabase (và mọi Postgres nghiêm túc) nên được quản lý bằng migrations: file SQL versioned, áp dụng theo thứ tự. Bài này mô tả cách viết migration, thư mục và quy ước đặt tên, áp dụng qua CLI hoặc Studio, và rollback cơ bản.

Mục tiêu: Biết tạo migration mới, chạy migration lên local/cloud an toàn, và hiểu nguyên tắc “schema versioned, reproducible”.

Features

What is a migration

A migration is a one-off SQL file that typically creates/alters/drops tables, columns, indexes, functions, RLS. Each file has a unique name (often with a timestamp) so application order is defined.
Supabase CLI manages migrations in supabase/migrations/; when you run supabase db push (or supabase migration up), the CLI compares with the supabase_migrations.schema_migrations table and only runs migrations that have not been applied.
Reproducible: From a repo + migrations you can recreate the DB from scratch; dev and CI share the same schema.

Studio vs CLI

Studio: Supabase Dashboard has a SQL Editor; you can run SQL directly. Good for quick experiments; do not use it as the source of truth for production schema (hard to version and reproduce).
CLI: Migrations in the repo, applied by command; you get history and PR review. Use this for all formal schema changes.

Workflow / Process

Tạo file migration: supabase migration new <tên_mô_tả> → tạo file supabase/migrations/<timestamp>_<tên>.sql.
Viết SQL: Chỉ thêm DDL (CREATE/ALTER/DROP) và nếu cần data seed (INSERT) có điều kiện; tránh DML tùy tiện (UPDATE/DELETE) trừ khi đã rõ ảnh hưởng.
Chạy local: supabase start (nếu chưa) rồi supabase db reset hoặc migrations tự áp khi start; hoặc supabase db push sau khi link project.
Chạy lên cloud: supabase link trỏ đúng project (staging/prod) → supabase db push. Nên chạy staging trước, verify rồi mới prod.
Rollback: Supabase không tự rollback; muốn “undo” phải viết migration mới (ALTER/DROP) và push. Giữ migration chỉ thêm/sửa, tránh xóa dữ liệu trong migration trừ khi đã backup.

Quy ước: mỗi migration một mục đích (vd. thêm bảng X, thêm cột Y); tên file mô tả ngắn (vd. add_messages_content_index).

Sample code

Tạo migration mới

supabase migration new add_conversations_archived
# Tạo file: supabase/migrations/20260317120000_add_conversations_archived.sql

Nội dung file migration

-- supabase/migrations/20260317120000_add_conversations_archived.sql
 
ALTER TABLE public.conversations
  ADD COLUMN IF NOT EXISTS archived BOOLEAN NOT NULL DEFAULT false;
 
CREATE INDEX IF NOT EXISTS idx_conversations_archived
  ON public.conversations(archived) WHERE archived = false;

Kiểm tra trạng thái (sau khi link)

supabase migration list
# Liệt kê migration đã áp dụng / chưa áp dụng

Reset DB local (xóa data, chạy lại toàn bộ migrations)

supabase db reset

Áp dụng trong kiến trúc

Schema versioned: Migrations là nguồn sự thật duy nhất cho cấu trúc DB; mọi thay đổi schema đều qua file migration, review trong PR. Tránh sửa tay trên production.
Reproducible: Bất kỳ env nào (dev, CI, staging) đều có thể tạo DB từ trống bằng cách chạy toàn bộ migrations; giảm “chạy được trên máy tôi nhưng không chạy trên máy bạn”.
Tách môi trường: Cùng bộ migrations, khác project (dev/staging/prod); deploy migration lên từng env theo quy trình (staging trước, sau đó prod).

Kết

Migrations cho phép quản lý schema Postgres dưới dạng file versioned, áp dụng nhất quán qua CLI. Bài tiếp sẽ đi Auth: JWT, session và cách verify JWT ở backend.

Bài tiếp: 05 — Auth: JWT và tích hợp backend

Đọc thêm: Supabase — Database Migrations

Migrations: viết và áp dụng