Самоучитель SQLAlchemy 1.4 / 2.0¶
Об этом документе
Новый учебник по SQLAlchemy теперь интегрирован между Core и ORM и служит единым введением в SQLAlchemy в целом. В новой 2.0 style работе, полностью доступной в 1.4 release, ORM теперь использует запросы в стиле Core с конструкцией select()
, а транзакционная семантика между соединениями Core и сессиями ORM эквивалентна. Обратите внимание на стили синих границ для каждого раздела, они подскажут вам, насколько «ORM-шной» является та или иная тема!
Пользователи, которые уже знакомы с SQLAlchemy, и особенно те, кто хочет перевести существующие приложения на работу под SQLAlchemy 2.0 в рамках переходного этапа 1.4, должны также ознакомиться с документом Переход на SQLAlchemy 2.0.
Для новичка этот документ содержит много деталей, однако к концу он будет считаться алхимиком.
SQLAlchemy представлен в виде двух различных API, один из которых построен на основе другого. Эти API известны как Core и ORM.
SQLAlchemy Core - это фундаментальная архитектура для SQLAlchemy как «набора инструментов для работы с базами данных». Библиотека предоставляет инструменты для управления подключением к базе данных, взаимодействия с запросами к базе данных и результатами, а также для программного построения SQL-запросов.
В разделах, имеющих темно-синюю рамку справа, обсуждаются концепции, которые в основном относятся только к Core; при использовании ORM эти концепции остаются в силе, но реже проявляются в пользовательском коде.
SQLAlchemy ORM основывается на ядре и предоставляет дополнительные возможности объектно-реляционного отображения. ORM предоставляет дополнительный уровень конфигурации, позволяющий определяемым пользователем классам Python быть сопоставленными с таблицами базы данных и другими конструкциями, а также механизм сохранения объектов, известный как Сессия. Затем он расширяет язык SQL-выражений уровня Core, позволяя составлять и вызывать SQL-запросы в терминах определяемых пользователем объектов.
В разделах, имеющих светло-голубую рамку слева, обсуждаются концепции, которые в основном относятся только к ORM. Пользователи только Core могут их пропустить.
Раздел, который имеет светлые и темные границы с обеих сторон, будет обсуждать основную концепцию, которая также явно используется в ORM.
Обзор учебника¶
В учебнике обе концепции будут представлены в том естественном порядке, в котором их следует изучать: сначала в основном подход, ориентированный на Core, а затем перейдем к концепциям, более ориентированным на ORM.
Основные разделы этого учебника следующие:
Установление связи - двигатель - все приложения SQLAlchemy начинаются с объекта
Engine
; вот как его создать.Работа с транзакциями и DBAPI - здесь представлен API использования
Engine
и связанных с ним объектовConnection
иResult
. Это содержание ориентировано на Core, однако пользователи ORM захотят ознакомиться хотя бы с объектомResult
.Работа с метаданными базы данных - Абстракции SQL в SQLAlchemy, а также ORM полагаются на систему определения конструкций схемы базы данных как объектов Python. В этом разделе рассказывается, как это сделать как с точки зрения Core, так и с точки зрения ORM.
Работа с данными - здесь мы узнаем, как создавать, выбирать, обновлять и удалять данные в базе данных. Так называемые операции CRUD здесь даются в терминах SQLAlchemy Core со ссылками на их ORM-аналоги. Операция SELECT, которая подробно представлена в Выбор строк с помощью ядра или ORM, одинаково хорошо применима как к Core, так и к ORM.
Манипулирование данными с помощью ORM охватывает структуру персистентности ORM; в основном, ORM-ориентированные способы вставки, обновления и удаления, а также то, как обрабатывать транзакции.
Работа со связанными объектами вводит понятие конструкции
relationship()
и дает краткий обзор того, как она используется, со ссылками на более подробную документацию.Дальнейшее чтение перечисляет ряд основных разделов документации верхнего уровня, которые полностью документируют концепции, представленные в этом учебнике.
Проверка версии¶
Этот учебник написан с использованием системы под названием doctest. Все фрагменты кода, написанные с использованием >>>
, на самом деле выполняются как часть тестового пакета SQLAlchemy, и читателю предлагается поработать с приведенными примерами кода в реальном времени с помощью собственного интерпретатора Python.
При выполнении примеров читателю рекомендуется выполнить быструю проверку, чтобы убедиться, что мы находимся на версии 1.4 SQLAlchemy:
>>> import sqlalchemy
>>> sqlalchemy.__version__
1.4.0
Заметка о будущем¶
В этом руководстве описывается новый API, появившийся в SQLAlchemy 1.4, известный как 2.0 style. Цель API в стиле 2.0 - обеспечить совместимость с SQLAlchemy 2.0, который планируется как следующее поколение SQLAlchemy.
Для обеспечения полного API 2.0 будет использоваться новый флаг future
, который будет появляться по мере описания в учебнике объектов Engine
и Session
. Эти флаги полностью включают режим совместимости с 2.0 и позволяют полностью продолжить работу с кодом в учебнике. При использовании флага future
с функцией create_engine()
возвращаемый объект является подклассом sqlalchemy.engine.Engine
, описанным как sqlalchemy.future.Engine
. В данном учебнике будет использоваться sqlalchemy.future.Engine
.