⭐ Python Developer · Chặng 9Bài 3/6Bài học~90 phút

FastAPI với SQLAlchemy: CRUD, dependency, schema Pydantic

Kết nối FastAPI với SQLite qua SQLAlchemy 2.0: cấu trúc module, dependency cấp Session, schema tạo, đọc, cập nhật và CRUD đầy đủ.

FastAPI với SQLAlchemy: CRUD, dependency, schema Pydantic

Học xong bài này, bạn sẽ

  • Tổ chức dự án API thành các module
  • Dùng dependency injection cấp Session cho từng request
  • Tách schema Pydantic khỏi model CSDL

Nên học trước: FastAPI đầu tiên: endpoint và Pydantic

Nội dung bài viết
  1. 1. Cấu trúc dự án
  2. 2. database.py: engine và dependency
  3. 3. models.py và schemas.py
  4. 4. main.py: các endpoint
  5. 5. Chạy thử
  6. Tóm tắt
  7. Bài tập

API ở bài trước mất sạch dữ liệu mỗi lần khởi động lại. Bài này nối FastAPI với cơ sở dữ liệu qua SQLAlchemy (chặng 8), tổ chức dự án thành các module rõ ràng, và dùng một trong những tính năng mạnh nhất của FastAPI: dependency injection với Depends.

1. Cấu trúc dự án

so-ghi-chu/
├── pyproject.toml
└── app/
    ├── __init__.py      (để trống)
    ├── database.py      ← engine, Base, dependency cấp Session
    ├── models.py        ← bảng CSDL (SQLAlchemy)
    ├── schemas.py       ← dữ liệu vào/ra API (Pydantic)
    └── main.py          ← ứng dụng FastAPI và các endpoint
$ uv add "fastapi[standard]" sqlalchemy
$ uv run fastapi dev app/main.py

Tách model (cấu trúc lưu trữ) khỏi schema (hợp đồng với client) là nguyên tắc quan trọng nhất của bài: bảng CSDL có thể có cột nội bộ (mật khẩu đã băm, cờ đã xóa) mà client không bao giờ được thấy; còn API có thể cần dữ liệu không nằm trong bảng. Đổi cấu trúc CSDL không bắt buộc đổi API, và ngược lại.

2. database.py: engine và dependency

# (minh họa) app/database.py
"""Kết nối CSDL và dependency cấp Session cho từng request."""

import os
from collections.abc import Iterator
from typing import Annotated

from fastapi import Depends
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, Session

DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///./so_ghi_chu.db")
engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})


class Base(DeclarativeBase):
    pass


def get_session() -> Iterator[Session]:
    with Session(engine) as session:
        yield session


SessionDep = Annotated[Session, Depends(get_session)]
  • Chuỗi kết nối đọc từ biến môi trường DATABASE_URL, mặc định là file SQLite. Khi triển khai, chỉ cần đặt biến môi trường để chuyển sang PostgreSQL mà không sửa code.
  • check_same_thread=False: FastAPI chạy endpoint thường (def) trong nhiều luồng, SQLite mặc định chỉ cho dùng kết nối ở luồng đã tạo nó. Tùy chọn này chỉ cần cho SQLite.
  • get_session là một dependency: generator mở Session, yield cho endpoint dùng, rồi đóng khi request xong (cơ chế giống context manager ở chặng 5). Mỗi request một Session riêng.
  • SessionDep = Annotated[Session, Depends(get_session)]: đặt tên cho dependency để dùng lại ngắn gọn ở mọi endpoint.

3. models.py và schemas.py

# (minh họa) app/models.py
"""Model SQLAlchemy: cấu trúc bảng trong CSDL."""

from datetime import datetime

from sqlalchemy import JSON, String, func
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base


