FastAPI와 SQL 데이터베이스를 어떻게 통합합니까?

Question

Accepted Answer

Django와 달리 FastAPI는 데이터베이스에 대해 **편향되지 않습니다(unopinionated)**. 라이브러리를 직접 선택합니다. 일반적인 선택은 **SQLAlchemy**(흔히 FastAPI 제작자가 만든 **SQLModel**과 함께 사용, SQLAlchemy + Pydantic을 결합)입니다. 데이터베이스 세션은 dependency injection을 통해 제공됩니다.

## SQLAlchemy 설정

```python
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

engine = create_engine("postgresql://user:pass@localhost/db")
SessionLocal = sessionmaker(bind=engine)
Base = declarative_base()

class User(Base):                        # ORM 모델 (테이블에 매핑됨)
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
```

## 의존성을 통한 DB 세션 제공

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                 # 세션 제공
    finally:
        db.close()               # 요청 후 항상 닫음 (정리)

@app.get("/users/{id}")
def get_user(id: int, db: Session = Depends(get_db)):   # 요청마다 세션 주입
    user = db.query(User).filter(User.id == id).first()
    if not user:
        raise HTTPException(404, "Not found")
    return user
```

`yield` 의존성 패턴은 세션을 관리하는 표준 방법입니다: 요청마다 하나를 열고, 주입하며, 이후에 자동으로 닫습니다. 모든 엔드포인트가 깨끗하고 올바르게 닫히는 세션을 얻습니다.

## SQLModel — SQLAlchemy + Pydantic을 하나로

```python
from sqlmodel import SQLModel, Field, Session, select

class User(SQLModel, table=True):        # 하나의 클래스 = ORM 모델 이자 Pydantic 모델
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str

@app.get("/users")
def list_users(db: Session = Depends(get_session)):
    return db.exec(select(User)).all()    # 쿼리; 결과는 유효한 응답 모델이기도 함
```

SQLModel은 ORM 모델과 Pydantic 모델을 하나의 클래스로 통합하여, 데이터베이스와 API schema 간의 중복을 줄입니다.

## 마이그레이션과 async 옵션

```text
✓ 마이그레이션: 스키마 변경에 Alembic(SQLAlchemy의 마이그레이션 도구) 사용
✓ async: async 엔드포인트에는 SQLAlchemy의 async 엔진 + async 세션 사용
  (async def 안에서 동기 데이터베이스 드라이버를 사용하지 마세요 — 이벤트 루프를 막습니다)
```

## 왜 중요한가

데이터베이스 통합은 거의 모든 실제 API에 필수적이며, FastAPI가 (Django의 내장 ORM과 달리) 이에 대해 의도적으로 **편향되지 않으므로**, 일반적인 접근 방식을 이해하는 것이 중요한 실용 지식입니다.

표준 패턴—**SQLAlchemy**(또는 ORM과 Pydantic 모델을 우아하게 통합해 중복을 줄이는 **SQLModel**)와 `yield` 패턴을 통한 **dependency injection 세션**—은 거의 모든 FastAPI 앱이 데이터를 영속화하는 데 사용하는 방식입니다.

요청별 세션 의존성(이전에 열고, 이후에 자동으로 닫음)은 데이터베이스 연결을 관리하는 관용적이고 올바른 방법이며, SQLModel의 데이터베이스와 API schema 통합은 FastAPI 제작자 본인이 만든 주목할 만한 생산성 기능입니다.

데이터베이스를 설정하고, DI를 통해 세션을 제공하며, 쿼리를 수행하고, 마이그레이션(Alembic)과 async 주의 사항(async 엔드포인트에 async 드라이버 사용, 절대 블로킹 동기 드라이버를 사용하지 않음)을 처리하는 방법을 아는 것은 데이터 기반 FastAPI 애플리케이션을 구축하는 데 필요합니다. FastAPI가 선택의 자유를 주므로, 관습적이고 검증된 길을 아는 것은 실제 앱을 올바르게 구축하는 데 가치가 있습니다.