SQLAlchemy 2.1 compatibility

[Iberlauf]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

uv tree --package sqlmodel

Description

With the release of SQLAlchemy 2.1, I noticed that SQLModel currently still restricts SQLAlchemy to versions below 2.1:

sqlalchemy>=2.0.54,<2.1

The latest SQLAlchemy version currently supported by SQLModel is therefore 2.0.54.

Is there a plan to add support for SQLAlchemy 2.1?

It would be great to have SQLModel support the 2.1 release series once compatibility has been verified. In particular, the current <2.1 upper bound prevents projects using SQLModel from upgrading to the latest SQLAlchemy release.

Thanks for the great work on SQLModel!

Operating System

Windows

Operating System Details

No response

Project Version

0.0.47

Python Version

3.14

Additional Context

No response

[TanbirRamim]

There was an attempt at this in #1884, which relaxed the pin and added a pre-release test job. It was closed in July because 2.1 was still in beta and a maintainer preferred to wait for the final release before touching the <2.1.0 bound. Now that 2.1 is out, a new PR against that line in pyproject.toml with the test suite passing on 2.1 is probably the way forward.

Until then, since you use uv, you can try 2.1 in your own project without waiting:

[tool.uv]
override-dependencies = ["sqlalchemy>=2.1"]

uv lock will then resolve SQLAlchemy 2.1 despite SQLModel's upper bound. The author of #1884 reported their Postgres tests passing on 2.1.0b2 with SQLModel 0.0.38, so it's worth a try, just not something to ship without your own tests.

[SDAravind]

SQLAlchemy does not follow Semantic Versioning (SemVer). There may be breaking changes in SQLAlchemy that would break SQLModel isn't it?

[TanbirRamim]

Right, SQLAlchemy doesn't promise SemVer, and 2.1 does have breaking changes (the removed legacy Query APIs, typing changes, etc.). That's exactly why the <2.1.0 bound exists and why the uv override is a run-your-own-tests workaround, not something to ship blindly. The proper path is a SQLModel release that is actually tested against 2.1, which is what #1884 tried to add with a pre-release CI job. So: override to find out whether your app breaks, but wait for the official bump before relying on it in production.

[Tenzer]

All tests are passing with SQLAlchemy 2.1, so I've made a PR to expand the allowed version range: #2107.

Edit: Oh well, it's already been closed again automatically. I guess that's not the way to get this addressed then.

[tiangolo]

Thanks everyone for the discussion here! It is now handled in SQLModel 0.0.48, just released. 🚀