Chuyển đổi JSON thành giải pháp SQLAlchemy!

Nhập JSON và chuyển đổi nó thành giải pháp SQLAlchemy! Hỗ trợ SQLAlchemy 2.0 ORM, Mapped, mapped_column, Flask, FastAPI.
JSON
Kết quả
 

Chuyển đổi JSON thành giải pháp SQLAlchemy!

Chuyển JSON thành model declarative SQLAlchemy 2.0 chạy được ngay: một class Base(DeclarativeBase), type hint Mapped[...] với mapped_column(), cờ nullable, __tablename__ và khóa chính Integer.

Đây là điểm khởi đầu tốt khi backend FastAPI hay Flask phải lưu JSON của request, hoặc dữ liệu tải về từ hệ thống khác, vào một bảng chưa có model.

Cách sử dụng

  1. Dán một object JSON đại diện cho một dòng của bảng. Nếu có dòng chứa giá trị rỗng, hãy dán nhiều dòng dưới dạng mảng để nhận ra nullable=True.
  2. Nhập tên class vào Tên model (mặc định MyModel); __tablename__ là tên đó ở dạng upper snake case.
  3. Lưu output thành models.py. Nếu dự án đã có Base, hãy xóa cái được tạo và import cái của bạn, để mọi model dùng chung một metadata.

Ví dụ

Đầu vào (JSON)
{
  "isbn": "978-0-13-468599-1",
  "title": "The Pragmatic Programmer",
  "pages": 352,
  "rating": 4.7,
  "available": true,
  "published_at": "2019-09-13"
}
Đầu ra (SQLAlchemy 2.0)
from datetime import date

from sqlalchemy import Boolean, Date, Float, Integer, String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class Book(Base):
    __tablename__ = "BOOK"

    id: Mapped[int] = mapped_column(Integer, primary_key=True)
    isbn: Mapped[str] = mapped_column(String(255), nullable=False)
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    pages: Mapped[int] = mapped_column(Integer, nullable=False)
    rating: Mapped[float] = mapped_column(Float, nullable=False)
    available: Mapped[bool] = mapped_column(Boolean, nullable=False)
    published_at: Mapped[date] = mapped_column(Date, nullable=False)

isbn có gạch nối vẫn là String(255), pages thành Integer, rating thành Float, còn published_at, một ngày không có giờ, thành Date với hint date. Mọi giá trị đều có, nên tất cả cột là nullable=False.

Tính năng hỗ trợ

  • Định nghĩa class Base(DeclarativeBase): pass và chỉ import những kiểu SQLAlchemy và tên datetime thực sự được dùng.
  • Ánh xạ kiểu: số nguyên → Integer/int (BigInteger cho giá trị lớn), số thập phân → Float, boolean → Boolean, YYYY-MM-DD → Date/date, ngày giờ → DateTime/datetime, object và mảng → JSON với dict/list.
  • Chuỗi là String(255), hoặc Text khi có giá trị mẫu dài hơn 255 ký tự, nên bảng cũng tạo được trên MySQL.
  • Attribute là snake_case. Khi key JSON khác (publishedAt, home-url), key gốc được truyền làm tên cột: mapped_column("publishedAt", ...). Từ khóa Python và metadata được thêm _ ở cuối.
  • Cột nullable được gắn hint Mapped[str | None] cùng với nullable=True.
  • Khóa chính là Integer, tự tăng được cả trên SQLite; id dạng chuỗi trong JSON thành khóa String(255), và id số nguyên lớn dùng BigInteger().with_variant(Integer, "sqlite").

Trường hợp sử dụng

Model lưu trữ cho endpoint FastAPI

Nếu đã có JSON request mẫu cho schema Pydantic, hãy tạo model SQLAlchemy từ chính JSON đó và viết ngay luồng session.add(Book(**payload)).

Migration Alembic tự sinh

Khi model đã được đăng ký trên Base.metadata, alembic revision --autogenerate tạo migration create_table từ class này.

Lưu ý và giới hạn

  • Hint str | None cần Python 3.10+. Ở phiên bản cũ hơn, hãy viết Optional[str] với from typing import Optional.
  • __tablename__ viết hoa (BOOK). Khi đó PostgreSQL cần đặt nó trong dấu nháy trong raw SQL, nên nhiều dự án đổi thành books.
  • Với Flask-SQLAlchemy, hãy kế thừa db.Model thay vì Base được tạo.
  • Float là số thực dấu phẩy động nhị phân; với giá tiền hãy dùng Numeric(10, 2) cùng Decimal.

Câu hỏi thường gặp

Vì sao id dùng Integer chứ không phải BigInteger?

SQLite chỉ tự tăng cột được khai báo chính xác là INTEGER PRIMARY KEY, nên Integer giữ cho test local và production hoạt động giống nhau. Chỉ khi dữ liệu đã có id vượt 32 bit thì khóa mới chuyển sang BigInteger với variant cho SQLite.

Có thiết lập schema (__table_args__) không?

Không. Bảng được đặt vào schema mặc định của kết nối. Để nhắm tới schema PostgreSQL khác, hãy tự thêm __table_args__ = {"schema": "billing"}.

Có lấy được cú pháp Column() của SQLAlchemy 1.4 không?

Output chỉ theo kiểu 2.0 (Mapped, mapped_column, DeclarativeBase). Với 1.4, hãy dùng declarative_base() và viết lại mỗi dòng thành title = Column(String(255), nullable=False).