20강. 데이터베이스 마이그레이션 개념과 Alembic

?1. 이번 강의에서 해결할 문제

테이블 모델이 바뀔 때 DB 파일을 삭제하면 기존 데이터가 사라집니다. schema 변경을 순서가 있는 코드로 관리합니다.

✓2. 학습 목표

✓이 강의를 마치면

• migration revision과 현재 DB 상태의 관계를 설명합니다.
• Alembic에 SQLAlchemy metadata와 DB URL을 연결합니다.
• autogenerate 결과를 검토한 뒤 upgrade를 적용합니다.

◇3. 핵심 개념

Alembic revision은 schema를 다음 상태로 바꾸는 upgrade와 되돌리는 downgrade 함수입니다. --autogenerate는 metadata와 DB를 비교해 초안을 만들 뿐 완전한 판단을 대신하지 않으므로 파일을 반드시 검토합니다. 앱 시작 시 create_all 대신 배포 전에 alembic upgrade head를 실행합니다.

</>4. 단계별 코드 예시

파일 경로: game-ranking-api/alembic/env.py의 핵심 수정

alembic/env.py

from alembic import context

from app.config import settings
from app.database import Base
import app.models

config = context.config
config.set_main_option("sqlalchemy.url", settings.database_url.replace("%", "%%"))
target_metadata = Base.metadata

파일 경로: game-ranking-api/app/models/record.py에 추가

app/models/record.py

from sqlalchemy import Text

# GameRecord 클래스 안에 추가
note: Mapped[str | None] = mapped_column(Text, nullable=True)

실행 위치: game-ranking-api/

alembic init alembic
alembic revision --autogenerate -m "create users and game records"
alembic upgrade head
alembic current
alembic history
alembic check

app/main.py의 Base.metadata.create_all(...)은 제거합니다.

→5. 코드가 동작하는 이유

target_metadata가 현재 모델 schema를 Alembic에 제공합니다. autogenerate가 DB와 비교해 migration 초안을 만들고 upgrade head가 아직 적용하지 않은 revision을 순서대로 실행합니다. Alembic의 version 테이블이 현재 revision을 기록합니다.

!6. 자주 하는 실수와 해결법

!자주 하는 실수

• 실수: 생성된 migration을 읽지 않고 적용합니다. 해결: 컬럼 삭제, nullable 변경, 데이터 변환을 직접 검토합니다.
• 실수: 모델 import를 빼 target_metadata가 비어 있습니다. 해결: 모든 모델이 등록되는 app.models를 import합니다.
• 실수: 운영 앱 시작마다 migration을 동시에 실행합니다. 해결: 배포 단계에서 단일 작업으로 적용합니다.

✎7. 직접 실습

✎직접 실습

nullable note 컬럼 migration을 생성해 upgrade 내용을 읽고 적용하세요. 테스트 DB에서 downgrade 후 다시 upgrade하며 데이터 보존 여부와 위험한 변경을 기록합니다.

?8. 이해 점검 질문 3개

?이해 점검

1. autogenerate 결과를 수동 검토해야 하는 이유는 무엇인가요?
2. target_metadata는 어디에서 오나요?
3. create_all과 migration은 운영 변경 이력 측면에서 어떻게 다른가요?

■9. 핵심 요약

■핵심 요약

Alembic은 schema 변경을 revision 코드와 적용 순서로 관리합니다. 자동 생성은 초안이며 검토·테스트 후 배포 전에 upgrade합니다.