Overview

SQLAlchemy 2.1, released on March 16, 2025, introduces write-only relationships and improves query performance.

Main Features

Write-only relationships

WriteOnlyMapped relationships avoid loading large collections into memory. Elements are added or removed without loading the entire collection.

python 
from sqlalchemy.orm import DeclarativeBase, Mapped, WriteOnlyMapped
from sqlalchemy.orm import mapped_column, relationship
from sqlalchemy import ForeignKey

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = 'users'
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    # Large collection: write-only
    logs: WriteOnlyMapped[list['Log']] = relationship()

class Log(Base):
    __tablename__ = 'logs'
    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(ForeignKey('users.id'))
    message: Mapped[str]

Performance improvements

The query compiler is optimized to generate more efficient SQL, with better batching support for inserts.

python 
from sqlalchemy import create_engine, select
from sqlalchemy.orm import Session

engine = create_engine('sqlite:///app.db')

with Session(engine) as session:
    # Optimized batch insert
    session.add_all([
        User(name=f'user_{i}') for i in range(1000)
    ])
    session.commit()

    # Optimized query
    stmt = select(User).where(User.name.like('user_1%'))
    users = session.scalars(stmt).all()

Sources