Flask-SQLAlchemy type stubs

2.5.9.4 verified Fri May 01 auth: no python

Third-party type stubs for Flask-SQLAlchemy, provided by the typeshed project. Version 2.5.9.4 corresponds to stubs for Flask-SQLAlchemy 2.5.x. These stubs are installed to enable type checking (e.g., with mypy or Pyright) for Flask-SQLAlchemy usage. Release cadence follows upstream typeshed updates.

pip install types-flask-sqlalchemy

Common errors

error Cannot find implementation or library stub for module 'flask_sqlalchemy' ↓

cause Flask-SQLAlchemy runtime package is not installed.

fix

pip install Flask-SQLAlchemy

error Library stubs not installed for 'flask_sqlalchemy' (or incompatible with Python 3.x) ↓

cause types-flask-sqlalchemy is missing or outdated.

fix

pip install types-flask-sqlalchemy

error error: 'SQLAlchemy' has no attribute 'Column' ↓

cause Stubs do not expose SQLAlchemy's top-level attributes; they should be accessed via 'db.Column'.

fix

Use 'db.Column(...)' where 'db' is your SQLAlchemy instance, not 'SQLAlchemy.Column'.

Warnings

gotcha Ensure both Flask-SQLAlchemy and types-Flask (or stubs for Flask) are installed. Missing stub dependencies will cause mypy to report 'library stubs not found' errors. ↓

fix Run: pip install Flask-SQLAlchemy types-Flask

gotcha The 'db.relationship()' return type may not be fully stubbed. Use 'Mapped' or explicit type hints for complex relationships. ↓

fix Use annotation: from typing import List; users: List['User'] = db.relationship('User')

gotcha Mypy may raise 'Missing type hints' for methods like 'query.filter_by()' due to incomplete stubs. This is a known limitation. ↓

fix Suppress with '# type: ignore[no-untyped-call]' or upgrade to Flask-SQLAlchemy 3.x and use SQLAlchemy 2.0 style.

Imports

SQLAlchemy
```
from flask_sqlalchemy import SQLAlchemy
```
db (SQLAlchemy instance)
```
from flask_sqlalchemy import SQLAlchemy
db = SQLAlchemy()
```
Standard pattern; no alternative import path.
Model
```
from flask_sqlalchemy import Model
```
Base model class; can be subclassed.

Quickstart

Minimal Flask-SQLAlchemy app with type stubs enabling type checking.

from flask import Flask
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///:memory:'
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True)

with app.app_context():
    db.create_all()
    db.session.add(User(username='example'))
    db.session.commit()
    print(User.query.first().username)