تحويل JSON إلى SQLAlchemy Schema!

أدخل JSON وحوله إلى SQLAlchemy Schema! يدعم SQLAlchemy 2.0 ORM, Mapped, mapped_column, Flask, FastAPI.
JSON
النتيجة
 

تحويل JSON إلى SQLAlchemy Schema!

يحوّل JSON إلى نموذج declarative في SQLAlchemy 2.0 جاهز للتشغيل: صنف Base(DeclarativeBase)، وتلميحات الأنواع Mapped[...] مع mapped_column()، وعلامات nullable، و__tablename__، ومفتاح أساسي من نوع Integer.

نقطة انطلاق جيدة حين يجب على خلفية FastAPI أو Flask تخزين JSON الطلبات، أو بيانات منزَّلة من نظام آخر، في جدول ليس له نموذج بعد.

طريقة الاستخدام

  1. الصق كائن JSON يمثّل صفًا واحدًا من الجدول. إن كانت لبعض الصفوف قيم فارغة، فالصق عدة صفوف كمصفوفة ليُلتقط nullable=True.
  2. أدخل اسم الصنف في اسم النموذج (الافتراضي MyModel)؛ و__tablename__ هو ذلك الاسم بصيغة upper snake case.
  3. احفظ الناتج باسم models.py. إن كان لمشروعك Base أصلًا، فاحذف المولَّد واستورد الخاص بك، لتتشارك كل النماذج 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 مع التلميح date. كل القيم موجودة، لذا كل الأعمدة nullable=False.

الميزات المدعومة

  • يعرّف class Base(DeclarativeBase): pass ولا يستورد إلا أنواع SQLAlchemy وأسماء datetime المستخدمة فعلًا.
  • ربط الأنواع: الأعداد الصحيحة → Integer/int (وBigInteger للقيم الكبيرة)، والعشرية → Float، والمنطقية → Boolean، وYYYY-MM-DD → Date/date، والتاريخ مع الوقت → DateTime/datetime، والكائنات والمصفوفات → JSON مع dict/list.
  • السلاسل النصية String(255)، أو Text حين تكون قيمة في العيّنة أطول من 255 حرفًا، فيمكن إنشاء الجدول على MySQL أيضًا.
  • السمات بصيغة snake_case. وحين يختلف مفتاح JSON (publishedAt، home-url)، يُمرَّر المفتاح الأصلي اسمًا للعمود: mapped_column("publishedAt", ...). والكلمات المحجوزة في Python وmetadata تحصل على _ في آخرها.
  • الأعمدة القابلة لـ null تحمل التلميح Mapped[str | None] إضافة إلى nullable=True.
  • المفتاح الأساسي Integer، الذي يزداد تلقائيًا على SQLite أيضًا؛ والـ id النصي في JSON يصبح مفتاحًا من نوع String(255)، والـ id العددي الكبير يستخدم BigInteger().with_variant(Integer, "sqlite").

حالات الاستخدام

نماذج تخزين لنقاط نهاية FastAPI

إن كان لديك أصلًا JSON الطلب النموذجي لمخطط Pydantic، فولّد نموذج SQLAlchemy من JSON نفسه واكتب تدفق session.add(Book(**payload)) فورًا.

ترحيلات Alembic المولَّدة تلقائيًا

ما إن يُسجَّل النموذج في Base.metadata، حتى يُنتج alembic revision --autogenerate ترحيل create_table من هذا الصنف.

ملاحظات وقيود

  • تلميحات str | None تحتاج إلى Python 3.10+. على الإصدارات الأقدم اكتب Optional[str] مع from typing import Optional.
  • __tablename__ بأحرف كبيرة (BOOK). عندها يحتاج PostgreSQL إلى اقتباسه في SQL الخام، لذا تغيّره مشاريع كثيرة إلى books.
  • مع Flask-SQLAlchemy، ورّث من db.Model بدلًا من Base المولَّد.
  • Float فاصلة عائمة ثنائية؛ استخدم Numeric(10, 2) مع Decimal للأسعار.

الأسئلة الشائعة

لماذا يستخدم id النوع Integer لا BigInteger؟

لا يزيد SQLite تلقائيًا إلا العمود المعرَّف بالضبط كـ INTEGER PRIMARY KEY، لذا يُبقي Integer سلوك الاختبارات المحلية والإنتاج متطابقًا. فقط حين تحوي بياناتك أصلًا معرّفات تتجاوز 32 بت ينتقل المفتاح إلى BigInteger مع بديل لـ SQLite.

هل يوجد إعداد للمخطط (__table_args__)؟

لا. يذهب الجدول إلى المخطط الافتراضي للاتصال. لاستهداف مخطط آخر في 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).