class GhiChu(Base):
    __tablename__ = "ghi_chu"

    id: Mapped[int] = mapped_column(primary_key=True)
    tieu_de: Mapped[str] = mapped_column(String(100))
    noi_dung: Mapped[str] = mapped_column(default="")
    the: Mapped[list[str]] = mapped_column(JSON, default=list)
    tao_luc: Mapped[datetime] = mapped_column(server_default=func.now())

Cột the dùng kiểu JSON để lưu list chuỗi (SQLite và PostgreSQL đều hỗ trợ). server_default=func.now() để CSDL tự điền thời điểm tạo. Lưu ý: CURRENT_TIMESTAMP của SQLite là giờ UTC, nên kết quả sẽ chậm 7 tiếng so với giờ Việt Nam. Lưu UTC trong CSDL và chỉ đổi sang giờ địa phương khi hiển thị là cách làm chuẩn.

# (minh họa) app/schemas.py
"""Schema Pydantic: dữ liệu đi vào và đi ra qua API."""

from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field, field_validator


class GhiChuTao(BaseModel):
    tieu_de: str = Field(min_length=1, max_length=100)
    noi_dung: str = ""
    the: list[str] = []


class GhiChuCapNhat(BaseModel):
    """Mọi trường đều tùy chọn: PATCH chỉ gửi trường cần đổi."""

    tieu_de: str | None = Field(default=None, min_length=1, max_length=100)
    noi_dung: str | None = None
    the: list[str] | None = None

    @field_validator("tieu_de", "noi_dung", "the")
    @classmethod
    def khong_nhan_null(cls, gia_tri: object) -> object:
        # Chỉ chạy khi client GỬI trường đó; bỏ trống thì vẫn là None mặc định
        if gia_tri is None:
            raise ValueError("không được gửi null, hãy bỏ trường này nếu không muốn đổi")
        return gia_tri


class GhiChuDoc(GhiChuTao):
    model_config = ConfigDict(from_attributes=True)  # cho phép tạo từ đối tượng SQLAlchemy

    id: int
    tao_luc: datetime
  • Ba schema cho ba mục đích: GhiChuTao (POST, các trường bắt buộc), GhiChuCapNhat (PATCH, mọi trường tùy chọn), GhiChuDoc (dữ liệu trả về, có id, tao_luc).
  • from_attributes=True cho phép GhiChuDoc.model_validate(doi_tuong_sqlalchemy) đọc dữ liệu từ thuộc tính của đối tượng thay vì từ dict.
  • Validator khong_nhan_null giải quyết một lỗi rất hay gặp với PATCH: không có nó, client gửi {"tieu_de": null} vượt qua kiểm tra (vì kiểu là str | None) rồi gây lỗi 500 NOT NULL constraint failed ở CSDL. Validator chỉ chạy khi client thật sự gửi trường đó, nên bỏ trống trường vẫn hợp lệ.

4. main.py: các endpoint

# (minh họa) app/main.py
"""API sổ ghi chú lưu trong SQLite."""

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from typing import Annotated

from fastapi import FastAPI, HTTPException, Query, status
from sqlalchemy import or_, select

from app.database import Base, SessionDep, engine
from app.models import GhiChu
from app.schemas import GhiChuCapNhat, GhiChuDoc, GhiChuTao


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    Base.metadata.create_all(engine)  # chạy một lần khi khởi động
    yield


app = FastAPI(title="Sổ ghi chú", version="0.2.0", lifespan=lifespan)


def lay_hoac_404(session: SessionDep, ghi_chu_id: int) -> GhiChu:
    gc = session.get(GhiChu, ghi_chu_id)
    if gc is None:
        raise HTTPException(status_code=404, detail="Không tìm thấy ghi chú")
    return gc


@app.post("/ghi-chu", status_code=status.HTTP_201_CREATED)
def tao(du_lieu: GhiChuTao, session: SessionDep) -> GhiChuDoc:
    gc = GhiChu(**du_lieu.model_dump())
    session.add(gc)
    session.commit()
    session.refresh(gc)  # nạp id, tao_luc do CSDL sinh
    return GhiChuDoc.model_validate(gc)


