Unaijumuishaje database ya SQL na FastAPI?

Question

Accepted Answer

Tofauti na Django, FastAPI **haina mtazamo maalum** kuhusu databases — wewe huchagua maktaba. Chaguo la kawaida ni **SQLAlchemy** (mara nyingi pamoja na **SQLModel**, iliyotengenezwa na mwandishi wa FastAPI, ambayo huchanganya SQLAlchemy + Pydantic). Database sessions hutolewa kupitia dependency injection.

## Usanidi wa 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)
```

## Kutoa database session kupitia 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
```

Mfumo wa dependency ya `yield` ndiyo njia ya kawaida ya kusimamia sessions: fungua moja kwa kila ombi, iingize, na uifunge baadaye kiotomatiki — kila endpoint hupata session safi, iliyofungwa ipasavyo.

## SQLModel — SQLAlchemy + Pydantic kwa pamoja

```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 huunganisha modeli ya ORM na modeli ya Pydantic kuwa class moja — kupunguza urudufu kati ya database na schemas za API.

## Migrations na chaguo za async

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

## Kwa nini ni muhimu

Ujumuishaji wa database ni wa lazima kwa karibu API yoyote halisi, na kwa kuwa FastAPI kwa makusudi **haina mtazamo maalum** kuihusu (tofauti na ORM iliyojengwa ndani ya Django), kuelewa mbinu ya kawaida ni maarifa muhimu ya vitendo.

Mfumo wa kawaida — **SQLAlchemy** (au **SQLModel**, ambayo huunganisha kwa ustadi modeli za ORM na Pydantic ili kupunguza urudufu) pamoja na **sessions zinazoingizwa kupitia DI** kwa mfumo wa `yield` — ndio ambao karibu kila programu ya FastAPI hutumia kuhifadhi data.

Dependency ya session-kwa-kila-ombi (fungua kabla, funga baada, kiotomatiki) ndiyo njia ya kawaida na sahihi ya kusimamia miunganisho ya database, na muunganisho wa SQLModel wa schemas za database na API ni kipengele cha tija kinachoonekana kutoka kwa mwandishi mwenyewe wa FastAPI.

Kujua jinsi ya kusanidi database, kutoa sessions kupitia DI, kutekeleza queries, na kushughulikia migrations (Alembic) na onyo la async (kutumia drivers za async katika async endpoints, kamwe usizuie zile za sync zinazozuia) ni la lazima kwa kujenga programu za FastAPI zinazoendeshwa na data — kwa kuwa FastAPI hukupa uhuru wa kuchagua, kujua njia ya kawaida iliyopita ni jambo la thamani kwa kujenga programu halisi kwa usahihi.