Skip to content

Latest commit

 

History

History
206 lines (157 loc) · 15.8 KB

README.md

File metadata and controls

206 lines (157 loc) · 15.8 KB

SQLAlchemy: API 2.x

English

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
Loading
Чтение Результат
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" и FK ON 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. Задавайте явные транзакционные границы задачи.

Источники