SQLAlchemyはPythonのデータベース操作を強力に支援してくれるライブラリですが、mypyなどの型チェックツールと組み合わせると問題が発生することがあります。この記事では、特にselect.where句で型エラーが発生するケースについて、再現例と解決策を詳しく紹介します。最近この現象でドハマリしたので備忘録です。

環境

• sqlalchemy>=2.0.36
• mypy>=1.5.1

再現例と解決策

再現例: mypyによる型チェックエラー

以下のコードを例に取ります。このコードは、Userテーブルから特定のuser_idに一致するレコードを取得するシンプルなクエリを実行します。

from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.future import select

# Userモデルは適切に定義されていると仮定

result = await session.execute(
    select(User).where(User.id == user_id)
)

このコードをmypyでチェックすると、以下のようなエラーが発生することがあります。

error: Unsupported left operand type for == ("Column[Any]")

このエラーは、SQLAlchemyの比較演算子（==）が返す型をmypyが正確に理解できないために起こります。

解決策

型エラーを解消するためのアプローチを以下に整理しました。

1. mypyの設定

mypyがSQLAlchemyの型ヒントを正しく扱えるようにするため、次の設定をmypy.iniまたはpyproject.tomlに追加してください。

mypy.ini の例

1
2
3

[mypy]
plugins = sqlalchemy.ext.mypy.plugin

pyproject.toml の例

1
2
3

[tool.mypy]
plugins = ["sqlalchemy.ext.mypy.plugin"]

これにより、SQLAlchemyの型情報が正しく認識され、型チェックが強化されます。

2. filter_byの使用

SQLAlchemyにはfilter_byメソッドが用意されており、シンプルな等価比較に適しています。この方法では型エラーが発生しません。

書き換え例

result = await session.execute(
    select(User).filter_by(id=user_id)
)

注意点

filter_byには以下の制限があります：

• 等価比較（==）のみ対応
• 複雑な条件（ORやANDなど）は使用できない
• カラム名を文字列として扱うため、静的解析では限定的なサポート

そのため、複雑な条件が必要な場合にはwhere句を使用する必要があります。

3. 型キャストを使用する

where句を使用しながら、mypyの型エラーを回避する方法として、castを使った型キャストがあります。

書き換え例

from typing import cast
from sqlalchemy.sql.elements import BinaryExpression

condition = cast(BinaryExpression, User.id == user_id)
result = await session.execute(

    select(User).where(condition)

)

メリット

• 型安全性を保ちながらmypyエラーを解消できる
• 複雑な条件にも対応可能

4. # type: ignore コメントを使用

どうしても型エラーを解決できない場合は、 # type: ignore を使って特定の行での型チェックを無効化します。

書き換え例

result = await session.execute(

    select(User).where(User.id == user_id)  # type: ignore[operator]

)

注意点

• # type: ignore は乱用せず、他の解決策が使えない場合のみに限定する
• 型チェックが無効化されるため、安全性が低下する可能性がある

実践例

以下に、複雑な条件を扱う場合の実践例を示します。

条件: 年齢が30以上かつ特定の名前を持つユーザーを取得

型キャストを使用

from sqlalchemy import and_
from typing import cast
from sqlalchemy.sql.elements import BinaryExpression

condition = cast(BinaryExpression, and_(User.age >= 30, User.name == "Alice"))
result = await session.execute(

    select(User).where(condition)

)

このような複雑な条件は filter_by ではサポートされていません。

sqlalchemy-stubs

ネットを調べてこの問題の解決策として sqlalchemy-stubs を使えとの情報にたどり着いたのですが、SQLAlchemy 2.0の登場以降は推奨されていません。

結論

SQLAlchemyとmypyの相性には課題がありますが、まず filter_by 使ってそれがだめなときはこまめに型キャストするか面倒なら # type: ignore を使うことになるでしょう。この記事が型チェックエラーの解決に役立てば幸いです！

参考文献

• SQLAlchemy Documentation
• mypy Documentation