Обзор¶
SQLAlchemy SQL Toolkit и Object Relational Mapper - это полный набор инструментов для работы с базами данных и Python. В нем есть несколько отдельных функциональных областей, которые можно использовать по отдельности или комбинировать вместе. Его основные компоненты показаны ниже, а зависимости компонентов организованы в слои:
Две наиболее значимые части SQLAlchemy - это Object Relational Mapper (ORM) и Core.
Core содержит широкий спектр услуг SQLAlchemy по интеграции и описанию SQL и баз данных, наиболее заметной частью которых является SQL Expression Language.
Язык выражений SQL - это самостоятельный инструментарий, независимый от пакета ORM, который обеспечивает систему построения выражений SQL, представленных в виде составных объектов, которые затем могут быть «выполнены» против целевой базы данных в рамках определенной транзакции, возвращая набор результатов. Вставки, обновления и удаления (т.е. DML) достигаются путем передачи объектов SQL-выражений, представляющих эти операторы, вместе со словарями, представляющими параметры для использования с каждым оператором.
ORM основывается на Core и предоставляет средства для работы с объектной моделью домена, сопоставленной со схемой базы данных. При использовании ORM операторы SQL строятся в основном так же, как и при использовании Core, однако задача DML, которая здесь относится к сохранению бизнес-объектов в базе данных, автоматизируется с помощью паттерна unit of work, который переводит изменения состояния в отношении изменяемых объектов в конструкции INSERT, UPDATE и DELETE, которые затем вызываются в терминах этих объектов. Операторы SELECT также дополнены специфическими для ORM автоматизациями и возможностями объектно-ориентированных запросов.
Если работа с Core и языком SQL Expression представляет схемно-ориентированное представление базы данных, а также парадигму программирования, ориентированную на неизменяемость, то ORM строит поверх этого доменно-ориентированное представление базы данных с парадигмой программирования, более явно объектно-ориентированной и полагающейся на изменяемость. Поскольку реляционная база данных сама по себе является изменяемым сервисом, разница заключается в том, что язык Core/SQL Expression ориентирован на команды, в то время как ORM ориентирован на состояние.
Обзор документации¶
Документация разделена на четыре раздела:
Самоучитель SQLAlchemy 1.4 / 2.0 - этот совершенно новый учебник для серии SQLAlchemy 1.4/2.0 представляет всю библиотеку в целом, начиная с описания Core и все больше и больше продвигаясь к специфическим концепциям ORM. Новым пользователям, а также пользователям, пришедшим из 1.x style и желающим работать в 2.0 style, следует начать именно с этого руководства.
SQLAlchemy ORM - В этом разделе представлена справочная документация по ORM; этот раздел также включает в себя ныне устаревший Объектно-реляционный учебник (API 1.x).
Ядро SQLAlchemy - Здесь представлена справочная документация для всего остального в Core; раздел также включает унаследованную Учебник по языку выражений SQL (API 1.x). Здесь также описываются движок SQLAlchemy, соединения и службы пула.
Диалекты - Предоставляет справочную документацию для всех реализаций dialect, включая специфику DBAPI.
Примеры кода¶
Примеры рабочего кода, в основном касающиеся ORM, включены в дистрибутив SQLAlchemy. Описание всех включенных примеров приложений находится по адресу Примеры ORM.
В вики также имеется большое количество примеров с использованием как основных конструкций SQLAlchemy, так и ORM. См. Theatrum Chemicum.
Руководство по установке¶
Поддерживаемые платформы¶
SQLAlchemy был протестирован на следующих платформах:
cPython 2.7
cPython 3.6 и выше
PyPy 2.1 или выше
Изменено в версии 1.4: В рамках серии Python 3, 3.6 теперь является минимально поддерживаемой версией Python 3.
Поддержка AsyncIO¶
Поддержка SQLAlchemy asyncio зависит от проекта greenlet. Эта зависимость будет установлена по умолчанию на распространенных машинных платформах, однако она поддерживается не на всех архитектурах, а также может не устанавливаться по умолчанию на менее распространенных архитектурах. Дополнительные сведения об обеспечении поддержки asyncio см. в разделе Примечания по установке платформы Asyncio (включая Apple M1).
Поддерживаемые методы установки¶
Установка SQLAlchemy осуществляется с помощью стандартных методик Python, основанных на setuptools, либо обращаясь непосредственно к setup.py, либо используя pip или другие совместимые с setuptools подходы.
Изменено в версии 1.1: setuptools теперь требуется файлом setup.py; простые установки distutils больше не поддерживаются.
Установите с помощью pip¶
Когда pip будет доступен, дистрибутив можно будет скачать с PyPI и установить в один шаг:
pip install SQLAlchemyЭта команда загрузит последнюю выпущенную версию SQLAlchemy с сайта Python Cheese Shop и установит ее в вашу систему.
Для установки последней предрелизной версии, такой как 1.4.0b1, pip требует использования флага --pre:
pip install --pre SQLAlchemyЕсли последняя версия является предварительной версией, то она будет установлена вместо последней выпущенной версии.
Установка с помощью setup.py¶
В противном случае вы можете установить из дистрибутива с помощью сценария setup.py:
python setup.py installУстановка расширений C¶
SQLAlchemy включает расширения на языке C, которые обеспечивают дополнительное увеличение скорости работы с наборами результатов. Расширения поддерживаются на cPython серий 2.xx и 3.xx.
setup.py автоматически соберет расширения, если будет обнаружена соответствующая платформа. Если сборка расширений C не удалась из-за отсутствия компилятора или других проблем, процесс установки выдаст предупреждение и повторно запустит сборку без расширений C по завершении, сообщив об окончательном состоянии.
Чтобы запустить сборку/установку без попытки компиляции расширений C, можно указать переменную окружения DISABLE_SQLALCHEMY_CEXT. Это может быть использовано либо для особых условий тестирования, либо в редких случаях, когда проблемы совместимости/сборки не преодолеваются обычным механизмом «пересборки»:
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py installИзменено в версии 1.1: Устаревший флаг --without-cextensions был удален из программы установки, поскольку он использует устаревшие возможности setuptools.
Установка API базы данных¶
SQLAlchemy предназначен для работы с DBAPI реализацией, созданной для конкретной базы данных, и включает поддержку наиболее популярных баз данных. В разделах Диалекты по отдельным базам данных перечислены доступные DBAPI для каждой базы данных, включая внешние ссылки.
Проверка установленной версии SQLAlchemy¶
Эта документация охватывает SQLAlchemy версии 1.4. Если вы работаете в системе, где уже установлен SQLAlchemy, проверьте версию из подсказки Python следующим образом:
>>> import sqlalchemy
>>> sqlalchemy.__version__
1.4.0Следующие шаги¶
Установив SQLAlchemy, как новые, так и старые пользователи могут Proceed to the SQLAlchemy Tutorial.
1.3 - 1.4 Миграция¶
Заметки о том, что изменилось с 1.3 на 1.4, доступны здесь What’s New in SQLAlchemy 1.4?.