แปลงโมเดล SQLAlchemyเป็น JSON!

ป้อนโมเดล SQLAlchemyเพื่อสร้าง JSON ตัวอย่าง! รองรับ SQLAlchemy ORM เหมาะสำหรับเอกสาร API และ request body สำหรับทดสอบ (mock request body)
SQLAlchemy
ผลลัพธ์
 

แปลงโมเดล SQLAlchemyเป็น JSON!

วางคลาสโมเดลของ SQLAlchemy แล้วจะได้ JSON ตัวอย่างที่ใช้ชื่อ attribute ของคอลัมน์เป็นคีย์ อ่านได้ทั้ง Mapped[...] คู่กับ mapped_column() แบบ 2.0 Column() แบบ 1.x และ db.Column() ของ Flask-SQLAlchemy และรวมคอลัมน์จาก mixin และคลาส parent ให้ด้วย

โมเดล SQLAlchemy ส่งเข้า json.dumps โดยตรงไม่ได้ แอป FastAPI และ Flask จึงต้องเพิ่ม schema ของ Pydantic หรือ Marshmallow ใช้เครื่องมือนี้วางแผนว่าโมเดลจะเปิดเผยฟิลด์อะไรบ้างก่อนเขียน schema นั้น หรือสร้าง request body สำหรับเทสต์

วิธีใช้

  1. วางไฟล์โมเดลลงในช่อง SQLAlchemy เก็บ Base, mixin และคลาส enum.Enum ไว้ในอินพุตเดียวกัน เพื่อให้คอลัมน์ที่สืบทอดและค่า enum ถูก resolve
  2. นับเป็นโมเดลเฉพาะคลาสที่มี __tablename__ ถ้ามีหลายโมเดล ผลลัพธ์จะใช้ชื่อคลาสเป็นคีย์ เช่น { "User": {...}, "Team": {...} }
  3. คัดลอกผลลัพธ์

ตัวอย่าง

อินพุต (Python · Flask-SQLAlchemy)
class TimestampMixin:
    created_at = db.Column(db.DateTime, default=datetime.utcnow)


class Plan(enum.Enum):
    FREE = "free"
    PRO = "pro"


class Subscription(TimestampMixin, db.Model):
    __tablename__ = "subscriptions"

    id = db.Column(db.Integer, primary_key=True)
    plan = db.Column(db.Enum(Plan), nullable=False)
    seats = db.Column(db.SmallInteger, default=1)
    trial_ends = db.Column(db.Date)
    user_id = db.Column(db.Integer, db.ForeignKey("users.id"))
    user = db.relationship("User", backref="subscriptions")
เอาต์พุต (JSON)
{
  "created_at": "1970-01-01T00:00:00",
  "id": 0,
  "plan": "free",
  "seats": 1,
  "trial_ends": "1970-01-01",
  "user_id": 0
}

created_at จาก TimestampMixin มาก่อนตามลำดับการสืบทอด และ user ถูกตัดออกเพราะ relationship() ไม่ใช่คอลัมน์ db.Enum(Plan) ใช้ค่าแรกของ enum คือ "free" และ db.Date กลายเป็น 1970-01-01 seats แสดง 1 จาก default=1 ขณะที่ created_at ยังเป็นค่าตัวอย่างเพราะ datetime.utcnow เป็นฟังก์ชัน

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

  • type hint ของ Python อย่าง Mapped[int], Mapped[Optional[str]] และ Mapped[str | None] เป็นตัวกำหนดค่า
  • ถ้าไม่มี type hint อาร์กิวเมนต์ไทป์ SQL จะเป็นตัวกำหนด เช่นใน Column(String(50)) หรือ db.Column(db.Numeric)
  • DateTime → 1970-01-01T00:00:00, Date → 1970-01-01, Time → 00:00:00, JSON/JSONB → {}, Uuid → UUID ที่เป็นศูนย์ทั้งหมด
  • ARRAY(String) และ Mapped[list[str]] กลายเป็นอาร์เรย์หนึ่งสมาชิก
  • คลาสที่ extend enum.Enum ซึ่งใช้ผ่าน Enum(Plan) หรือ Mapped[Plan] ให้ค่าของสมาชิกตัวแรก
  • relationship(), column_property() ตัวแปรคลาสธรรมดา และ attribute แบบ dunder อย่าง __table_args__ ถูกตัดออก
  • คอลัมน์จาก mixin และโมเดล parent ถูกวางไว้ก่อนคอลัมน์ของคลาสลูกเอง

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

ร่าง response model ของ Pydantic

ก่อนเขียนคลาส Pydantic สำหรับ response_model ของ FastAPI ให้ตรวจฟิลด์และไทป์ที่โมเดลเปิดเผยเป็น JSON แล้วนำ JSON นั้นไปใส่หน้า JSON to Python เพื่อให้ได้ร่าง Pydantic ด้วย

payload สำหรับเทสต์ API ของ Flask

สร้าง body สำหรับ client.post("/subscriptions", json=...) ที่คีย์ตรงกับ attribute ของโมเดล โดยตัด id ที่ autoincrement และเวลาที่สร้างออกก่อน

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

  • default= ที่เป็น literal ("new", 1, True, None) ถูกใช้เป็นค่าตัวอย่าง ส่วน callable อย่าง datetime.utcnow หรือ dict ไม่ถูกรัน และไม่อ่าน server_default= กับ nullable=
  • ถ้าคอลัมน์มีชื่อในฐานข้อมูลแยกต่างหาก เช่น Column("user_name", String) คีย์ JSON ยังเป็นชื่อ attribute ของ Python
  • ออบเจ็กต์ที่สัมพันธ์กันซึ่งโหลดผ่าน relationship ไม่ถูกรวมไว้ ถ้า response ฝังออบเจ็กต์เหล่านั้น ให้เพิ่มออบเจ็กต์ซ้อนเอง
  • attribute คำนวณอย่าง hybrid_property หรือ @property ไม่อยู่ในผลลัพธ์

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

ทำไม Mapped[Optional[str]] เป็นสตริงว่างแทน null?

Optional หมายความว่ายอมให้เป็น None แต่ตัวอย่างแสดงกรณีที่มีค่า จึงใช้ str ข้างใน ถ้าต้องการกรณีนั้น ให้เปลี่ยนเป็น null ในผลลัพธ์เอง

ทำไม datetime ไม่มี Z หรือ offset?

คอลัมน์ DateTime เป็นแบบ naive โดยค่าเริ่มต้น และ isoformat() พิมพ์ออกมาโดยไม่มี offset ถ้าใช้ DateTime(timezone=True) ตัวอย่างที่มี +00:00 จะใกล้กับสิ่งที่เห็นจริงมากกว่า

แปลงโมเดล Django ได้ไหม?

ไม่ได้ หน้านี้เข้าใจเฉพาะไวยากรณ์ Column, mapped_column และ Mapped ของ SQLAlchemy ฟิลด์ของ Django อย่าง models.CharField ไม่ถูกรู้จัก