SQLAlchemy 1.4 Typing Stubs

Warnings

• breaking The `sqlalchemy2-stubs` package is explicitly NOT compatible with SQLAlchemy 2.0. Upgrading to SQLAlchemy 2.0 requires manual uninstallation of `sqlalchemy2-stubs` because SQLAlchemy 2.0 includes inline type annotations that conflict with stub packages.
  Fix: Before upgrading to SQLAlchemy 2.0, or if you are using SQLAlchemy 2.0, uninstall `sqlalchemy2-stubs` using `pip uninstall sqlalchemy2-stubs`.
• deprecated The Mypy plugin associated with `sqlalchemy2-stubs` is deprecated in SQLAlchemy 2.0 and has known compatibility issues with Mypy versions 1.11.0 or greater, with support guaranteed only up to Mypy 1.10.1.
  Fix: For SQLAlchemy 1.4, use Mypy versions 1.10.1 or older. For SQLAlchemy 2.0, migrate to its native typing system and remove the Mypy plugin and stubs.
• gotcha Do not install `sqlalchemy2-stubs` and the older `sqlalchemy-stubs` (from Dropbox) simultaneously. They occupy the same namespace and will cause conflicts and incorrect type checking results.
  Fix: Ensure only one set of SQLAlchemy stubs (`sqlalchemy2-stubs` or `sqlalchemy-stubs`) is installed. For SQLAlchemy 1.4, `sqlalchemy2-stubs` is recommended.
• gotcha Mixed environments (e.g., SQLAlchemy 1.x and 2.x codebases, or incremental migration attempts) where `sqlalchemy2-stubs` is present can lead to significant type errors, especially with imports like `declarative_base`.
  Fix: Maintain a clear separation of SQLAlchemy versions. For projects migrating to SQLAlchemy 2.0, a complete transition away from `sqlalchemy2-stubs` is necessary, and incremental migration with stubs installed is difficult and often problematic.

Install

• pip install sqlalchemy2-stubs Install only stubs
• pip install 'sqlalchemy[mypy]' sqlalchemy2-stubs Install with SQLAlchemy's Mypy extra

Imports

• declarative_base

  from sqlalchemy.ext.declarative import declarative_base

  This is the typical import path for declarative_base in SQLAlchemy 1.x. In SQLAlchemy 2.0, it's typically 'from sqlalchemy.orm import DeclarativeBase'.
• Column

  from sqlalchemy import Column

  Standard import for column definition.
• Integer

  from sqlalchemy import Integer

  Standard import for integer type.
• String

  from sqlalchemy import String

  Standard import for string type.
• Mapped

  from sqlalchemy.orm import Mapped

  Mapped is part of the ORM module.

Quickstart

This quickstart demonstrates defining a SQLAlchemy 1.4 ORM model with `sqlalchemy2-stubs` compatible type annotations using `Mapped`. The `sqlalchemy2-stubs` package itself does not have runtime code but provides type hints for tools like Mypy. Ensure Mypy is configured to use the SQLAlchemy plugin for full benefits (e.g., in `mypy.ini` or `pyproject.toml`: `[mypy] plugins = sqlalchemy.ext.mypy.plugin`).

from typing import Optional
from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.orm import Mapped, declarative_base, Session

Base = declarative_base()

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = Column(Integer, primary_key=True)
    name: Mapped[Optional[str]] = Column(String(50))
    email: Mapped[str] = Column(String(50), nullable=False)

    def __repr__(self) -> str:
        return f"<User(id={self.id}, name='{self.name}', email='{self.email}')>"

# Example usage (not requiring sqlalchemy2-stubs at runtime, but for type checking)
if __name__ == '__main__':
    engine = create_engine('sqlite:///:memory:')
    Base.metadata.create_all(engine)

    with Session(engine) as session:
        new_user = User(name='Alice', email='alice@example.com')
        session.add(new_user)
        session.commit()
        print(f"Added user: {new_user}")

        retrieved_user = session.query(User).filter_by(name='Alice').first()
        print(f"Retrieved user: {retrieved_user}")