Alembic 사용법

Alembic은 데이터베이스 변경 이력을 코드로 관리할 수 있게 해주는 툴입니다.

• DB 스키마(테이블 구조)가 바뀔 때마다,
  직접 SQL 쓰지 않고,
  Python 코드로 변경 내용을 버전 관리합니다.
  마치 Git이 코드 이력을 관리하듯, Alembic은 DB 구조 변경 이력을 관리합니다.

User 테이블에 is_active 컬럼을 추가했을 때:

Alembic으로 이렇게 처리:
alembic revision --autogenerate -m "Add is_active to User"
alembic upgrade head

자동으로 변경사항을 감지해서 마이그레이션 파일 생성
upgrade() / downgrade()로 쉽게 적용/되돌리기 가능

alembic upgrade <revision_id>
alembic upgrade 1234abcd5678
alembic downgrade -1
alembic downgrade <revision_id>

---

1. 설치

pip install alembic

 

2. 초기화 및 설정 파일

# alembic init {directory_name}
alembic init migration

# ./alembic.ini 파일
sqlalchemy.url = {driver}://{root}:{pwd}@{host}:{port}/{database}

# for 'autogenerate' support (migration/env.py 파일)
# 기본값은 None
# SQLAlchemy + Pydantic 하이브리드 조합인 경우 SQLModel.metadata로 수정
target_metadata = SQLModel.metadata

 

3. 모델 선언 (./models.py)

SQLAlchemy + Pydantic 하이브리드 조합

SQLAlchemy의 ORM 기능 + Pydantic의 타입 검증 기능을 한 클래스로 통합함

import uuid

from pydantic import EmailStr
from sqlalchemy.ext.declarative import declarative_base
from sqlmodel import Field, Relationship, SQLModel

# Shared properties
class UserBase(SQLModel):
    email: EmailStr = Field(unique=True, index=True, max_length=255)
    is_active: bool = True
    is_superuser: bool = False
    full_name: str | None = Field(default=None, max_length=255)

# Database model, database table inferred from class name
class User(UserBase, table=True):
    # sqlmodel을 쓰고 있고, table=True가 붙어 있어 SQLAlchemy ORM 테이블로 인식
    # sqlmodel은 SQLAlchemy + Pydantic의 하이브리드 프레임워크입니다.
    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
    hashed_password: str
    items: list["Item"] = Relationship(back_populates="owner", cascade_delete=True)

 

4. 모델 타겟 import (migration/env.py 파일 수정)

model을 import해야 대상 테이블을 생성할 수 있다.

import models  # 모델 import
또는 
from models import User, Item  # 특정 타겟 import

 

5. alembic commit

# 자동 생성
alembic revision --autogenerate -m "first commit"

# 수동 생성
alembic revision -m "first commit"

 

6. DB 적용

#업그레이드
alembic upgrade head


#다운그레이드
alembic downgrade -1