@app.get("/ghi-chu")
def liet_ke(
    session: SessionDep,
    tu_khoa: str | None = None,
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
) -> list[GhiChuDoc]:
    q = select(GhiChu).order_by(GhiChu.id)
    if tu_khoa:
        q = q.where(
            or_(GhiChu.tieu_de.ilike(f"%{tu_khoa}%"), GhiChu.noi_dung.ilike(f"%{tu_khoa}%"))
        )
    ket_qua = session.scalars(q.offset(skip).limit(limit))
    return [GhiChuDoc.model_validate(gc) for gc in ket_qua]


@app.get("/ghi-chu/{ghi_chu_id}")
def xem(ghi_chu_id: int, session: SessionDep) -> GhiChuDoc:
    return GhiChuDoc.model_validate(lay_hoac_404(session, ghi_chu_id))


@app.patch("/ghi-chu/{ghi_chu_id}")
def cap_nhat(ghi_chu_id: int, du_lieu: GhiChuCapNhat, session: SessionDep) -> GhiChuDoc:
    gc = lay_hoac_404(session, ghi_chu_id)
    for truong, gia_tri in du_lieu.model_dump(exclude_unset=True).items():
        setattr(gc, truong, gia_tri)
    session.commit()
    session.refresh(gc)
    return GhiChuDoc.model_validate(gc)


@app.delete("/ghi-chu/{ghi_chu_id}", status_code=status.HTTP_204_NO_CONTENT)
def xoa(ghi_chu_id: int, session: SessionDep) -> None:
    session.delete(lay_hoac_404(session, ghi_chu_id))
    session.commit()
  • lifespan: hàm chạy khi ứng dụng khởi động (trước yield) và khi tắt (sau yield). Ở đây tạo bảng nếu chưa có. Dự án thật dùng Alembic thay cho create_all (chặng 8).
  • Endpoint khai báo session: SessionDep: FastAPI tự gọi get_session, truyền Session vào, và đóng sau khi trả response. Hàm endpoint không cần biết Session đến từ đâu, nên khi test có thể thay bằng CSDL khác (bài kiểm thử API).
  • session.refresh(gc) sau commit nạp lại giá trị do CSDL sinh (id, tao_luc).
  • PATCH: model_dump(exclude_unset=True) chỉ lấy những trường client thực sự gửi, rồi gán từng trường vào đối tượng. Không có exclude_unset, mọi trường không gửi sẽ bị ghi đè thành None.
  • Lọc và phân trang giờ do câu SQL đảm nhận (where, offset, limit), không phải nạp hết rồi lọc trong Python. ilike với tham số f"%{tu_khoa}%" vẫn an toàn vì SQLAlchemy truyền giá trị dưới dạng tham số.
  • lay_hoac_404 gom đoạn "tìm, không thấy thì 404" dùng ở ba endpoint.

5. Chạy thử

POST   /ghi-chu    {"tieu_de":"Mua sữa","noi_dung":"2 hộp","the":["việc nhà"]}
201 {"tieu_de":"Mua sữa","noi_dung":"2 hộp","the":["việc nhà"],"id":1,"tao_luc":"2026-10-29T09:39:03"}
PATCH  /ghi-chu/1  {"noi_dung":"3 hộp, loại không đường"}
200 {"tieu_de":"Mua sữa","noi_dung":"3 hộp, loại không đường","the":["việc nhà"],"id":1,"tao_luc":"2026-10-29T09:39:03"}
PATCH  /ghi-chu/1  {"tieu_de":null}
422 {"detail":[{"type":"value_error","loc":["body","tieu_de"],"msg":"Value error, không được gửi null, hãy bỏ trường này nếu không muốn đổi","input":null,"ctx":{"error":{}}}]}
GET    /ghi-chu?tu_khoa=sql
200 [{"tieu_de":"Học SQLAlchemy","noi_dung":"","the":[],"id":2,"tao_luc":"2026-10-29T09:39:03"}]
DELETE /ghi-chu/2
204
GET    /ghi-chu/2
404 {"detail":"Không tìm thấy ghi chú"}

