[Alembic] Alembic

💡 개요

FastAPI + SQLAlchemy 를 사용하고 있는 프로젝트에서 데이터베이스 스키마를 쉽게 관리하기 위해 Alembic 을 사용하려했다.

 

1️⃣ Alembic 설치

pip install alembic

 

2️⃣ Alembic 초기화

alembic init alembic

 

이 명령어를 실행하면 alembic 디렉터리가 생성되며, 기본 설정 파일과 마이그레이션 파일을 저장할 versions/ 폴더가 만들어진다.

 

📁 프로젝트 구조 예시:

my_project/
│── alembic/
│   │── env.py        # 마이그레이션 환경 설정
│   │── script.py.mako  # 마이그레이션 파일 템플릿
│   │── versions/     # 마이그레이션 파일 저장 위치
│── alembic.ini      # Alembic 설정 파일
│── main.py          # FastAPI 애플리케이션
│── models.py        # SQLAlchemy 모델 정의
│── database.py      # 데이터베이스 연결 설정

 

3️⃣ alembic.ini 설정 변경

alembic.ini 파일을 열어서 sqlalchemy.url 값을 데이터베이스 URL 로 설정해준다.

 

ex)

sqlalchemy.url = mysql+pymysql://username:password@localhost:3306/mydatabase
sqlalchemy.url = postgresql://username:password@localhost:5432/mydatabase

 

4️⃣ env.py 수정 (MetaData 설정)

alembic/env.py에서 target_metadata를 SQLAlchemy 모델의 Base.metadata로 변경해준다.

# database.py에서 Base를 가져옵니다.
from database import Base  

config = context.config

if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# SQLAlchemy의 MetaData 연결 (자동 생성 기능을 위해 필요)
target_metadata = Base.metadata

 

5️⃣ 마이그레이션 생성

모델 변경 사항을 반영하기 위해 마이그레이션 파일을 생성한다.

alembic revision --autogenerate -m "Initial migration"

 

이 명령어를 실행하면 alembic/versions/ 디렉터리에 새로운 마이그레이션 파일이 생성된다.

 

6️⃣ 마이그레이션 적용

alembic upgrade head

---

7️⃣ 추가 마이그레이션 (모델 변경 시)

1. 모델 변경

class Todo(Base):
    __tablename__ = "todo"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(100), nullable=False)
    user_id = Column(Integer, ForeignKey("user.id"))  # 새로운 컬럼 추가

 

2. 새 마이그레이션 생성

alembic revision --autogenerate -m "Add user_id to todo"

 

3. 마이그레이션 적용

alembic upgrade head

 

8️⃣ 마이그레이션 롤백 (되돌리기)

만약 최신 마이그레이션을 되돌리고 싶다면:

alembic downgrade -1

 

특정 버전으로 되돌리려면:

alembic downgrade <revision_id>

(alembic history를 실행하면 revision ID를 확인할 수 있음)