Как интегрировать 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` — это стандартный способ управления сессиями: открыть одну на запрос, внедрить её и автоматически закрыть после — каждый endpoint получает чистую, правильно закрытую сессию.

## 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-модели, уменьшая дублирование) с **внедряемыми через зависимости сессиями** через паттерн `yield` — это то, что использует практически каждое приложение FastAPI для сохранения данных.

Зависимость сессии-за-запрос (открыть перед, закрыть после, автоматически) — это идиоматичный, правильный способ управления подключениями к базе данных, а объединение SQLModel'ем схем базы данных и API — это заметная функция повышения производительности от автора самого FastAPI.

Умение настроить базу данных, предоставить сессии через DI, выполнять запросы, обрабатывать миграции (Alembic) и асинхронные особенности (использовать асинхронные драйверы в асинхронных endpoints, никогда не блокировать синхронные) необходимо для создания управляемых данными приложений FastAPI — поскольку FastAPI дает вам свободу выбора, знание проверенного и общепринятого пути ценно для правильного создания реальных приложений.