sqlalchemy

library2.0.52pypypi✓ verified 31d ago

The most widely used Python SQL toolkit and ORM. v2.0 released January 2023 — massive breaking change from v1.x. The entire ORM query API shifted from session.query() to select(). engine.execute() removed. Passing raw strings to execute() removed. Typed mapped_column() replaces Column(). Current version: 2.0.48 (Mar 2026). Flask-SQLAlchemy's Model.query pattern is also legacy in v2.

database web-framework

pip install sqlalchemy

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SQLALCHEMY

sqlalchemy

databasepythonv2.0.52

Install

3.5s avg

Import

643ms

Disk

41MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.52 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.674s · 43MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.5s · import 0.611s · 41MB

41MB installed

● package 41MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

select

✓ from sqlalchemy import select

✗ from sqlalchemy import select

Session

✓ from sqlalchemy.orm import Session

✗ from sqlalchemy.orm import Session

SQLAlchemy 2.0 ORM quickstart with typed models.

# pip install sqlalchemy from sqlalchemy import create_engine, String, select, text from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session class Base(DeclarativeBase): pass class User(Base): __tablename__ = 'users' id: Mapped[int] = mapped_column(primary_key=True) name: Mapped[str] = mapped_column(String(50)) engine = create_engine('sqlite:///test.db') Base.metadata.create_all(engine) with Session(engine) as session: # Insert session.add(User(name='Alice')) session.commit() # Query — v2 style stmt = select(User).where(User.name == 'Alice') user = session.scalars(stmt).first() print(user.name) # 'Alice'

Debug

Known issues

breakingengine.execute() removed in v2.0. Raises AttributeError. Most LLM-generated SQLAlchemy code uses engine.execute().

fix

Use 'with engine.connect() as conn: conn.execute(text(...))'

affects: >= 2.0

breakingPassing raw strings to execute() removed. conn.execute('SELECT 1') raises ArgumentError in v2.

fix

from sqlalchemy import text; conn.execute(text('SELECT 1'))

affects: >= 2.0

breakingdeclarative_base() from sqlalchemy.ext.declarative is legacy in v2. Still works but generates RemovedIn20Warning.

fix

from sqlalchemy.orm import DeclarativeBase; class Base(DeclarativeBase): pass

affects: >= 2.0

gotchasession.query() is legacy in v2 — still works but not recommended. Flask-SQLAlchemy's Model.query is also legacy. LLMs trained pre-2023 generate session.query() patterns.

fix

Replace session.query(Model).filter(...) with session.scalars(select(Model).where(...))

affects: >= 2.0

gotchasession.execute() now returns a Result object. For ORM models use session.scalars() to get model instances directly, not session.execute().

fix

users = session.scalars(select(User)).all() — not session.execute(select(User)).all()

affects: >= 2.0

gotchaAutocommit behavior changed in v2. Connections no longer autocommit. Must explicitly use with engine.begin() for autocommit or session.commit().

fix

Use 'with engine.begin() as conn:' for autocommit. Or call session.commit() explicitly.

affects: >= 2.0

gotchaColumn() without type annotations still works but loses IDE/mypy type inference. mapped_column() with Mapped[] is the v2 typed approach.

fix

id: Mapped[int] = mapped_column(primary_key=True)

affects: >= 2.0

Upgrade

Version history

2.0.52latest on PyPI · released Aug 11, 2026

Audit

Dependencies

greenletoptionalRequired for async support. Install via sqlalchemy[asyncio].

psycopg2optionalRequired for PostgreSQL sync. Or use asyncpg for async.

Agent activity

84 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

githubhttps://github.com/sqlalchemy/sqlalchemy ↗

packagehttps://pypi.org/project/sqlalchemy/ ↗

homepagehttps://www.sqlalchemy.org ↗

docshttps://docs.sqlalchemy.org ↗