Jak zintegrować bazę danych SQL z FastAPI?

Question

Accepted Answer

W przeciwieństwie do Django, FastAPI jest **niefrasobliwe** w kwestii baz danych — ty wybierasz bibliotekę. Popularnym wyborem jest **SQLAlchemy** (często z **SQLModel**, autorstwa twórcy FastAPI, która łączy SQLAlchemy + Pydantic). Sesje bazy danych są dostarczane poprzez dependency injection.

## Konfiguracja 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):                        # an ORM model (maps to a table)
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String, unique=True)
```

## Dostarczanie sesji bazy danych poprzez dependency

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                 # provide the session
    finally:
        db.close()               # ALWAYS close after the request (cleanup)

@app.get("/users/{id}")
def get_user(id: int, db: Session = Depends(get_db)):   # inject a session per request
    user = db.query(User).filter(User.id == id).first()
    if not user:
        raise HTTPException(404, "Not found")
    return user
```

Wzorzec dependency `yield` to standardowy sposób na zarządzanie sesjami: otwórz jedną na żądanie, wstrzyknij ją i zamknij automatycznie — każdy endpoint otrzymuje czystą, prawidłowo zamkniętą sesję.

## SQLModel — SQLAlchemy + Pydantic w jednym

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

class User(SQLModel, table=True):        # ONE class = ORM model AND 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; results are also valid response models
```

SQLModel ujednolica model ORM i model Pydantic w jedną klasę — zmniejszając duplikację między schematem bazy danych a schematem API.

## Migracje i opcje asynchroniczne

```text
✓ Migrations: use Alembic (SQLAlchemy's migration tool) for schema changes
✓ Async: use SQLAlchemy's async engine + async session for async endpoints
  (don't use a SYNC database driver inside async def — it blocks the event loop)
```

## Dlaczego to ważne

Integracja bazy danych jest niezbędna dla prawie każdego rzeczywistego API, a ponieważ FastAPI jest celowo **niefrasoblliwe** w tej kwestii (w odróżnieniu od wbudowanego ORM Django), zrozumienie powszechnego podejścia jest ważną praktyczną wiedzą.

Standardowy wzorzec — **SQLAlchemy** (lub **SQLModel**, które elegancko ujednolica model ORM i modele Pydantic, aby zmniejszyć duplikację) z **sesjami wstrzykiwanymi poprzez dependency injection** via wzorzec `yield` — to to, co wykorzystuje prawie każda aplikacja FastAPI do utrwalania danych.

Sesja-na-żądanie dependency (otwórz przed, zamknij po, automatycznie) to idiomatyczny, prawidłowy sposób na zarządzanie połączeniami bazy danych, a unifikacja schematów bazy danych i API przez SQLModel to godna uwagi funkcja wydajności od autora samego FastAPI.

Wiedzenie, jak skonfigurować bazę danych, dostarczać sesje poprzez DI, wykonywać zapytania i obsługiwać migracje (Alembic) oraz asynchroniczną zastrzeżenie (używanie asynchronicznych sterowników w asynchronicznych endpointach, nigdy nie blokując synchroniczne) jest konieczne do budowania aplikacji FastAPI opartych na danych — ponieważ FastAPI daje ci swobodę wyboru, znajomość konwencjonalnej, dobrze przetestowanej ścieżki jest cenna dla budowania prawdziwych aplikacji w prawidłowy sposób.