[FastAPI] FastAPI+ Alembic 설정 및 프로세스 정리

2025.03.18 - [🌎 Dev(for macos)/Python] - Alembic 명령어 및 오류 설정확인

 

📌 FastAPI + Alembic 설정 및 프로세스 정리

FastAPI에서 Alembic은 SQLAlchemy ORM의 모델을 기반으로 데이터베이스 마이그레이션을 자동으로 생성하고 적용하는 도구입니다.

공식 API URL

https://alembic.sqlalchemy.org/en/latest/index.html

불러오는 중입니다...

 

핵심 개념:

• SQLAlchemy ORM의 models.py → 테이블 정의
• Alembic의 versions/ 폴더 → 마이그레이션 스크립트 저장
• 자동 마이그레이션 생성 및 적용 (alembic revision --autogenerate)

---

1. Alembic 프로세스 개요

1.1  초기 설정

FastAPI 프로젝트에서 Alembic을 설정하려면 먼저 alembic init 명령어로 마이그레이션 환경을 생성합니다.

alembic init migrations

🔹 파일 및 폴더 구조

📂 my-project/
│── 📂 app/
│   ├── 📂 db/
│   │   ├── base.py  ← (Base 설정)
│   │   ├── session.py  ← (DB 세션 관리)
│   │   ├── models.py  ← (SQLAlchemy 모델 정의)
│── 📂 migrations/
│   ├── 📂 versions/  ← (마이그레이션 스크립트 저장)
│   ├── env.py  ← (Alembic 환경 설정)
│   ├── script.py.mako  ← (자동 생성되는 마이그레이션 템플릿)
│── alembic.ini  ← (Alembic 설정 파일)
│── .env  ← (DATABASE_URL)

 

---

1.2 env.py 설정 (DB 연결)

Alembic이 데이터베이스와 연결될 수 있도록 migrations/env.py에서 DATABASE_URL을 로드해야 합니다.

 migrations/env.py 수정

import os

from dotenv import load_dotenv
from alembic import context
from logging.config import fileConfig

from app.db.session import engine  # ✅ FastAPI의 session.py에서 가져옴
from app.db.base import Base  # SQLAlchemy Base
import app.db.models  # ✅ 모델을 수동으로 import하여 Alembic이 감지하도록 설정

# .env 파일 로드
load_dotenv()

target_metadata = Base.metadata  # Alembic이 인식할 metadata 설정

# 환경 변수에서 DATABASE_URL 가져오기
DATABASE_URL = os.getenv("DATABASE_URL")
if not DATABASE_URL:
    raise ValueError("❌ DATABASE_URL 환경 변수가 설정되지 않았습니다.")

# Alembic 설정 파일 로드
config = context.config
fileConfig(config.config_file_name)

# 무시할 테이블 리스트 정의
EXCLUDE_TABLES = {
    "ignore_table",
    "table_test",
}

def include_object(object, name, type_, reflected, compare_to):
    """Alembic이 특정 테이블을 무시하도록 설정"""
    if type_ == "table" and name in EXCLUDE_TABLES:
        return False  # 해당 테이블 무시
    return True  # 나머지는 처리

def run_migrations_online():
    """마이그레이션을 실행하는 함수 (데이터베이스 연결 포함)"""

    connectable = engine.connect()  # ✅ 연결 유지
    try:
        with engine.connect() as connection:
            context.configure(
                connection=connection,
                target_metadata=Base.metadata,
                include_object=include_object  # 무시할 테이블 적용
            )
            with context.begin_transaction():
                context.run_migrations()
    finally:
        connectable.close()  # ✅ 실행 후 안전하게 닫기

run_migrations_online()

 

핵심 역할

• load_dotenv() → .env에서 DATABASE_URL 로드
• Base.metadata → SQLAlchemy 모델 정보를 가져옴
• context.configure() → Alembic이 데이터베이스 스키마를 추적하도록 설정
• run_migrations_online() → DB 연결 후 마이그레이션 실행

---

1.3 모델 변경 후 마이그레이션 스크립트 생성

이제 **모델(app/models.py)**을 기반으로 마이그레이션 스크립트를 생성합니다.

alembic revision --autogenerate -m "init talbes"

실행하면 migrations/versions/ 폴더에 마이그레이션 파일이 생성됩니다.

📂 migrations/
│── 📂 versions/
│   ├── 20240318123456_init_talbes.py

파일 내부 (versions/*.py)

from alembic import op
import sqlalchemy as sa

# Revision 정보
revision = '20240318123456'
down_revision = None  # 첫 마이그레이션이므로 None
branch_labels = None
depends_on = None

def upgrade():
    """업그레이드 시 실행할 코드"""
    op.create_table(
        'users',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('username', sa.String(length=50), nullable=False),
        sa.Column('email', sa.String(length=100), unique=True, nullable=False),
        sa.Column('created_at', sa.DateTime(), server_default=sa.func.now()),
    )

def downgrade():
    """다운그레이드 시 실행할 코드"""
    op.drop_table('users')

 

✔ Alembic이 SQLAlchemy 모델을 기반으로 자동으로 마이그레이션 파일을 생성합니다.

(직접 수정 가능)

✔ 마이그레이션 스크립트 생성시 테이블이 drop_blabla 로 모든 테이블지우는 로직이 있다면 설정 전부 재확인필요

---

1.4 마이그레이션 적용 (upgrade)

생성된 마이그레이션을 데이터베이스에 적용합니다.

alembic upgrade head

✔ 실행하면 DB에 테이블이 생성됩니다! 🎉

📌 특정 마이그레이션만 적용하고 싶다면?

alembic upgrade <revision_id>

---

2. Alembic 마이그레이션 흐름

단계	명령어	설명
1. Alembic 초기화	alembic init migrations	마이그레이션 환경 설정
2. .env 설정	load_dotenv() 추가	.env에서 DB URL 불러오기
3. 모델 생성	models.py에 SQLAlchemy 모델 추가	테이블 정의
4. 마이그레이션 파일 생성	alembic revision --autogenerate -m "메시지"	모델 기반 스크립트 생성
5. 마이그레이션 적용	alembic upgrade head	데이터베이스에 반영
6. 모델 변경 시 재마이그레이션	alembic revision --autogenerate -m "변경 사항" → alembic upgrade head	필드 추가, 수정
7. 롤백(다운그레이드)	alembic downgrade -1	직전 버전으로 롤백

---

3.  FastAPI + Alembic 프로세스 개념 정리

(1) models.py → SQLAlchemy ORM 모델 생성

(2) env.py → Alembic이 모델을 감지하고, DB와 연결

(3) revision --autogenerate → 변경된 모델을 감지해 마이그레이션 스크립트 생성

(4) upgrade head → 최신 마이그레이션 적용

(5) 모델 변경 시 반복 (revision → upgrade)

---

4. 마이그레이션을 자동화하는 팁

📌 FastAPI 서버 실행 시 자동으로 Alembic 마이그레이션 적용

🔹 main.py 또는 db/init_db.py에 추가:

import subprocess

def run_migrations():
    """FastAPI 실행 시 자동으로 Alembic 적용"""
    try:
        subprocess.run(["alembic", "upgrade", "head"], check=True)
        print("✅ 데이터베이스 최신 상태로 마이그레이션 완료")
    except subprocess.CalledProcessError as e:
        print(f"❌ 마이그레이션 실패: {e}")

run_migrations()

✔ FastAPI 실행할 때마다 자동으로 alembic upgrade head 적용