كيف تدمج قاعدة بيانات SQL مع FastAPI؟

Question

Accepted Answer

بخلاف Django، FastAPI **غير متحيّز** بشأن قواعد البيانات — أنت تختار المكتبة. الخيار الشائع هو **SQLAlchemy** (غالباً مع **SQLModel**، من مؤلف FastAPI، الذي يجمع بين SQLAlchemy و Pydantic). يتم توفير جلسات قاعدة البيانات عبر حقن التبعيات.

## إعداد 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)
```

## توفير جلسة قاعدة البيانات عبر تبعية

```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` هو الطريقة القياسية لإدارة الجلسات: افتح واحدة لكل طلب، أدخلها، وأغلقها تلقائياً بعد ذلك — كل نقطة نهاية تحصل على جلسة نظيفة وموصدة بشكل صحيح.

## SQLModel — SQLAlchemy و Pydantic في واحد

```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 ونموذج Pydantic في فئة واحدة — مما يقلل التكرار بين قاعدة البيانات وأنماط API.

## الهجرات والخيارات غير المتزامنة

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

## لماذا هذا مهم

دمج قاعدة البيانات ضروري لأي API حقيقي تقريباً، وبما أن FastAPI **غير متحيّز** عنه عن قصد (بخلاف ORM المدمج في Django)، فإن فهم النهج الشائع هو معرفة عملية مهمة.

النمط القياسي — **SQLAlchemy** (أو **SQLModel**، الذي يوحد بأناقة نموذج ORM ونماذج Pydantic لتقليل التكرار) مع **جلسات معاد إدخالها عبر DI** باستخدام نمط `yield` — هو ما تستخدمه تقريباً كل تطبيقات FastAPI لحفظ البيانات.

تبعية جلسة لكل طلب (افتح قبل، أغلق بعد، تلقائياً) هي الطريقة الاصطلاحية والصحيحة لإدارة اتصالات قاعدة البيانات، وتوحيد SQLModel لقاعدة البيانات وأنماط API هي ميزة إنتاجية ملحوظة من مؤلف FastAPI نفسه.

معرفة كيفية إعداد قاعدة البيانات وتوفير الجلسات عبر DI وإجراء الاستعلامات والتعامل مع الهجرات (Alembic) وتحذير غير المتزامن (استخدام برامج التشغيل غير المتزامنة في نقاط النهاية غير المتزامنة، وعدم حظر النقاط المتزامنة أبداً) ضروري لبناء تطبيقات FastAPI موجهة للبيانات — بما أن FastAPI تمنحك الحرية في الاختيار، معرفة المسار التقليدي المشهور قيمة لبناء التطبيقات الحقيقية بشكل صحيح.