Làm thế nào để tích hợp một SQL database với FastAPI?

Question

Accepted Answer

Khác với Django, FastAPI **không áp đặt quan điểm** về database — bạn chọn thư viện. Lựa chọn phổ biến là **SQLAlchemy** (thường đi cùng **SQLModel**, của tác giả FastAPI, kết hợp SQLAlchemy + Pydantic). Database session được cung cấp qua dependency injection.

## Thiết lập 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):                        # một ORM model (ánh xạ tới một bảng)
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
```

## Cung cấp DB session qua một dependency

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                 # cung cấp session
    finally:
        db.close()               # LUÔN đóng sau request (cleanup)

@app.get("/users/{id}")
def get_user(id: int, db: Session = Depends(get_db)):   # tiêm một session cho mỗi request
    user = db.query(User).filter(User.id == id).first()
    if not user:
        raise HTTPException(404, "Not found")
    return user
```

Pattern dependency `yield` là cách chuẩn để quản lý session: mở một cái cho mỗi request, tiêm nó, và đóng nó sau đó tự động — mỗi endpoint nhận được một session sạch, được đóng đúng cách.

## SQLModel — SQLAlchemy + Pydantic trong một

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

class User(SQLModel, table=True):        # MỘT class = ORM model VÀ Pydantic model
    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()    # query; kết quả cũng là response model hợp lệ
```

SQLModel hợp nhất ORM model và Pydantic model thành một class — giảm trùng lặp giữa schema database và API.

## Migration và lựa chọn async

```text
✓ Migration: dùng Alembic (công cụ migration của SQLAlchemy) cho thay đổi schema
✓ Async: dùng async engine + async session của SQLAlchemy cho endpoint async
  (đừng dùng database driver SYNC bên trong async def — nó chặn event loop)
```

## Tại sao điều này quan trọng

Tích hợp database thiết yếu cho gần như mọi API thực, và vì FastAPI cố ý **không áp đặt quan điểm** về nó (khác với ORM tích hợp của Django), hiểu cách tiếp cận phổ biến là kiến thức thực tiễn quan trọng.

Pattern chuẩn — **SQLAlchemy** (hoặc **SQLModel**, thanh lịch hợp nhất ORM và Pydantic model để giảm trùng lặp) với **session tiêm qua DI** theo pattern `yield` — là thứ gần như mọi app FastAPI dùng để lưu dữ liệu.

Dependency session-cho-mỗi-request (mở trước, đóng sau, tự động) là cách idiomatic, đúng đắn để quản lý kết nối database, và việc SQLModel hợp nhất schema database và API là một tính năng năng suất đáng chú ý từ chính tác giả FastAPI.

Biết cách thiết lập database, cung cấp session qua DI, thực hiện query, và xử lý migration (Alembic) cùng lưu ý async (dùng async driver trong endpoint async, không bao giờ chặn bằng sync) là cần thiết để xây dựng ứng dụng FastAPI hướng dữ liệu — vì FastAPI cho bạn quyền tự do lựa chọn, biết con đường thông thường, đã được kiểm chứng là có giá trị để xây dựng app thực đúng đắn.