# SQLAlchemy 2.0のMappedとmapped_columnによるモデルの型付け

## Mappedとmapped_columnとは

SQLAlchemy 2.0の`Mapped`とは、ORMのモデルの属性の型を型チェッカーに通知するためのジェネリッククラスである。
`Mapped[str]`の注釈は、インスタンスの属性の型が`str`であることを意味する。
`mapped_column()`は、その属性に対応するテーブルの列を定義する関数で、列の型とNOT NULLの有無を`Mapped[...]`の注釈から決定する。

- mypyプラグインなしの環境では、1.x形式の`name = Column(String)`の属性の型は`Column[str]`と判定され、`str`の値の代入が型エラーになる
  - 1.xではSQLAlchemyのmypyプラグインがこの型を補正していた
  - プラグインは2.0で非推奨になり、pyrightには対応していない
- `name: Mapped[str] = mapped_column()`の形式では、属性の型と異なる値の代入を実行前の型チェックで検出できる
  - `user.name`の型は`str`で、`int`の代入は型エラーになる
  - `select(User.id, User.name)`の結果の行の型も`Row[tuple[int, str]]`と推論される
  - `Mapped[str]`の属性への`None`の代入も、実行前の型チェックで検出できる
  - クラスから参照する`User.name`は、検索条件の構築用の列の式になる
- 列のNULLとNOT NULLは、注釈の`str | None`の有無と`nullable`の指定に依存する
  - 主キー以外で`nullable`の指定がない列の例では、`str | None`の列はNULLを許容し、`str`の列はNOT NULLになる
  - `nullable`を指定した列のNULLの可否は、注釈ではなくその指定に従う
  - `nullable`が無指定の1.x形式の`Column(String)`を`Mapped[str]`へ移行すると、モデルの列の定義はNULL許容からNOT NULLになる
- 型チェッカーで検出されない誤りもある
  - `Mapped[...]`と`mapped_column()`の列の型の不一致は検出されない
  - 標準のコンストラクタでは引数名の誤りは検出されない

## 前提となるSQLAlchemyのモデルの用語

### 宣言的マッピング

宣言的マッピングは`DeclarativeBase`を継承したクラスの属性の定義から、テーブルの定義と、クラスとテーブルの対応を生成する方式である。
以降のコード例の`Base`はこの方式の基底クラスで、`User`と`Address`は説明のために定義したモデルである。

### 記述子

記述子（descriptor）は、`__get__`や`__set__`を定義したクラスのインスタンスで、クラスの属性に設定すると、属性の参照と代入の処理を置換する。
SQLAlchemyのモデルの属性は記述子で、クラスからの参照の結果は列の式（`User.name == "Ada"`のような条件の構築用のオブジェクト）、インスタンスからの参照の結果は列の値である。
`Mapped`は、この2種類の型を型チェッカーに通知するための型である。

## Columnで定義した属性の型はColumnになる

以降のコード例は1つのファイルの抜粋で、2つ目以降のコード例では最初の例のimportと`Base`の定義を再利用する。
DBへの保存を伴う例は`create_engine("sqlite://")`と`Base.metadata.create_all(engine)`でテーブルを作成してから実行する。

型情報がSQLAlchemyの同梱分に限られる環境で1.x形式の`Column`でモデルを定義すると、型チェッカーはインスタンスの属性の型を`Column[str]`と判定する。

```python
from typing import reveal_type

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    name = Column(String)


user = User(name="Ada")
reveal_type(user.name)
# mypy: Revealed type is "sqlalchemy.sql.schema.Column[str]"
# pyright: Type of "user.name" is "Column[str]"
user.name = "Grace"
# mypy
# error: Incompatible types in assignment (expression has type "str", variable has type "Column[str]")  [assignment]
```

