FastAPI'yi SQL veritabanı ile nasıl entegre edersiniz?

Question

Accepted Answer

Django'dan farklı olarak, FastAPI veritabanları konusunda **fikir belirtmez** — kütüphaneyi siz seçersiniz. Yaygın seçim **SQLAlchemy** (genellikle **SQLModel** ile, FastAPI'nin yazarı tarafından yapılmış ve SQLAlchemy + Pydantic'i birleştiren) veya başka seçeneklerdir. Veritabanı oturumları bağımlılık enjeksiyonu aracılığıyla sağlanır.

## SQLAlchemy kurulumu

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

## Veritabanı oturumunu bir bağımlılık aracılığıyla sağlama

```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` bağımlılık deseni oturumları yönetmenin standart yoludur: istek başına bir tane açın, enjekte edin ve ardından otomatik olarak kapatın — her uç nokta temiz, düzgün şekilde kapatılmış bir oturum alır.

## SQLModel — SQLAlchemy + Pydantic tek pakette

```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, ORM modelini ve Pydantic modelini tek bir sınıfta birleştirir — veritabanı ve API şemaları arasındaki tekrarlamayı azaltır.

## Migrasyonlar ve async seçenekleri

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

## Neden önemli

Veritabanı entegrasyonu hemen hemen her gerçek API için gereklidir ve FastAPI kasıtlı olarak bunu konusunda **fikir belirtmediği** için (Django'nun yerleşik ORM'sinin aksine), yaygın yaklaşımı anlamak önemli pratik bilgidir.

Standart desen — **SQLAlchemy** (veya **SQLModel**, ORM ve Pydantic modellerini zarif şekilde birleştirerek tekrarlamayı azaltan) **bağımlılık enjeksiyonu aracılığıyla sağlanan oturumlarla** `yield` deseni ile — neredeyse her FastAPI uygulamasının verileri kalıcı kılmak için kullandığı yaklaşımdır.

İstek başına oturum bağımlılığı (önce aç, sonra kapat, otomatik olarak) veritabanı bağlantılarını yönetmenin deyimsel, doğru yoludur ve SQLModel'in veritabanı ve API şemalarını birleştirmesi FastAPI'nin kendi yazarından gelen önemli bir verimlilik özelliğidir.

Veritabanını nasıl kuracağınızı, oturumları DI aracılığıyla nasıl sağlayacağınızı, sorguları nasıl gerçekleştireceğinizi ve migrasyonları (Alembic) ve async uyarısını (async uç noktalarda async sürücüleri kullanın, asla senkron olanları bloke etmeyin) nasıl işleyeceğinizi bilmek, veri odaklı FastAPI uygulamaları oluşturmak için gereklidir — FastAPI size seçme özgürlüğü verdiği için, geleneksel, çokça kullanılan yolu bilmek gerçek uygulamaları doğru şekilde oluşturmak için değerlidir.