Вышел SQLAlchemy 2.0: что нового в культовой ORM для работы с базами данных на Python
2026-02-26 17:08 Diff
https://ru.hexlet.io/blog/posts/vyshel-sqlalchemy-2-0

Рассказываем про обновление опенсорс-проекта SQLAlchemy, с помощью которого миллионы Python-разработчиков работают с базами данных.

В начале 2023 года вышла SQLAlchemy 2.0 — библиотека на Python для работы с реляционными СУБД, которая работает с Object Relational Mapper (объектно-реляционным отображением). Основная задача SQLAlchemy — синхронизация объектов Python с данными в БД.

То есть с помощью SQLAlchemy можно описывать структуры БД и работать с их данными на объектно-ориентированном коде на Python без использования чистого SQL. Другая важная особенность SQLAlchemy — код для работы с базой данных будет одинаковым вне зависимости от БД, которую использует разработчик. Такой подход позволяет без проблем мигрировать с одной базой данных на другую.

Полный список нововведений в SQLAlchemy 2.0 можно посмотреть в официальной документации сервиса.

Читайте также:

Программирование на Python: особенности обучения, перспективы, ситуация на рынке труда

Содержание

Новый интерфейс запросов

В SQLAlchemy 2.0 появился новый интерфейс запросов. Если быть точным, эта функция была представлена в релизе SQLAlchemy 1.4 как способ помочь разработчикам перейти на версию 2.0.

До этого основной (но теперь уже устаревший) способ выполнения запросов в ORM SQLAlchemy заключался в использовании объекта Query, доступного из метода Session.query(). Либо метода Model.query, если разработчик использовал расширение Flask-SQLAlchemy для микрофреймворка Flask.

В релизе SQLAlchemy 2.0 это теперь считается устаревшим способом выполнения запросов. Разработчики по-прежнему могут делать запросы этими методами, но в документации к SQLAlchemy такой подход уже называется «API запросов 1.x» или «устаревший API запросов».

Новый Query API имеет четкое разделение между самими запросами и средой выполнения, в которой они выполняются. Приведенный выше запрос для поиска пользователя по атрибуту username теперь можно записать вот так:

В этом примере запрос сохраняется в переменной query. При этом сейчас запрос еще не выполнен и даже пока не связан с сеансом. Для выполнения этого запроса его нужно передать в метод execute() объекта сеанса:

Возвращаемое значение из execute() — это объект Result, который функционирует как итерируемый объект, возвращающий объекты Row с интерфейсом как у кортежа. При этом в самом Python нет функции с таким названием, под Row обычно понимают «строку» или «запись» в контексте работы с базами данных. Если же разработчик хочет получить результаты, не дублируя их, есть несколько методов, которые можно вызвать для этого объекта:

  • Метод all() позволяет вернуть list с объектом строки для каждой строки результата
  • Метод first() вернет первую строку результата
  • Метод one() вернет первую строку результата и вызовет исключение, если в ответе нет результата. Либо в объекте есть несколько одинаковых объектов, которые подходят под результат
  • Метод one_or_none() вернет первую строку результата, None — если результатов нет, или вызовет исключение, если есть более чем один подходящий к результату объект.

Работа с результатами в виде кортежей имеет смысл, когда каждая строка результата может содержать несколько подходящих значений. Однако, когда у нас есть только одно значение на строку, то извлекать данные из одноэлементных кортежей может быть достаточно утомительно. Поэтому новый интерфейс имеет два дополнительных метода, которые делают работу со строками с одним значением более удобной:

  • Метод scalars() возвращает ScalarResult объект с первым значением каждой строки результата. И перечисленные выше методы остаются доступны для этого нового объекта результата.
  • Метод scalar() возвращает первое значение первой строки результата.

Поэтому устаревший запрос может быть теперь выполнен вот так:

Обновленные менеджеры контекста

Менеджеры контекста сеанса впервые появились, как и интерфейс запросов, еще в SQLAlchemy 1.4. Но теперь этот подход стал стандартом, который используется в SQLAlchemy.

Раньше сеанс с локальной областью видимости был основным шаблоном для работы с сеансами. Расширение Flask-SQLAlchemy, например, включило его в переменную db.session, которая является его сигнатурой. То есть раньше сеанс имел ограниченную зону видимости и привязывался к потоку. Даже несмотря на то, что условная жизнь сеанса может быть намного короче, чем потока — и лечилось это только ручным управлением.

Теперь сеанс можно инициировать с помощью менеджера контекста, что позволяет прозрачно наблюдать за началом сеанса и его концом:

Здесь сеанс закрывается, когда заканчивается блок диспетчера контекста. И, если внутри него возникает ошибка, то сессия откатывается.

Вариант этого шаблона можно использовать для сеанса, который автоматически фиксируется в конце, но все еще откатывается при ошибках:

Аннотации типов

Еще одно интересное изменение, представленное в версии SQLAlchemy 2.0, — это возможность использовать подсказки при вводе данных во время объявления столбцов и связей в моделях. По сути, это введение элементов строгой типизации. Рассмотрим это на модели User:

В версии 2.0 тип столбца можно определить с помощью Mapped-подсказки. Если есть какие-то дополнительные опции, их можно указать в mapped_column().

Применение подсказок для типов данных может дать разработчикам несколько преимуществ:

  • При использовании IDE, которая выполняет статический анализ кода и предлагает изменения по мере ввода, строго типизированная модель поможет вашей IDE лучше понять код.
  • Это позволяет проще работать с dataclasses, которые также опираются на выбранный разработчиком тип данных.
  • Это приводит к тому, что из SQLAlchemy теперь нужно импортировать меньше символов. Потому что теперь для столбцов, которые принимают данные только в числах, датах, времени или даже UUID, можно указывать формат в виде сразу в виде подсказки.

Как и в случае с запросами, SQLAlchemy по-прежнему поддерживает старый способ определения столбцов и связей.

Читайте также:

Как создатель Python Гвидо ван Россум устроился в Microsoft и теперь работает над развитием CPython

Отношения Write-Only

Динамические отношения считаются устаревшими в SQLAlchemy 2.0, поскольку они несовместимы с новым интерфейсом запросов. Вместо этого рекомендуемым решением является новый тип отношений под названием Write-Only («Только для записи»). Вот как определить отношения только для записи:

Отличие от старой динамической связи в том, что связь Write-Only не загружает и не читает связанные объекты. Она только предоставляет методы add() и remove() для внесения изменений или для записи в них.

С таким типом отношений можно получать связанные объекты через метод select(), который возвращает запрос, его можно выполнить в сеансе — например, после добавления фильтров, сортировки или разбивки на страницы.

Вот пример того, как получить объекты tokens, связанные с пользователем, и отсортированные по сроку их действия:

Поддержка асинхронности

SQLAlchemy 1.4 представила бета-версию расширения asyncio, которая показала асинхронные версии объектов Engine и Session. В версии 2.0 это расширение больше не считается бета-версией.

Большая часть настройки асинхронного решения в SQLAlchemy включает в себя предотвращение всех способов неявной работы с БД для того, чтобы минимизировать количество возможных ошибок. Поэтому для использования расширения asyncio нужно, чтобы разработчик хотя бы базово понимал, как работает asyncio под капотом и умел разбираться над выводом ошибок. Подробнее про асинхронность в SQLAlchemy можно почитать тут.

Этот текст — адаптированный перевод материала What's New in SQLAlchemy 2.0? с сайта blog.miguelgrinberg.com

Изучите Python на Хекслете

Пройдите нашу профессию «Python-разработчик», чтобы поменять свою жизнь и стать бэкенд-программистом.