JSONをSQLAlchemyスキーマに変換!

JSONを入力し、SQLAlchemyスキーマに変換します!SQLAlchemy 2.0 ORM, Mapped, mapped_column, Flask, FastAPI 対応。
JSON
結果
 

JSONをSQLAlchemyスキーマに変換!

JSON を、そのまま動く SQLAlchemy 2.0 の宣言的モデルに変換します。Base(DeclarativeBase) クラス、mapped_column() 付きの Mapped[...] 型ヒント、nullable フラグ、__tablename__、Integer の主キーを出力します。

FastAPI や Flask のバックエンドで、リクエストの JSON や他システムからダウンロードしたデータを、まだモデルのないテーブルに保存する必要があるときの出発点に向いています。

使い方

  1. テーブル1行分を表す JSON オブジェクトを貼り付けます。値が空の行がある場合は、nullable=True が反映されるよう複数行を配列で貼り付けてください。
  2. モデル名 にクラス名を入力します(既定は MyModel)。__tablename__ はその名前を大文字のスネークケースにしたものです。
  3. 出力を models.py として保存します。プロジェクトにすでに Base があるなら、すべてのモデルが1つの metadata を共有するよう、生成されたものを削除して既存のものを import してください。

例

入力 (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 の名前だけを import します。
  • 型の対応: 整数 → Integer/int(大きな値は BigInteger)、小数 → Float、真偽値 → Boolean、YYYY-MM-DD → Date/date、日時 → DateTime/datetime、オブジェクトと配列 → dict/list 付きの JSON。
  • 文字列は String(255) で、サンプルの値が 255 文字を超える場合は Text にするので、MySQL でもテーブルを作成できます。
  • 属性は snake_case です。JSON のキーが異なる場合(publishedAt、home-url)は、元のキーをカラム名として mapped_column("publishedAt", ...) のように渡します。Python のキーワードと metadata には末尾に _ が付きます。
  • NULL を許可するカラムには、nullable=True に加えて Mapped[str | None] の型ヒントも付きます。
  • 主キーは SQLite でも自動採番される Integer です。JSON の id が文字列なら String(255) のキーに、大きな整数なら BigInteger().with_variant(Integer, "sqlite") になります。

利用シーン

FastAPI エンドポイントの永続化モデル

Pydantic スキーマ用のサンプルリクエスト JSON がすでにあるなら、同じ JSON から SQLAlchemy のモデルを生成して、session.add(Book(**payload)) の流れをすぐに書けます。

Alembic のマイグレーション自動生成

モデルが Base.metadata に登録されれば、alembic revision --autogenerate がこのクラスから create_table のマイグレーションを作ります。

注意点と制限

  • str | None のヒントには Python 3.10 以降が必要です。それより古いバージョンでは、from typing import Optional を付けて Optional[str] と書いてください。
  • __tablename__ は大文字(BOOK)です。PostgreSQL では生の SQL で引用符が必要になるため、多くのプロジェクトでは books に変えています。
  • Flask-SQLAlchemy では、生成された Base ではなく db.Model を継承してください。
  • Float は2進浮動小数点です。価格には Decimal と組み合わせて Numeric(10, 2) を使ってください。

よくある質問

id が BigInteger ではなく Integer なのはなぜですか?

SQLite が自動採番するのは、正確に INTEGER PRIMARY KEY と宣言されたカラムだけなので、Integer にしておけばローカルのテストと本番の挙動がそろいます。データにすでに 32 ビットを超える id がある場合に限り、SQLite 用のバリアント付きの BigInteger に切り替えます。

スキーマ(__table_args__)の設定はありますか?

ありません。テーブルは接続の既定スキーマに作られます。PostgreSQL の別のスキーマを対象にするなら、__table_args__ = {"schema": "billing"} を自分で追加してください。

SQLAlchemy 1.4 の Column() 構文で出力できますか?

出力は 2.0 スタイル(Mapped、mapped_column、DeclarativeBase)だけです。1.4 なら declarative_base() を使い、各行を title = Column(String(255), nullable=False) のように書き直してください。