Flask-SQLAlchemy: the defaults and helpers wrapped around SQLAlchemy

The extension supplies defaults and helpers, not a different ORM

Flask-SQLAlchemy adds SQLAlchemy support to a Flask application. What it claims to change is ergonomics, not the ORM: it aims to simplify using SQLAlchemy with Flask by providing useful defaults and extra helpers that make common tasks easier. Everything you know about SQLAlchemy 2 still applies, because the package declares sqlalchemy>=2.0.16 as a runtime dependency and the shipped example imports DeclarativeBase, Mapped and mapped_column straight from sqlalchemy.orm. Two runtime dependencies in total, the other being flask>=2.2.5. The metadata is candid about the audience: classifiers for a production stable status, the web environment, OS independent operation and typed code. This is a bridge library. If your objection to SQLAlchemy is the API, this package does not answer it, and if your objection is the boilerplate around sessions and model bases, it does.

`db.Model` inherits the declarative base you hand the constructor

The example makes the base class explicit and passes it in. You declare Base(DeclarativeBase) yourself, construct the extension as SQLAlchemy(app, model_class=Base), and then define models on top of db.Model with SQLAlchemy 2 typed columns. The two columns in the example are annotated rather than cast: id: Mapped[int] = mapped_column(primary_key=True) and username: Mapped[str] = mapped_column(unique=True). Two consequences follow from the constructor signature. The extension does not impose its own declarative base, so if your project already has one, you keep it. And the typed column style in the example is SQLAlchemy 2 syntax, which lines up with the sqlalchemy>=2.0.16 floor in the project metadata and with requires-python = ">=3.8". Attribute typing works only for columns declared this way; a bare db.Column has no annotation to read.

`db.session` requires an active application context

Table creation and the first write both happen inside a context manager in the published example:

with app.app_context():
    db.create_all()

    db.session.add(User(username="example"))
    db.session.commit()

The session requires an active Flask application context. Requests and Flask CLI commands provide one automatically; standalone code can enter app.app_context() explicitly. create_all() is also the entire schema story in the example: it creates tables for the models that have been imported at that point, and the README does not document a migration path or a downgrade for this extension. create_all() does not update existing tables; the official guide recommends a migration library such as Alembic with Flask-Migrate or Flask-Alembic. The README then reads rows using `db.session.scalars(db.select(User))`.

`SQLALCHEMY_DATABASE_URI` is the one setting the example touches

The database is chosen in the Flask config, before the extension is constructed:

app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///example.sqlite"

That single key is the whole connection story in the README. The example stores its data in a SQLite file called example.sqlite, which makes it run with no server and no driver beyond the standard library. A server database instead of a file means supplying a different URI, and the published example gives none for it: no connection arguments, no pool settings, no mention of environment variables.

flit builds one module called `flask_sqlalchemy` under BSD-3-Clause

The distribution is built by flit, and the mapping from package name to import name is written out in the project file:

[build-system]
requires = ["flit-core<4"]
build-backend = "flit_core.buildapi"

[tool.flit.module]
name = "flask_sqlalchemy"

So the distribution is Flask-SQLAlchemy and the import is flask_sqlalchemy. The licence file is LICENSE.txt and the licence itself is BSD-3-Clause. Maintainers are listed as Pallets with [email protected]. The sdist configuration includes docs/, requirements/, tests/, CHANGES.rst and tox.ini, which tells you what travels with a source release: the documentation tree, the test suite and the change log, not just the module.

Dev, typing, docs and test work sit in dependency groups

Only two packages are needed to run the extension. Everything else is grouped:

requires-python = ">=3.8"
dependencies = [
    "flask>=2.2.5",
    "sqlalchemy>=2.0.16",
]

The dev group pulls in ruff, tox and tox-uv, then includes the pre-commit, docs, tests and typing groups rather than repeating their contents. tests holds pytest. typing holds mypy, pyright and pytest, so a contributor is expected to satisfy two type checkers, not one. docs is pallets-sphinx-themes, sphinx and sphinxcontrib-log-cabinet. Two groups are conditional on the interpreter: gha-update only installs on python_full_version >= '3.12', and the pre-commit group only on python_full_version >= '3.9'. A lock file for the development environment is committed as uv.lock.

Pallets-Eco maintains it, with two example applications in the tree

The project states that it belongs to the Pallets Community Ecosystem, that Pallets maintains Flask, and that Pallets-Eco exists so the extensions can be maintained by the community. Anyone interested in helping maintain it is pointed at the Pallets Discord server, and the repository carries CONTRIBUTING.rst and CHANGES.rst. The top level of the repository is a documentation project as much as a library: docs/ for the manual published at flask-sqlalchemy.readthedocs.io, artwork/ for images, a .readthedocs.yaml for the hosting side and examples/ holding two working applications, flaskr/ and todo/. Those two directories are where the extension is used at length, and they are the first place to look if the README example leaves a question about query patterns or relationships unanswered.

The newest tag is 3.1.1 from September 2023

The release history is short and old: 3.1.1 and 3.1.0 were both published on 2023-09-11, and 3.0.5 on 2023-06-21 before that. The project file still says version = "3.1.1", so nothing has been cut since, even though the branch itself is not dormant: the last push to the repository was on 2026-05-18. That gap matters for anyone writing a dependency constraint, because the floors the extension asks for are flask>=2.2.5 and sqlalchemy>=2.0.16 and the Python floor is 3.8, so a resolver on a current Flask will install this alongside a SQLAlchemy 2 line that has moved on since the tag. Documentation is hosted separately at flask-sqlalchemy.readthedocs.io with its own changes page, and the source of truth for behaviour on a newer branch is that documentation rather than the last tag.

Editorial conclusion

Take Flask-SQLAlchemy when you want a Flask app wired to SQLAlchemy 2 with a session and model base already configured, and use Alembic with Flask-Migrate or Flask-Alembic for schema migrations, and configure a supported database URI and driver. Before pinning a version, check which release your resolver picks: the newest tag is 3.1.1 from 2023-09-11, the runtime floors are flask>=2.2.5 and sqlalchemy>=2.0.16, and pyproject.toml still declares version = "3.1.1" while the last push to the branch was on 2026-05-18.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. pallets-eco/flask-sqlalchemy on GitHub
3. Project website
4. README
5. Releases