Обзор SQLAlchemy

SQLAlchemy SQL Toolkit and Object Relational Mapper — это комплексный набор инструментов для работы с базами данных и Python. Он обладает несколькими функциональными возможностями, которые можно использовать по отдельности или комбинировать. Его основные компоненты показаны ниже, а зависимости компонентов организованы по уровням:

Архитектура SQLAlchemy

Выше показаны два наиболее значимых компонента SQLAlchemy — Object Relational Mapper (ORM) и Core.

Core содержит полный набор сервисов SQLAlchemy для интеграции с SQL и базами данных, а также для их описания. Наиболее заметной частью является SQL Expression Language.

SQL Expression Language — это самостоятельный инструментарий, независимый от пакета ORM, который предоставляет систему построения SQL-выражений, представленных композируемыми объектами. Эти объекты могут быть «выполнены» относительно целевой базы данных в рамках конкретной транзакции, возвращая набор результатов. Вставки, обновления и удаления (т.е. DML) выполняются путём передачи объектов SQL-выражений, представляющих эти операторы, вместе со словарями, которые содержат параметры для каждого оператора.

ORM строится поверх Core и предоставляет средства работы с моделью предметной области, отображённой на схему базы данных. При использовании ORM SQL-операторы конструируются практически так же, как и при использовании Core, однако задача выполнения DML — которая здесь относится к сохранению бизнес-объектов в базе данных — автоматизируется с помощью паттерна unit of work. Этот паттерн преобразует изменения состояния изменяемых объектов в конструкции INSERT, UPDATE и DELETE, которые затем выполняются в контексте этих объектов. SELECT-запросы также дополняются специфичными для ORM автоматизациями и объектно-ориентированными возможностями запросов.

В то время как работа с Core и SQL Expression Language представляет схемо-центричный взгляд на базу данных с парадигмой программирования, ориентированной на неизменяемость, ORM надстраивает поверх этого предметно-центричный взгляд с более явно объектно-ориентированной парадигмой программирования, опирающейся на изменяемость. Поскольку реляционная база данных сама по себе является изменяемым сервисом, разница заключается в том, что Core/SQL Expression Language ориентирован на команды, тогда как ORM ориентирован на состояние.

Обзор документации

Документация разделена на четыре раздела:

SQLAlchemy Unified Tutorial — этот совершенно новый учебник для серии 1.4/2.0 SQLAlchemy целостно представляет всю библиотеку, начиная с описания Core и постепенно переходя к концепциям, специфичным для ORM. Новым пользователям, а также пользователям, переходящим с серии 1.x SQLAlchemy, следует начать отсюда.
SQLAlchemy ORM — в этом разделе представлена справочная документация по ORM.
SQLAlchemy Core — здесь представлена справочная документация для всего остального в Core. Здесь также описаны движок SQLAlchemy, соединения и сервисы пулинга.
Dialects — предоставляет справочную документацию для всех реализаций диалектов, включая специфику DBAPI.

Примеры кода

Рабочие примеры кода, в основном касающиеся ORM, включены в дистрибутив SQLAlchemy. Описание всех включённых примеров приложений находится в разделе ORM Examples.

Также существует множество примеров, касающихся как базовых конструкций SQLAlchemy, так и ORM, на вики. См. Theatrum Chemicum.

Поддерживаемые платформы

SQLAlchemy поддерживает следующие платформы:

cPython 3.7 и выше
Python-3 совместимые версии PyPy

Изменено в версии 2.0: SQLAlchemy теперь ориентирован на Python 3.7 и выше.

Поддержка AsyncIO

Поддержка asyncio в SQLAlchemy зависит от проекта greenlet. Эта зависимость будет установлена по умолчанию на распространённых платформах, однако она поддерживается не на всех архитектурах и может не устанавливаться автоматически на менее распространённых архитектурах. См. раздел Asyncio Platform Installation Notes (Including Apple M1) для получения дополнительной информации об обеспечении поддержки asyncio.

Поддерживаемые методы установки

Установка SQLAlchemy осуществляется через стандартные методологии Python, основанные на setuptools, либо путём прямого обращения к setup.py, либо с использованием pip или других подходов, совместимых с setuptools.

Установка через pip

Когда pip доступен, дистрибутив можно загрузить с PyPI и установить в один шаг:

pip install SQLAlchemy

Эта команда загрузит последнюю выпущенную версию SQLAlchemy из Python Cheese Shop и установит её в вашу систему. Для большинства распространённых платформ будет загружен файл Python Wheel, который предоставляет нативные расширения Cython/C в предварительно собранном виде.

Чтобы установить последнюю предварительную версию, например 2.0.0b1, pip требует использования флага --pre:

pip install --pre SQLAlchemy

В этом случае, если самая свежая версия является предварительной, она будет установлена вместо последней стабильной версии.

Ручная установка из исходного дистрибутива

Если установка не производится через pip, исходный дистрибутив может быть установлен с помощью скрипта setup.py:

python setup.py install

Установка из исходников платформенно-независима и будет работать на любой платформе независимо от того, установлены ли инструменты сборки Cython/C или нет. Как подробно описано в следующем разделе «Сборка расширений Cython», setup.py попытается выполнить сборку с использованием Cython/C, если это возможно, но в противном случае откатится к чистой установке на Python.

Сборка расширений Cython

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

Изменено в версии 2.0: Расширения SQLAlchemy на C были переписаны с использованием Cython.

setup.py автоматически соберёт расширения, если обнаружена подходящая платформа, при условии установки пакета Cython. Полная ручная сборка выглядит так:

# перейдите в директорию исходного дистрибутива SQLAlchemy
cd path/to/sqlalchemy

# установите cython
pip install cython

# опционально соберите расширения Cython перед установкой
python setup.py build_ext

# запустите установку
python setup.py install

Сборка из исходников также может быть выполнена с использованием техник PEP 517, таких как использование build:

# перейдите в директорию исходного дистрибутива SQLAlchemy
cd path/to/sqlalchemy

# установите build
pip install build

# соберите исходный дистрибутив / wheel
python -m build

Если сборка расширений Cython завершится неудачей из-за отсутствия Cython, отсутствия компилятора или другой проблемы, процесс установки выведет предупреждающее сообщение и повторно запустит сборку без расширений Cython по завершении, сообщая окончательный статус.

Чтобы запустить сборку/установку даже не пытаясь скомпилировать расширения Cython, можно указать переменную окружения DISABLE_SQLALCHEMY_CEXT. Это используется либо для специальных целей тестирования, либо в редких случаях проблем совместимости/сборки, не решаемых обычным механизмом «пересборки»:

export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install

Установка Database API

SQLAlchemy разработан для работы с реализацией DBAPI, созданной для конкретной базы данных, и включает поддержку самых популярных баз данных. Отдельные разделы баз данных в Dialects перечисляют доступные DBAPI для каждой базы данных, включая внешние ссылки.

Проверка установленной версии SQLAlchemy

Эта документация охватывает SQLAlchemy версии 2.0. Если вы работаете в системе, где SQLAlchemy уже установлен, проверьте версию из командной строки Python следующим образом:

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

⬅️ Назад Вперед ➡️