概述¶
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 引擎、连接和池服务也在这里描述。
代码示例¶
SQLAlchemy 分发包中包含了工作代码示例，主要涉及 ORM。所有包含的示例应用程序的描述请参见 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 - 主要迁移指南。
