SQLAlchemy 2.0 文档
- 上一篇: 目录
- 下一篇: SQLAlchemy 统一教程
- 向上: 首页
- 本页目录
概述¶
SQLAlchemy SQL 工具包和对象关系映射器是一套全面的工具,用于处理数据库和 Python。它有几个不同的功能领域,可以单独使用或组合使用。其主要组件如下所示,组件依赖关系按层组织

上面,SQLAlchemy 最重要的两个面向前端的部分是 对象关系映射器 (ORM) 和 Core。
Core 包含 SQLAlchemy 的 SQL 和数据库集成及描述服务的广度,其中最突出的部分是 SQL 表达式语言。
SQL 表达式语言本身就是一个工具包,独立于 ORM 包,它提供了一个构建 SQL 表达式的系统,这些表达式由可组合的对象表示,然后可以在特定事务的范围内“执行”以针对目标数据库,并返回结果集。插入、更新和删除(即 DML)是通过传递表示这些语句的 SQL 表达式对象以及表示每个语句要使用的参数的字典来实现的。
ORM 构建在 Core 之上,提供了一种使用映射到数据库模式的域对象模型的方法。当使用 ORM 时,SQL 语句的构造方式与使用 Core 时基本相同,但是 DML 的任务(这里指的是业务对象在数据库中的持久性)使用称为 工作单元 的模式自动化,该模式将可变对象的状态更改转换为 INSERT、UPDATE 和 DELETE 构造,然后根据这些对象调用这些构造。SELECT 语句也通过 ORM 特定的自动化和以对象为中心的查询功能得到增强。
与使用 Core 和 SQL 表达式语言呈现以模式为中心的数据库视图以及以不变性为导向的编程范例相反,ORM 在此基础上构建了以域为中心的数据库视图,编程范例更明确地以面向对象和依赖可变性。由于关系数据库本身是一种可变服务,因此区别在于 Core/SQL 表达式语言是面向命令的,而 ORM 是面向状态的。
文档概述¶
文档分为四个部分
SQLAlchemy 统一教程 - 这个全新的 SQLAlchemy 1.4/2.0 系列教程整体介绍了整个库,从 Core 的描述开始,逐步深入到 ORM 特定的概念。新用户以及来自 SQLAlchemy 1.x 系列的用户应该从这里开始。
SQLAlchemy ORM - 在本节中,介绍了 ORM 的参考文档。
SQLAlchemy Core - 在这里,介绍了 Core 中所有其他内容的参考文档。SQLAlchemy 引擎、连接和连接池服务也在此处描述。
代码示例¶
工作代码示例(主要关于 ORM)包含在 SQLAlchemy 发行包中。所有包含的示例应用程序的描述位于 ORM 示例。
wiki 上还有各种各样的示例,涉及核心 SQLAlchemy 构造以及 ORM。请参阅 Theatrum Chemicum。
安装指南¶
支持的平台¶
SQLAlchemy 支持以下平台
cPython 3.7 及更高版本
Python-3 兼容版本的 PyPy
在版本 2.0 中更改: SQLAlchemy 现在以 Python 3.7 及更高版本为目标。
AsyncIO 支持¶
SQLAlchemy 的 asyncio
支持取决于 greenlet 项目。此依赖项默认安装在常见的机器平台上,但并非在所有架构上都受支持,也可能不会默认安装在不太常见的架构上。有关确保 asyncio 支持存在的更多详细信息,请参阅 Asyncio 平台安装说明(包括 Apple M1) 部分。
支持的安装方法¶
SQLAlchemy 的安装是通过基于 setuptools 的标准 Python 方法进行的,可以直接引用 setup.py
,也可以使用 pip 或其他与 setuptools 兼容的方法。
通过 pip 安装¶
当 pip
可用时,可以从 PyPI 下载发行包并一步安装
pip install SQLAlchemy
此命令将从 Python Cheese Shop 下载 SQLAlchemy 的最新发布版本,并将其安装到您的系统中。对于大多数常见平台,将下载 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 包。完整的手动构建如下所示
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy
# install cython
pip install cython
# optionally build Cython extensions ahead of install
python setup.py build_ext
# run the install
python setup.py install
源代码构建也可以使用 PEP 517 技术执行,例如使用 build
# cd into SQLAlchemy source distribution
cd path/to/sqlalchemy
# install build
pip install build
# build source / wheel dists
python -m build
如果由于未安装 Cython、缺少编译器或其他问题导致 Cython 扩展构建失败,则安装过程将输出警告消息,并在完成后重新运行不带 Cython 扩展的构建,报告最终状态。
要运行构建/安装而甚至不尝试编译 Cython 扩展,可以指定 DISABLE_SQLALCHEMY_CEXT
环境变量。这种情况的用例要么是用于特殊测试情况,要么是在罕见的兼容性/构建问题无法通过通常的“重建”机制克服的情况下。
export DISABLE_SQLALCHEMY_CEXT=1; python setup.py install
安装数据库 API¶
SQLAlchemy 旨在与为特定数据库构建的 DBAPI 实现一起运行,并包括对最流行数据库的支持。方言 中的各个数据库部分列举了每个数据库可用的 DBAPI,包括外部链接。
检查已安装的 SQLAlchemy 版本¶
本文档涵盖 SQLAlchemy 2.0 版本。如果您正在使用已安装 SQLAlchemy 的系统,请像这样从 Python 提示符检查版本
>>> import sqlalchemy
>>> sqlalchemy.__version__
2.0.0
下一步¶
安装 SQLAlchemy 后,新老用户都可以继续学习 SQLAlchemy 教程。
1.x 到 2.0 迁移¶
有关 SQLAlchemy 2.0 中发布的新 API 的说明,请访问 SQLAlchemy 2.0 - 主要迁移指南。
flambé! 龙和 The Alchemist 图像设计由 Rotem Yaari 创建并慷慨捐赠。
使用 Sphinx 7.2.6 创建。文档上次生成时间:2025 年 3 月 11 日星期二下午 02:40:17 EDT