実行時の`user.name`の値は文字列の`"Ada"`であり、代入も問題なく動作する。
型チェッカーの判定と実行時の値が一致しないのは、`Column(String)`の戻り値の型が`Column[str]`で、型チェッカーはクラスの属性への代入をそのままインスタンスの属性の型と判定するからである。
1.4まではこの型の補正はSQLAlchemyの [mypyプラグイン](https://docs.sqlalchemy.org/en/20/orm/extensions/mypy.html) の役割だった。
プラグインは2.0で非推奨になり、2.1で削除される予定で、mypy 1.11以降では正常に動作しない可能性がある。
pyrightはmypyのプラグインに非対応なので、1.x形式の`name`に対するpyrightの判定は`Column[str]`のままである。

## Mappedの注釈でインスタンスとクラスの型を区別する

以降の例の前提は型情報がSQLAlchemy 2.0の同梱分に限られる環境である。
2.0の型付けが機能するには、`sqlalchemy-stubs`や`sqlalchemy2-stubs`などのスタブのパッケージの [削除が必要である](https://docs.sqlalchemy.org/en/20/changelog/whatsnew_20.html#the-catch-all-stubs-must-be-uninstalled)。
[型チェッカーの解決順](https://typing.python.org/en/latest/spec/distributing.html#import-resolution-ordering) では、スタブのパッケージがパッケージ同梱の型情報より優先される。
1.x向けのスタブがインストールされたままなら、2.0の`Mapped`の定義は型チェッカーの参照の対象外になる。
`pip show sqlalchemy-stubs sqlalchemy2-stubs`で有無を確認し、mypyの設定の`plugins`から`sqlalchemy.ext.mypy.plugin`も削除する。

2.0の形式では属性の注釈に`Mapped[...]`を指定し、値に`mapped_column()`を設定する。

```python
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column


class Base(DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))


user = User(name="Ada")
reveal_type(user.name)
# mypy: Revealed type is "str"
reveal_type(User.name)
# mypy: Revealed type is "sqlalchemy.orm.attributes.InstrumentedAttribute[str]"
user.name = 1
# mypy
# error: Incompatible types in assignment (expression has type "int", variable has type "SQLCoreOperations[str] | str")  [assignment]
```

インスタンスからの参照は`str`、クラスからの参照は`InstrumentedAttribute[str]`になり、pyrightの表示も一致する。
`int`の代入は、mypyとpyrightの両方がエラーにする。
1.x形式でエラーになった文字列の代入はエラーにならず、型と異なる値の代入だけが型チェッカーに検出される。
この区別は`Mapped`の型スタブの`__get__`のオーバーロードで実現されている。

```python
# sqlalchemy/orm/base.py の型スタブからの抜粋
class Mapped(...):
    @overload
    def __get__(self, instance: None, owner: Any) -> InstrumentedAttribute[_T_co]: ...
    @overload
    def __get__(self, instance: object, owner: Any) -> _T_co: ...
    def __set__(self, instance: Any, value: SQLCoreOperations[_T_co] | _T_co) -> None: ...
```

インスタンスが`None`の呼び出し、つまりクラスからの参照には`InstrumentedAttribute`、インスタンスからの参照には型引数の`_T_co`が対応する。
SQLAlchemyのコードを解釈する専用の処理は不要で、判定は通常の記述子の型の規則に従うので、mypyとpyrightの結果が一致する。
`mapped_column()`の戻り値の型は`MappedColumn[Any]`で、注釈の`Mapped[str]`への代入で型エラーにならない。

### 移行の途中でMappedの注釈にColumnを設定した場合

`Mapped[int]`の注釈の値に`mapped_column()`ではなく`Column`を設定すると、型チェッカーはエラーにする。

```python
class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = Column(Integer, primary_key=True)
# mypy
# error: Incompatible types in assignment (expression has type "Column[int]", variable has type "Mapped[int]")  [assignment]
```

`Mapped`の注釈に`Column`を設定しても、実行時には正常に動作する。
この型エラーは1.x形式からの移行時に注釈を先行して追加すると発生する。
値を`mapped_column()`に置換すると、`Column`の引数をそのまま指定できる。

### select()の結果も型が推論される

クラスの属性の型が列の型引数を保持するので、`select()`に指定した列から結果の行の型が推論される。

```python
from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session

engine = create_engine("sqlite://")
Base.metadata.create_all(engine)
with Session(engine) as session:
    session.add(User(id=1, name="Ada"))
    session.commit()
    statement = select(User.id, User.name)
    # mypy: Revealed type is "sqlalchemy.sql.selectable.Select[tuple[int, str]]"
    rows = session.execute(statement).all()
    # mypy: Revealed type is "typing.Sequence[sqlalchemy.engine.row.Row[tuple[int, str]]]"
    users = session.scalars(select(User)).all()
    # mypy: Revealed type is "typing.Sequence[User]"
    print(rows[0].name.upper())  # ADA
```


## 注釈のOptionalと列のNULLの対応

`mapped_column()`は、注釈の`Mapped[...]`から列の型とNULLの可否を決定する。

### 注釈からのNULLの可否の推論

`nullable`と`primary_key`の指定がない列のNULLの可否は、[注釈の`Optional[...]`の有無に依存する](https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html#orm-declarative-mapped-column-nullability)。
`str | None`は`Optional[str]`と同等である。
`str | None`の記法はPython 3.10以降で、それより前のバージョンの記法は`Optional[str]`である。
`mapped_column()`の値の設定自体も省略でき、値のない`name: Mapped[str]`の注釈も列になる。

```python
from sqlalchemy.schema import CreateTable


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    nickname: Mapped[str | None]


print(CreateTable(Base.metadata.tables["users"]).compile(engine))
```

```text
CREATE TABLE users (
	id INTEGER NOT NULL, 
	name VARCHAR NOT NULL, 
	nickname VARCHAR, 
	PRIMARY KEY (id)
)
```

`Mapped[str]`の`name`はNOT NULLの列である。
`Mapped[str | None]`の`nickname`はNULLを許容する。

### 1.x形式からの移行時のNULLの変化

1.x形式の`name = Column(String)`はNULLを許容するので、`Mapped[str]`への書き換えはモデルの列の定義の変更になる。
既存のテーブルの列はNULLを許容したままで、`create_all()`も既存のテーブルを変更しない。
NULLを許容する既存の列の注釈は`Mapped[str | None]`にし、NOT NULLへの変更はマイグレーションとして別に行う。
`name`への`None`の代入はmypyとpyrightが型エラーにし、型チェックを無視して実行すると、`commit()`の時点で`IntegrityError: NOT NULL constraint failed: users.name`になる。

### nullableの明示による上書き

`mapped_column(nullable=...)`の明示は、注釈より優先される。

```python
class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(nullable=True)  # VARCHAR（NULLを許容）
    nickname: Mapped[str | None] = mapped_column(nullable=False)  # VARCHAR NOT NULL
```

注釈と異なる指定の [用途の例](https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html#orm-declarative-mapped-column-nullability) は、オブジェクトの作成中に限りPython上で`None`を許容し、データベースの列はNOT NULLにする場合である。
逆に`Mapped[str]`の列を`nullable=True`にすると、データベースの値が`NULL`の行でも、型チェッカーの判定は`str`のままである。

## 注釈の型と列の型の対応

列の型を`mapped_column()`に指定しない場合、列の型は注釈の型から推論される。
標準の対応は次のとおりである。

| 注釈の型 | 列の型 |
|---|---|
| `int` | `Integer` |
| `str` | `String` |
| `float` | `Float` |
| `bool` | `Boolean` |
| `datetime.datetime` | `DateTime` |
| `decimal.Decimal` | `Numeric` |
| `uuid.UUID` | `Uuid` |
| `enum.Enum`のサブクラス | `Enum` |

`list[int]`のように標準の対応にない注釈は、対応から列の型を決定できないので、対応を追加していなければクラスの定義の時点で例外になる。
次の`Record`は説明用のモデルである。

```python
class Record(Base):
    __tablename__ = "records"
    id: Mapped[int] = mapped_column(primary_key=True)
    values: Mapped[list[int]]
# mypy: Success: no issues found in 1 source file
# pyright: 0 errors, 0 warnings, 0 informations
# 実行時
# sqlalchemy.orm.exc.MappedAnnotationError: Could not locate SQLAlchemy Core type when resolving for Python type indicated by 'list[int]' inside the Mapped[] annotation for the 'values' attribute; the type object is not resolvable by the registry
```

型チェッカーはこの誤りを検出せず、モジュールのimportの時点で初めて例外になる。

`String(30)`のように長さや精度を指定する列は、`mapped_column(String(30))`で型を明示する。
1つの型の指定を複数の列で再利用する方法は、[公式ドキュメント](https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html#orm-declarative-mapped-column-type-map) の`type_annotation_map`と`Annotated`の節にある。

## 型チェッカーが検出しない誤り

### 注釈とmapped_column()の列の型の不一致

`Mapped[...]`の型と`mapped_column()`に指定した列の型が矛盾していても、型チェッカーはエラーにしない。

```python
class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[int] = mapped_column(String(30))


with Session(engine) as session:
    session.add(User(id=1, name="Ada"))
    session.commit()
    value = session.scalars(select(User.name)).one()
    reveal_type(value)
    # mypy: Revealed type is "int"
    print(value, type(value).__name__)  # Ada str
```

型チェッカーは`name`列の値`value`を`int`と判定するが、実行時の値は文字列の`"Ada"`である。
この不一致を検出できないのは、`mapped_column()`の戻り値が列の型の情報のない`MappedColumn[Any]`だからである。
列の型を明示する列では注釈の型と列の型の対応を目視かテストで確認する。

### コンストラクタの引数名の誤り

`DeclarativeBase`が生成するコンストラクタの型は、任意のキーワード引数を受理する。
型チェッカーは引数名の誤りを検出しない。
標準のコンストラクタの引数名がモデルの属性にない場合、実行時に`TypeError`になる。

```python
User(nmae="x")
# mypy: Success: no issues found in 1 source file
# 実行時
# TypeError: 'nmae' is an invalid keyword argument for User
```

型チェッカーで引数名の誤りを検出する方法は2つある。
1つは引数に型の注釈がある`__init__`（`def __init__(self, *, name: str) -> None`）をモデルに定義する方法である。
もう1つは`MappedAsDataclass`の併用で、モデルはdataclassになり、生成されたコンストラクタの引数が型チェッカーに通知される。

```python
from sqlalchemy.orm import MappedAsDataclass


class Base(MappedAsDataclass, DeclarativeBase):
    pass


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(init=False, primary_key=True)
    name: Mapped[str]


User(nmae="x")
# mypy
# error: Unexpected keyword argument "nmae" for "User"  [call-arg]
# pyright
# error: Argument missing for parameter "name" (reportCallIssue)
# error: No parameter named "nmae" (reportCallIssue)
```

コンストラクタの引数にしない列には`init=False`を指定する。
自動採番の`id`がその例である。
引数を省略可能にするには`default`を指定する。
`str | None`の注釈だけでは引数は省略可能にならない。
注釈の役割は引数の値の型の指定で、生成される`__init__`の引数の省略の可否は、[dataclassと同じく](https://peps.python.org/pep-0557/#specification) デフォルト値の有無に依存する。
dataclassになると、デフォルトの設定では`__eq__`と`__repr__`も生成され、インスタンスはハッシュ化できなくなる。
モデルを集合や辞書のキーにする既存のコードがあるなら、`__init__`の定義のほうが既存のコードへの影響が少ない。
型チェッカーがこのモデルを [dataclassとして認識する](https://docs.sqlalchemy.org/en/20/orm/dataclasses.html) のは、[PEP 681](https://peps.python.org/pep-0681/) の`dataclass_transform`を解釈するからである。

## relationshipの型

`relationship()`の属性も`Mapped[...]`で注釈し、1対多の側は`Mapped[list["Address"]]`、多対1の側は`Mapped["User"]`にする。

```python
from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship


class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    addresses: Mapped[list["Address"]] = relationship(back_populates="user")


class Address(Base):
    __tablename__ = "addresses"
    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
    user: Mapped["User"] = relationship(back_populates="addresses")

# reveal_type(user.addresses) -> list[Address]
# reveal_type(address.user) -> User
```

モデルを複数のファイルに分割したときの循環参照の回避は [SQLAlchemyでMany to Manyのモデルを分割する](https://kdot.co.jp/kdotdev/sqlalchemy-orm-many-to-many-relationship) で説明した。
