แปลง JSON เป็น SQLAlchemy แผน!

ป้อน JSON และแปลงเป็น SQLAlchemy แผน! รองรับ SQLAlchemy 2.0 ORM, Mapped, mapped_column, Flask, FastAPI
JSON
ผลลัพธ์
 

แปลง JSON เป็น SQLAlchemy แผน!

แปลง JSON เป็นโมเดลแบบ declarative ของ SQLAlchemy 2.0 ที่พร้อมรัน: คลาส Base(DeclarativeBase) type hint Mapped[...] พร้อม mapped_column() แฟล็ก nullable __tablename__ และ primary key แบบ Integer

เป็นจุดเริ่มต้นที่ดีเมื่อ backend FastAPI หรือ Flask ต้องเก็บ JSON ของ request หรือข้อมูลที่ดาวน์โหลดจากระบบอื่นลงตารางที่ยังไม่มีโมเดล

วิธีใช้

  1. วางออบเจ็กต์ JSON ที่แทนหนึ่งแถวของตาราง ถ้าบางแถวมีค่าว่าง ให้วางหลายแถวเป็นอาร์เรย์เพื่อให้ได้ nullable=True
  2. ใส่ชื่อคลาสใน ชื่อโมเดล (ค่าเริ่มต้น MyModel) __tablename__ คือชื่อนั้นในรูป upper snake case
  3. บันทึกผลลัพธ์เป็น models.py ถ้าโปรเจกต์มี Base อยู่แล้ว ให้ลบตัวที่สร้างขึ้นแล้ว import ของคุณ เพื่อให้ทุกโมเดลใช้ metadata เดียวกัน

ตัวอย่าง

อินพุต (JSON)
{
  "isbn": "978-0-13-468599-1",
  "title": "The Pragmatic Programmer",
  "pages": 352,
  "rating": 4.7,
  "available": true,
  "published_at": "2019-09-13"
}
เอาต์พุต (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 ที่มีขีดกลางยังเป็น String(255) pages เป็น Integer rating เป็น Float และ published_at ซึ่งเป็นวันที่ไม่มีเวลาเป็น Date พร้อม hint date ทุกค่ามีข้อมูลครบ ทุกคอลัมน์จึงเป็น nullable=False

ฟีเจอร์ที่รองรับ

  • นิยาม class Base(DeclarativeBase): pass และ import เฉพาะไทป์ของ SQLAlchemy และชื่อจาก datetime ที่ใช้จริง
  • การจับคู่ไทป์: จำนวนเต็ม → Integer/int (BigInteger สำหรับค่าใหญ่), ทศนิยม → Float, บูลีน → Boolean, YYYY-MM-DD → Date/date, วันเวลา → DateTime/datetime, ออบเจ็กต์และอาร์เรย์ → JSON พร้อม dict/list
  • สตริงเป็น String(255) หรือ Text เมื่อค่าตัวอย่างยาวเกิน 255 ตัวอักษร ตารางจึงสร้างบน MySQL ได้ด้วย
  • attribute เป็น snake_case เมื่อคีย์ JSON ต่างไป (publishedAt, home-url) คีย์เดิมจะถูกส่งเป็นชื่อคอลัมน์: mapped_column("publishedAt", ...) คำสงวนของ Python และ metadata ได้ _ ต่อท้าย
  • คอลัมน์ที่เป็น null ได้มี hint Mapped[str | None] นอกเหนือจาก nullable=True
  • primary key เป็น Integer ซึ่ง autoincrement บน SQLite ได้ด้วย id ที่เป็นสตริงใน JSON จะเป็นคีย์ String(255) และ id จำนวนเต็มขนาดใหญ่ใช้ BigInteger().with_variant(Integer, "sqlite")

กรณีการใช้งาน

โมเดลสำหรับบันทึกข้อมูลของ endpoint FastAPI

ถ้ามี JSON ตัวอย่างของ request สำหรับ schema ของ Pydantic อยู่แล้ว ให้สร้างโมเดล SQLAlchemy จาก JSON เดียวกัน แล้วเขียน flow session.add(Book(**payload)) ได้ทันที

migration ของ Alembic ที่สร้างอัตโนมัติ

เมื่อโมเดลลงทะเบียนกับ Base.metadata แล้ว alembic revision --autogenerate จะสร้าง migration create_table จากคลาสนี้

ข้อควรระวังและข้อจำกัด

  • hint str | None ต้องใช้ Python 3.10+ ถ้าเวอร์ชันเก่ากว่า ให้เขียน Optional[str] พร้อม from typing import Optional
  • __tablename__ เป็นตัวพิมพ์ใหญ่ (BOOK) บน PostgreSQL ต้องใส่เครื่องหมายคำพูดใน SQL ดิบ หลายโปรเจกต์จึงเปลี่ยนเป็น books
  • ถ้าใช้ Flask-SQLAlchemy ให้สืบทอดจาก db.Model แทน Base ที่สร้างขึ้น
  • Float เป็น floating point แบบไบนารี สำหรับราคาให้ใช้ Numeric(10, 2) คู่กับ Decimal

คำถามที่พบบ่อย

ทำไม id ใช้ Integer ไม่ใช่ BigInteger?

SQLite จะ autoincrement เฉพาะคอลัมน์ที่ประกาศเป็น INTEGER PRIMARY KEY ตรงตัว Integer จึงทำให้เทสต์บนเครื่องกับ production ทำงานเหมือนกัน คีย์จะเปลี่ยนเป็น BigInteger พร้อม variant ของ SQLite ก็ต่อเมื่อข้อมูลมี id ที่เกิน 32 บิตอยู่แล้วเท่านั้น

มีการตั้งค่า schema (__table_args__) ไหม?

ไม่มี ตารางจะอยู่ใน schema ค่าเริ่มต้นของการเชื่อมต่อ ถ้าต้องการใช้ schema อื่นของ PostgreSQL ให้เพิ่ม __table_args__ = {"schema": "billing"} เอง

ขอเป็นไวยากรณ์ Column() ของ SQLAlchemy 1.4 ได้ไหม?

ผลลัพธ์เป็นสไตล์ 2.0 เท่านั้น (Mapped, mapped_column, DeclarativeBase) สำหรับ 1.4 ให้ใช้ declarative_base() แล้วเขียนแต่ละบรรทัดใหม่เป็น title = Column(String(255), nullable=False)