마이그레이션으로 스키마 진화시키기

스키마 변경도 버전 기록이야

마이그레이션은 개발·스테이징·운영 환경에 같은 순서로 적용되는 재현 가능한 변경이야. 운영 데이터베이스에서 직접 ALTER하고 기록을 남기지 않으면 환경의 역사가 갈라져.

적용된 파일은 고치지 말고 앞으로 수정해

이미 배포한 마이그레이션이 틀렸다면 새 마이그레이션으로 바로잡아. 열 이름 변경이나 삭제는 새 열 추가, 데이터 채우기, 양쪽 쓰기, 읽기 전환, 옛 열 제거를 여러 배포에 나눠.

도구는 하나로 통일해

Alembic(Python·SQLAlchemy), Flyway, goose, Prisma Migrate, Supabase migration, graphile-migrate 가운데 저장소에 맞는 하나를 고르고 적용과 복구를 시험해.

파일과 되돌리기까지 시험해

20260503_add_user_avatar.sql처럼 시각과 목적이 드러나는 이름을 써. 개발 환경에서는 down()도 시험하되, 운영에서는 되돌리기보다 새 마이그레이션으로 바로잡아. 파괴적 변경은 1) 새 열 추가, 2) 데이터 채우기, 3) 양쪽 쓰기, 4) 읽기 전환, 5) 옛 열 제거로 나눠.

Code

Alembic 마이그레이션·python

# alembic/versions/20260503_add_user_avatar.py
def upgrade():
    op.add_column('users', sa.Column('avatar_url', sa.Text(), nullable=True))
    op.execute("UPDATE users SET avatar_url = 'https://...' WHERE id = 1")

def downgrade():
    op.drop_column('users', 'avatar_url')

직접 SQL로 쓰는 마이그레이션·sql

-- migrations/20260503120000_add_user_avatar.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
UPDATE users SET avatar_url = '/avatars/default.png' WHERE avatar_url IS NULL;
ALTER TABLE users ALTER COLUMN avatar_url SET NOT NULL;

Supabase CLI 작업 흐름·bash

supabase migration new add_user_avatar
# 생성된 마이그레이션 파일 편집
supabase db push --include-all

Exercise

샌드박스에서 프로젝트 도구로 작은 스키마 변경 마이그레이션을 만들어 적용해. 첫 변경에 의존하는 두 번째 마이그레이션도 적용한 뒤, 첫 변경의 실수를 되돌리지 않고 바로잡는 세 번째 마이그레이션을 만들어 정방향 수정 방식을 연습해.