SQLAlchemy Единое Руководство

Единое руководство SQLAlchemy интегрирует компоненты Core и ORM библиотеки SQLAlchemy и служит единым введением в SQLAlchemy в целом. Для пользователей SQLAlchemy версии 1.x важно знать, что в стиле работы 2.0 ORM использует запросы в стиле Core с конструкцией select(), а транзакционная семантика между Core-соединениями и ORM-сессиями эквивалентна.

Пользователям, уже знакомым с SQLAlchemy, и особенно тем, кто хочет мигрировать существующие приложения для работы с серией SQLAlchemy 2.0 в переходной фазе 1.4, следует также ознакомиться с документом SQLAlchemy 2.0 - Major Migration Guide.

Для новичков этот документ содержит много деталей, однако к концу они будут считаться настоящими алхимиками.

SQLAlchemy представлен как два отдельных API, один из которых построен поверх другого. Эти API известны как Core и ORM.

SQLAlchemy Core — это базовая архитектура SQLAlchemy как “инструментария для работы с базами данных”. Библиотека предоставляет инструменты для управления подключением к базе данных, взаимодействия с запросами и результатами, а также программного построения SQL-выражений.

SQLAlchemy ORM строится поверх Core и предоставляет дополнительные возможности объектно-реляционного отображения. ORM обеспечивает дополнительный конфигурационный слой, позволяющий отображать пользовательские Python-классы на таблицы базы данных и другие конструкции, а также механизм сохранения объектов, известный как Session. Затем он расширяет язык SQL-выражений уровня Core, позволяя составлять и выполнять SQL-запросы в терминах пользовательских объектов.

Большинство секций в этом руководстве обсуждают концепции Core, которые также явно используются с ORM. SQLAlchemy 2.0, в частности, демонстрирует гораздо более высокий уровень интеграции использования Core API в ORM.

Обзор руководства

Руководство представит обе концепции в естественном порядке их изучения, начиная с преимущественно Core-ориентированного подхода, а затем расширяясь в более ORM-ориентированные концепции.

Основные разделы этого руководства следующие:

• Establishing Connectivity - the Engine — все приложения SQLAlchemy начинаются с объекта Engine; здесь показано, как его создать.

• Working with Transactions and the DBAPI — здесь представлен API использования Engine и связанных с ним объектов Connection и Result. Этот контент Core-ориентирован, однако пользователи ORM захотят быть знакомыми как минимум с объектом Result.

• Working with Database Metadata — SQL-абстракции SQLAlchemy, а также ORM опираются на систему определения конструкций схемы базы данных как Python-объектов. Этот раздел представляет, как это делать как с точки зрения Core, так и ORM.

• Working with Data — здесь мы учимся создавать, выбирать, обновлять и удалять данные в базе данных. Так называемые CRUD-операции здесь представлены в терминах SQLAlchemy Core со ссылками на их ORM-аналоги. Операция SELECT, которая подробно представлена в Using SELECT Statements, одинаково хорошо применима как к Core, так и к ORM.

• Data Manipulation with the ORM охватывает фреймворк персистентности ORM; в основном, ORM-ориентированные способы вставки, обновления и удаления, а также обработки транзакций.

• Working with ORM Related Objects представляет концепцию конструкции relationship() и даёт краткий обзор того, как она используется, со ссылками на более глубокую документацию.

• Further Reading перечисляет серию основных разделов документации верхнего уровня, которые полностью документируют концепции, представленные в этом руководстве.

Проверка версии

Это руководство написано с использованием системы под названием doctest. Все фрагменты кода, написанные с >>>, фактически выполняются как часть тестового набора SQLAlchemy, и читателю предлагается работать с примерами кода в реальном времени со своим собственным интерпретатором Python.

При выполнении примеров рекомендуется, чтобы читатель выполнил быструю проверку, чтобы убедиться, что используется версия 2.0 SQLAlchemy:

>>> import sqlalchemy
>>> sqlalchemy.__version__
'2.0.0'