Tắt máy chủ, chạy lại: ghi chú số 1 vẫn còn, vì giờ nó nằm trong file so_ghi_chu.db. Trường noi_dung đã đổi còn tieu_de, the giữ nguyên: PATCH chỉ sửa đúng trường được gửi.

def hay async def?Bài dùng def thường cho endpoint vì SQLAlchemy ở chế độ đồng bộ. FastAPI tự chạy endpoint def trong một nhóm luồng, nên không chặn các request khác. Chỉ dùng async def khi mọi thao tác chờ bên trong đều là await (thư viện bất đồng bộ); gọi hàm đồng bộ chậm trong async def sẽ chặn cả máy chủ. Bạn sẽ học asyncio ở chặng 10.

Tóm tắt

  • Tách database.py, models.py (SQLAlchemy), schemas.py (Pydantic), main.py.
  • Dependency get_session dùng yield; SessionDep = Annotated[Session, Depends(get_session)].
  • Schema riêng cho tạo, cập nhật, đọc; from_attributes=True; chặn null trong PATCH.
  • PATCH với model_dump(exclude_unset=True); lọc, phân trang bằng SQL; lifespan cho việc khởi động.

Bài tập

Bài 1. Dựng lại dự án

Dựng dự án theo cấu trúc ở mục 1, chạy thử đủ kịch bản ở mục 5 qua /docs, khởi động lại máy chủ và xác nhận dữ liệu vẫn còn. Mở file so_ghi_chu.db bằng extension SQLite Viewer của VS Code để xem bảng.

Xem gợi ý

Lỗi ModuleNotFoundError: No module named 'app' nghĩa là bạn đang chạy lệnh từ sai thư mục: chạy uv run fastapi dev app/main.py từ thư mục gốc so-ghi-chu, nơi chứa thư mục app. Thêm echo=True vào create_engine để xem từng câu SQL được sinh ra cho mỗi request.

Bài 2. Thời điểm cập nhật

Thêm cột cap_nhat_luc tự điền khi ghi chú bị sửa (để trống khi mới tạo), trả về trong GhiChuDoc.

Xem đáp án
# (minh họa) thêm vào lớp GhiChu trong app/models.py
    cap_nhat_luc: Mapped[datetime | None] = mapped_column(onupdate=func.now())

# (minh họa) thêm vào lớp GhiChuDoc trong app/schemas.py
    cap_nhat_luc: datetime | None = None
POST  /ghi-chu    → "cap_nhat_luc": null
PATCH /ghi-chu/1  → "cap_nhat_luc": "2026-10-29T09:41:17"

onupdate để SQLAlchemy tự đặt giá trị mỗi khi sinh câu UPDATE cho dòng đó. Vì create_all không thêm cột vào bảng đã có, bạn phải xóa file so_ghi_chu.db để bảng được tạo lại (mất dữ liệu cũ). Đây chính là vấn đề mà Alembic giải quyết khi dự án đã chạy thật.

Nguồn tham khảo: FastAPI: Dependencies; FastAPI: SQL (Relational) Databases; FastAPI: Lifespan Events; FastAPI: Body - Updates; Pydantic: Validators.

Bài tập thực hành

  1. Chuyển API sổ ghi chú sang lưu SQLite bằng SQLAlchemy, dữ liệu còn sau khi khởi động lại.
  2. Thêm endpoint PATCH cập nhật một phần ghi chú, chỉ đổi trường được gửi lên.

Làm xong bài tập mới chuyển sang bài tiếp theo: tự viết code là cách duy nhất để nhớ lâu.

Bài tiếp theo
Ban biên tập HocFree

Chúng tôi viết những bài hướng dẫn dễ hiểu, thực tế để ai cũng có thể tự học lập trình và AI, hoàn toàn miễn phí.