Alembic

개념

Alembic은 SQLAlchemy용 DB 마이그레이션 도구다. 스키마 변경을 파이썬 파일(리비전)로 남겨서 DB 상태를 버전 관리한다. git이 코드 변경을 추적하듯, Alembic은 DB 스키마 변경 이력을 관리한다.

왜 필요한가

스키마 변경을 수동 SQL로 관리하면 세 가지 문제가 생긴다.

• 팀원 간 DB 상태가 달라짐 — 누구는 컬럼이 있고 누구는 없음
• 롤백이 어려움 — "어제까지 어떤 상태였나"를 되돌리기 힘듦
• 배포 환경과 dev가 어긋남 — 프로덕션과 로컬 스키마 동기화가 수작업

Alembic은 변경을 파일로 커밋해서 DB 상태를 git처럼 관리한다.

기본 명령어

alembic revision --autogenerate -m "설명"  # 변경 감지해서 마이그레이션 파일 생성
alembic upgrade head    # 최신으로 적용
alembic downgrade -1    # 한 단계 롤백
alembic current         # 현재 버전 확인
alembic history         # 전체 이력

마이그레이션 파일 구조

def upgrade():
    op.create_table('user',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('name', sa.String(50)),
    )

def downgrade():
    op.drop_table('user')

• upgrade() — 앞으로 적용
• downgrade() — 되돌리기

두 함수가 대칭이 되어야 롤백이 깔끔하다.

주의할 점

• autogenerate가 전부는 아니다 — 타입 변경, view, 일부 인덱스 변경 등은 감지 못 함. 생성 후 파일을 꼭 확인
• 동시 브랜치 충돌 — 팀원 두 명이 각자 마이그레이션 만들면 head가 둘이 됨 → alembic merge heads로 해결
• DB URL 분리 — 환경변수로 dev/stage/prod를 구분

데이터 마이그레이션도 가능

스키마 변경뿐 아니라 기존 데이터 변환도 같은 파일 안에서 할 수 있다.

def upgrade():
    op.add_column('user', sa.Column('full_name', sa.String()))
    op.execute("UPDATE user SET full_name = first_name || ' ' || last_name")

스키마와 데이터 변환을 한 리비전에 묶으면 "이 버전이면 데이터 모양도 이렇다"가 보장된다.

더 보기

• Frappe-Fixture — Frappe에서는 Alembic 대신 fixture로 데이터 관리 (의도가 다름)