SQLAlchemy объединяет SQL-конструктор Core и ORM с сессиями, отношениями и транзакциями.
Откройте справочник для моделей, транзакций, запросов и выбора загрузки отношений.
Справочник использует стиль select().
Примеры используют SQLAlchemy 2.1.
Примеры сохраняют основные конструкции, введённые в 2.0.
Каталог Python · FastAPI и сессия на запрос
| Задача | API | Где |
|---|---|---|
| Модель, типы, defaults, constraints | DeclarativeBase, Mapped, mapped_column |
Модели |
| CRUD и откат | Session, session.begin(), rollback() |
Транзакции |
| 1:N, N:1, 1:1, N:M | relationship, ForeignKey, Table |
Полная схема |
| WHERE/JOIN/CTE/CASE/UNION/EXISTS | select, func, aliased |
Запросы |
| Устранить слишком много запросов при чтении коллекций | N+1, lazy, selectinload |
Карточка N+1 · Самостоятельная программа |
| Выбрать загрузку коллекции по объёму и ограничениям | selectinload или joinedload |
Таблица решений · Select-in · Joined и unique |
| Загрузить автора каждого поста | Сравнить повторение полей и число SELECT | Одиночная связь |
| Запретить неожиданный lazy SELECT | raiseload |
Карточка и ограничения |
| Загрузить часть отношения своим JOIN | contains_eager, populate_existing |
Частичная коллекция |
| Обработать большую выборку | yield_per, partitions |
Пакеты и ограничения |
| Async-сессия и атрибуты | AsyncSession, AsyncAttrs, awaitable_attrs |
Async |
| UPSERT / FOR UPDATE / частичный индекс | Диалект PostgreSQL | Компиляция PostgreSQL |
| События, SQL-логи и время запроса | event, logging, perf_counter |
Наблюдение |
| Изменить схему | Alembic | Миграции |
| Параметр | Значение |
|---|---|
| API / диалект | SQLAlchemy 2.1; исполняемые примеры SQLite, PostgreSQL отдельно помечен |
| Предпосылки | Python, SQL, транзакции; async-рецепт требует async with |
| Самостоятельный N+1 | Синхронный пример с двумя моделями: отдельная установка и проверки; общая схема ему не нужна |
Ситуация: пользователь должен сохраниться при успехе и откатиться при исключении.
Изменение: отделите жизнь сессии от транзакционной границы.
Фрагмент использует User и new_engine() из полной схемы:
from sqlalchemy.orm import Session
from demo_models import User, new_engine
engine = new_engine()
try:
with Session(engine) as session, session.begin():
user = User(name="alice", email="alice@example.com")
session.add(user)
session.flush()
assert user.id is not None
finally:
engine.dispose()Результат: flush выдаёт id, а успешный выход из begin фиксирует транзакцию.
SQLite существует только в памяти; после освобождения движка данные исчезают.
Полные CRUD и проверки отката.
Для первого знакомства с N+1 используйте отдельную подготовку одного файла.
Установка ниже относится к общей схеме и остальным рецептам раздела.
Установите пакеты в отдельное окружение: python -m pip install 'sqlalchemy[asyncio]==2.1.8' pytest.
Extra asyncio нужен общей модели с AsyncAttrs, даже для её синхронных рецептов.
Для async добавьте aiosqlite и pytest-asyncio.
| Компонент | Назначение |
|---|---|
Engine / Connection |
Доступ к драйверу/пулу; конкретное соединение |
MetaData / Table / Column |
Описание схемы Core; Column нужен и в 2.x |
DeclarativeBase, Mapped[T] |
ORM-отображение и аннотации; Mapped не обязателен для всех допустимых стилей |
Session |
Identity map и единица работы; не общий потокобезопасный контейнер |
select() |
Описание запроса; SQL выполняется через сессию/соединение |
Result / ScalarResult |
Строки / значения первого выбранного столбца |
with Session(engine) закрывает сессию, но сам не делает commit.
При успехе with session.begin() фиксирует транзакцию.
При исключении контекст откатывает транзакцию.
flush() отправляет изменения в БД внутри транзакции.
Метод также выдаёт сгенерированные id.
Вызов flush() не выполняет commit.
Полный исполняемый пример.
Схема показывает границу сессии и исходы явной транзакции:
flowchart LR
A[Открыть Session] -->|выделить границу работы| B[Начать транзакцию]
B -->|выполнить изменения| C[Изменить объекты]
C -->|синхронизировать с БД| D[flush: отправить SQL]
D -->|завершить успешно| E[Успех: commit]
D -->|обработать ошибку| F[Ошибка: rollback]
E -->|освободить ресурсы| G[Закрыть Session]
F -->|освободить ресурсы| G
| Чтение | Результат |
|---|---|
session.get(User, id) |
Объект либо None, с учётом identity map |
session.scalars(select(User)).all() |
Список ORM-объектов |
session.execute(select(User.name, User.email)) |
Строки из двух выбранных значений |
result.scalar_one() / scalar_one_or_none() |
Контроль числа результатов; больше одной строки — ошибка |
Ситуация: из подготовленных Alice и Bob нужны имена и возраст совершеннолетних.
Изменение: выберите колонки явно и используйте execute, сохраняя обе колонки.
Фрагмент использует Session с данными из полного seed():
from sqlalchemy import select
from demo_models import User
rows = session.execute(
select(User.name, User.age).where(User.age >= 18).order_by(User.id)
).all()
assert rows == [("alice", 30)]Результат: одна строка с двумя значениями.
scalars() оставил бы только первую выбранную колонку.
Полный набор JOIN, CTE, EXISTS и проверки.
Mapped[str | None]выводит nullable. Явныйnullable=имеет приоритет.Numericобычно возвращаетDecimal. Аннотируйте соответствующее поле как Decimal.defaultприменяется на стороне Python/SQLAlchemy.server_defaultвходит в DDL БД.onupdateне создаёт серверный trigger.- Обеспечивайте уникальность и внешние ключи через constraints. Для 1:1 скалярного
relationshipнедостаточно. Нужен уникальный FK или PK. Enum(MyEnum)по умолчанию хранит имена членов. Для строковых значений задайтеvalues_callable. Для целочисленного хранения нужна соответствующая отдельная модель столбца/конвертации.- ORM
cascade="all, delete-orphan"и FKON DELETE— разные механизмы. Схема и тесты включают внешний ключ SQLite явно.
Ситуация: список пользователей должен включать все посты, а дополнительный SELECT допустим.
Изменение: загрузите коллекции через selectinload.
Фрагмент запроса из самостоятельной программы с двумя моделями:
stmt = select(User).options(selectinload(User.posts)).order_by(User.id)
users = session.scalars(stmt).all()
rows = [(user.name, [post.title for post in user.posts]) for user in users]Результат учебного набора: Alice с двумя постами и Bob с пустой коллекцией; два SELECT вместо трёх. Число запросов относится к двум пользователям и новой Session. Импорты и подготовка указаны в полной программе. Выбор стратегии, цена JOIN и ограничения.
Запросы описывают SQL-выражения и отдельную компиляцию PostgreSQL.
Карточки загрузки помогают выбрать состав отношений.
Большие выборки описывают пакетную обработку отдельно.
Для полных коллекций списка начните с selectinload, если дополнительные SELECT допустимы.
Для небольшой коллекции сравните joinedload, учитывая повторение полей родителя и обязательный unique().
Для одиночной связи сопоставьте число SELECT и повторение полей связанного объекта.
Таблица решений и ограничения запроса описывает условия выбора.
Количество SELECT само по себе не доказывает ускорение.
Async и эксплуатация описывают сессию на задачу, события и миграции.
Выбирайте размер пула, max_overflow, pool_recycle и pool_pre_ping по драйверу и лимитам БД.
Числа из примеров не являются универсальными настройками.
Компиляционный cache SQLAlchemy не кэширует строки результата.
Наличие cache не означает server-side prepared statement.
Для новых примеров не нужен устаревший sqlalchemy.ext.baked.
Переиспользуйте параметризованные выражения.
Измеряйте запросы.
| Симптом | Исправление |
|---|---|
| Сессия «rolled back» после flush | Вызовите rollback() перед повторным использованием либо завершите контекст транзакции |
DetachedInstanceError |
Заранее загрузите нужные поля/отношения или преобразуйте объект в DTO до закрытия сессии |
Надежда на expire_on_commit=False как полное лечение |
Он предотвращает expiry при commit, но не загружает отсутствующие отношения |
| Отношение не заполнено после обычного JOIN | JOIN фильтрует строки; для eager loading нужны loader options / contains_eager |
metadata как ORM-атрибут |
Имя зарезервировано Declarative. Используйте другое Python-имя с SQL-именем столбца |
Один AsyncSession в gather() |
Выделите сессию на конкурентную задачу |
Session.query() — legacy API.
Query.get() заменён на Session.get().
Не объявляйте все конструкции с Column запрещёнными.
Не возвращайте library-level autocommit.
Задавайте явные транзакционные границы задачи.