{"id":2780,"library":"sqlalchemy-stubs","title":"SQLAlchemy Stubs","description":"SQLAlchemy Stubs (version 0.4, last updated January 2021) is an experimental package providing type stubs and a Mypy plugin for the SQLAlchemy framework. Its goal was to offer more precise static types and type inference for SQLAlchemy's dynamic features. This package is now largely superseded by newer approaches to SQLAlchemy typing.","status":"abandoned","version":"0.4","language":"en","source_language":"en","source_url":"https://github.com/dropbox/sqlalchemy-stubs","tags":["typing","mypy","SQLAlchemy","stubs","static-analysis","declarative-models"],"install":[{"cmd":"pip install sqlalchemy-stubs","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required to use the Mypy plugin for type checking.","package":"mypy","optional":false},{"reason":"Required for type hint features.","package":"typing-extensions","optional":false},{"reason":"The core library that these stubs provide typing for. Must be installed separately.","package":"SQLAlchemy","optional":false}],"imports":[{"note":"This is a Mypy configuration entry, not a Python import. It must be added to your 'mypy.ini' or 'setup.cfg' to enable the plugin.","symbol":"Plugin Configuration","correct":"[mypy]\nplugins = sqlmypy"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, Column, Integer, String\nfrom sqlalchemy.orm import declarative_base, sessionmaker\n\n# Configure Mypy (typically in mypy.ini or setup.cfg, not code)\n# [mypy]\n# plugins = sqlmypy\n\n# Database setup (example using SQLite in memory)\nDATABASE_URL = os.environ.get('DATABASE_URL', 'sqlite:///:memory:')\nengine = create_engine(DATABASE_URL)\nBase = declarative_base()\nSession = sessionmaker(bind=engine)\n\nclass User(Base):\n    __tablename__ = 'users'\n    id: int = Column(Integer, primary_key=True)\n    name: str = Column(String)\n\n# This class will be type-checked by mypy using the stubs and plugin\n# (Assuming mypy is configured and run externally)\n\n# Example usage (not directly type-checked by sqlalchemy-stubs at runtime)\ndef create_user(session, user_id: int, user_name: str):\n    new_user = User(id=user_id, name=user_name)\n    session.add(new_user)\n    session.commit()\n    return new_user\n\nif __name__ == '__main__':\n    Base.metadata.create_all(engine)\n    session = Session()\n\n    # This part needs mypy run externally to show type benefits\n    # For instance, mypy might catch: create_user(session, '1', 123) if types were incorrect\n    user1 = create_user(session, 1, 'Alice')\n    print(f\"Created user: {user1.name} (ID: {user1.id})\")\n\n    session.close()","lang":"python","description":"This quickstart demonstrates how to define a SQLAlchemy declarative model. To benefit from `sqlalchemy-stubs`, you must install the package and configure Mypy to use its plugin by adding `plugins = sqlmypy` to your `mypy.ini` or `setup.cfg` file. Run Mypy separately on your project to enable static type checking for SQLAlchemy models."},"warnings":[{"fix":"For SQLAlchemy 2.0+, uninstall `sqlalchemy-stubs` and `sqlalchemy2-stubs` (if installed). SQLAlchemy 2.0 provides full PEP-484 compliant typing natively without external stub packages or a Mypy plugin.","message":"The `sqlalchemy-stubs` package is superseded by SQLAlchemy 2.0's native, inline type annotations. Installing `sqlalchemy-stubs` or `sqlalchemy2-stubs` (for SQLAlchemy 1.4) can cause type conflicts and incorrect behavior with SQLAlchemy 2.0+.","severity":"breaking","affected_versions":"SQLAlchemy 2.0.0 and newer"},{"fix":"Transition to SQLAlchemy 2.0+ for native typing support. If using SQLAlchemy 1.4, consider the `sqlalchemy2-stubs` package (though also superseded by 2.0+).","message":"This project (version 0.4) is no longer actively maintained and has not seen updates since January 2021. Its functionality has been largely replaced by the SQLAlchemy project's own typing efforts.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Ensure your Mypy configuration includes the `plugins = sqlmypy` line under the `[mypy]` section.","message":"The Mypy plugin provided by `sqlalchemy-stubs` must be explicitly enabled in your Mypy configuration file (e.g., `mypy.ini` or `setup.cfg`) via `plugins = sqlmypy`. Without this, the stubs will not provide enhanced type inference.","severity":"gotcha","affected_versions":"All versions of `sqlalchemy-stubs`"},{"fix":"Be aware of potential limitations. For more comprehensive and up-to-date typing, upgrading to SQLAlchemy 2.0+ is the recommended approach.","message":"The `sqlalchemy-stubs` package is marked as 'Alpha' and may not fully cover all SQLAlchemy features or edge cases, potentially leading to incomplete type inference (`Any`) or false positive errors.","severity":"gotcha","affected_versions":"All versions of `sqlalchemy-stubs`"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}