Kaip integruoti SQL duomenų bazę su FastAPI?

Question

Accepted Answer

Skirtingai nuo Django, FastAPI **nepriima jokios nuomonės** apie duomenų bazes — jūs pasirenkate biblioteką. Dažniausias pasirinkimas yra **SQLAlchemy** (dažnai su **SQLModel**, kurį sukūrė FastAPI autorius ir kuris sujungia SQLAlchemy + Pydantic). Duomenų bazės sesijos pateikiamos per priklausomybės injekcija.

## SQLAlchemy sąranka

```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)
```

## Duomenų bazės sesijos teikimas per priklausomybę

```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
```

`yield` priklausomybės šablonas yra standartinis būdas valdyti sesijas: atidarykite vieną kiekvieno užklausos metu, injekuokite ją ir automatiškai uždarykite po to — kiekvienas galas punktas gauna švarią, tinkamai uždarytą sesiją.

## SQLModel — SQLAlchemy + Pydantic viename

```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 sujungia ORM modelį ir Pydantic modelį į vieną klasę — sumažindamas pasikartojimą tarp duomenų bazės ir API schemų.

## Migracijos ir asinchroninės parinktys

```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)
```

## Kodėl tai svarbu

Duomenų bazės integracija yra esminė beveik bet kuriai realiai API, ir kadangi FastAPI sąmoningai **nepriima jokios nuomonės** apie tai (skirtingai nuo Django integruoto ORM), supratimas dėl dažniausio metodo yra svarbi praktinė žinios.

Standartinis šablonas — **SQLAlchemy** (arba **SQLModel**, kuris elegantiškai sujungia ORM ir Pydantic modelius, sumažindamas pasikartojimą) su **priklausomybės injekcija injektuotomis serijomis** per `yield` šabloną — yra tas, kurį naudoja beveik kiekviena FastAPI aplikacija duomenims išsaugoti.

Serijų per užklausą priklausomybė (atidaryti prieš, užverti po to, automatiškai) yra idiomatinis, teisingas duomenų bazės jungčių valdymo būdas, o SQLModel suvienijimas duomenų bazės ir API schemų yra pastebima produktyvumo funkcija iš FastAPI paties autoriaus.

Žinojimas, kaip nustatyti duomenų bazę, teikti sesijas per DI, atlikti užklausas ir valdyti migracijas (Alembic) ir asinchroninį įspėjimą (naudojant asinchroninius tvarkytuvus asinchroniniuose galuose, niekada neblokuojant sinchroninius) yra būtinas duomenimis pagrįstų FastAPI aplikacijų kūrimui — kadangi FastAPI suteikia jums laisvę pasirinkti, žinojimas apie įprastą, gerai nužygiąjusią kelią yra vertingas tinkamų aplikacijų kūrimui.