概述¶
SQLAlchemy SQL Toolkit 和 Object Relational Mapper 是一套用于处理数据库和 Python 的综合工具。它有几个不同的功能区域，可以单独使用，也可以组合使用。它的主要组件如下所示，组件依赖项分为多个层：
在上面，SQLAlchemy 的两个最重要的正面部分是对象关系映射器 （ORM） 和
核心。
Core 包含 SQLAlchemy 的 SQL 和数据库集成及描述服务的广度，其中最突出的部分是 SQL 表达式语言。
SQL 表达式语言本身就是一个独立于 ORM 包的工具包，ORM 包提供了一个构建由可组合对象表示的 SQL 表达式的系统，然后可以在特定事务范围内针对目标数据库“执行”这些表达式，并返回结果集。插入、更新和删除（即 DML）是通过传递表示这些语句的 SQL 表达式对象以及表示要用于每个语句的参数的字典来实现的。
ORM 构建在 Core 之上，提供了一种使用映射到数据库模式的域对象模型的方法。当使用 ORM 时，SQL 语句的构造方式与使用 Core 时大致相同，但是 DML 的任务（这里指的是数据库中业务对象的持久性）是使用一种称为工作单元的模式自动完成的，该模式将针对可变对象的状态更改转换为 INSERT、UPDATE 和 DELETE 结构，然后根据这些对象调用这些结构。特定于 ORM 的自动化和以对象为中心的查询功能还增强了 SELECT 语句。
使用 Core 和 SQL 表达式语言提供了一个以模式为中心的数据库视图，以及一个面向不可变性的编程范式，而 ORM 则在此基础上构建了一个以域为中心的数据库视图，其编程范式更明确地面向对象并依赖于可变性。由于关系数据库本身就是一个可变服务，区别在于 Core/SQL 表达式语言是面向命令的，而 ORM 是面向状态的。
文档概述¶
该文档分为四个部分：
SQLAlchemy Unified Tutorial - 这个 SQLAlchemy 1.4/2.0 系列的全新教程全面介绍了整个库，从核心的描述开始，越来越多地转向 ORM 特定的概念。新用户以及来自 SQLAlchemy 的 1.x 系列的用户都应该从这里开始。
SQLAlchemy ORM - 在本节中，将介绍 ORM 的参考文档。
SQLAlchemy Core - 这里提供了 Core 中所有其他内容的参考文档。此处还介绍了 SQLAlchemy 引擎、连接和池服务。
代码示例¶
工作代码示例（主要与 ORM 有关）包含在 SQLAlchemy 发行版中。ORM Examples中提供了所有包含的示例应用程序的描述。
还有各种各样的示例涉及核心 SQLAlchemy
结构以及 wiki 上的 ORM。 看
Theatrum Chemicum.
安装指南¶
支持的平台¶
SQLAlchemy 支持以下平台：
cPython 3.7 及更高版本
PyPy 的 Python-3 兼容版本
在 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 扩展，这些扩展在各个领域中提供了额外的速度提升，目前强调核心结果集的速度。
在 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 环境变量。这种情况的用例要么用于特殊测试环境，要么在通常的 “rebuild” 机制无法克服的兼容性/构建问题的罕见情况下：
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 - 主要迁移指南。