💡 학습 개념 정의

• 핵심 키워드: DB 마이그레이션, DDL, 버전 관리, Infrastructure as Code, supabase db push
• 한 줄 정의: 스키마 변경(DDL)을 콘솔에서 즉석으로 실행하는 대신, 순서가 있는 파일로 남겨 버전 관리하고 재현 가능하게 적용하는 방식.

📝 상세 학습 내용

1. 도입 배경 (Why?)

• DB 스키마를 바꾸는 가장 단순한 방법은 콘솔을 열어 CREATE TABLE, ALTER TABLE, CREATE POLICY 같은 SQL을 직접 실행하는 것이다. 빠르지만 문제가 있다.
• 누가 언제 무엇을 바꿨는지 기록이 남지 않는다. 같은 변경을 다른 환경(로컬·스테이징·운영)에 적용하려면 손으로 다시 쳐야 하고, 빠뜨리면 환경마다 DB가 달라진다.
• 협업 시에도 "내 로컬 DB는 이런데 네 건 다르네" 같은 불일치가 생긴다. 스키마가 코드와 따로 놀기 때문이다.
• 마이그레이션은 이 문제를 "스키마 변경을 파일로 남겨 코드처럼 관리"하는 방식으로 해결한다.

2. 핵심 원리 및 특징 (What?)

• 스키마 변경 SQL을 타임스탬프가 붙은 파일로 저장한다. (예: 20260611041041_grant_anon_access.sql)
• 이 파일들이 한 폴더(supabase/migrations/)에 순서대로 쌓이고, 적용 명령(supabase db push)은 "아직 적용 안 된 파일을 타임스탬프 순으로 DB에 실행"한다.
• 핵심 이점 세 가지:
  • 기록: 변경 이력이 파일로 남아 git으로 버전 관리된다. 언제 무엇을 왜 바꿨는지 추적 가능.
  • 재현: 다른 환경에서 db push 한 번이면 동일한 스키마가 만들어진다. 손으로 다시 칠 필요가 없다.
  • 순서 보장: 타임스탬프 순으로 적용되어 "테이블 생성 → 정책 추가 → 권한 부여" 같은 의존 순서가 항상 지켜진다.
• 본질적으로 "스키마를 코드로 관리(Infrastructure as Code)"하는 것이다. 쿼리를 즉석 실행하는 대신, 코드 리뷰·롤백·재현이 가능한 자산으로 만든다.

3. 실제 활용 예시 (How?)

# 1) 마이그레이션 파일 생성 (빈 SQL 파일이 타임스탬프와 함께 생김)
supabase migration new add_user_table
 
# → supabase/migrations/20260611120000_add_user_table.sql 생성됨

-- 2) 그 파일에 DDL 작성
create table users (
  id uuid primary key default gen_random_uuid(),
  email text not null unique,
  created_at timestamptz not null default now()
);

# 3) 원격 DB에 적용 (아직 적용 안 된 마이그레이션을 순서대로 실행)
supabase db push
 
# 4) 스키마가 바뀌었으니 코드 타입도 동기화
supabase gen types typescript --linked > lib/supabase/database.types.ts

• 흐름을 백엔드 작업으로 번역하면: 파일 작성 = DDL 작성, db push = 쿼리 적용, migrations 폴더 = 변경 이력, gen types = 스키마와 코드 타입 동기화.

🔍 심화 학습 (Deep Dive)

• Q. 그냥 콘솔에서 SQL 실행하는 거랑 결과는 똑같지 않나? A. 한 번 적용한 결과는 같다. 차이는 "그 변경을 다시 만들 수 있는가"다. 콘솔 실행은 일회성이라 다른 환경·다른 개발자에게 재현이 안 되고 기록도 없다. 마이그레이션은 같은 결과를 언제 어디서나 재현하고, 이력을 남긴다.
• Q. Prisma의 migrate랑 뭐가 다른가? A. 발상은 같다. 스키마를 코드로 정의하고 마이그레이션으로 적용한다. 차이는 정의 방식이다. Prisma는 schema.prisma라는 자체 DSL로 스키마를 선언하면 도구가 SQL을 생성하고, Supabase는 SQL을 직접 작성한다. 전자는 추상화가 높고, 후자는 SQL을 그대로 다뤄 제어가 직접적이다.
• Q. 이미 적용한 마이그레이션 파일을 수정하면? A. 하면 안 된다. 이미 DB에 반영된 파일을 고쳐도 db push는 "이미 적용됨"으로 보고 다시 실행하지 않는다. 변경이 필요하면 기존 파일을 건드리지 말고 새 마이그레이션 파일을 추가한다. (예: 권한이 빠졌으면 grant_anon_access 같은 새 파일로 보강) 적용된 이력은 불변으로 두는 게 원칙이다.
• Q. 재적용 시 데이터가 중복되면? A. DDL(테이블·정책)은 보통 멱등하게 관리되지만, 시드 데이터처럼 insert가 든 마이그레이션은 재적용 시 중복 누적될 수 있다. 이럴 땐 db push로 덧붙이지 말고 db reset(전체 재적용)으로 깨끗이 다시 까는 경로를 택한다.

📌 오늘의 핵심 요약

• 마이그레이션은 "스키마 변경(DDL)을 콘솔에서 즉석 실행하는 대신, 순서 있는 파일로 남겨 버전 관리·재현하는 방식"이다.
• 이점은 기록(이력 추적)·재현(환경 일관성)·순서 보장. 본질은 스키마를 코드처럼 다루는 Infrastructure as Code.
• 적용된 마이그레이션은 수정하지 말고 새 파일로 보강한다. 이력을 불변으로 유지하는 게 원칙.