SqlAlchemy 2.0 中文文档（一）（1）

原文：docs.sqlalchemy.org/en/20/contents.html

概述

原文：docs.sqlalchemy.org/en/20/intro.html

SQLAlchemy SQL 工具包和对象关系映射器是一套全面的用于处理数据库和 Python 的工具集。它有几个不同的功能区域，可以单独使用或组合在一起。其主要组件如下图所示，组件依赖关系组织成层次结构：

上面，SQLAlchemy 最重要的两个面向用户的部分是对象关系映射器（ORM）和核心（Core）。

核心部分包含了 SQLAlchemy 的 SQL 和数据库集成以及描述服务，其中最突出的部分是SQL 表达式语言。

SQL 表达式语言是一个独立于 ORM 包的工具包，它提供了一种构建  SQL 表达式的系统，这些表达式由可组合的对象表示，然后可以在特定事务范围内“执行”到目标数据库中，返回一个结果集。通过传递表示这些语句的  SQL 表达式对象以及表示要与每个语句一起使用的参数的字典，可以实现插入、更新和删除（即 DML）。

ORM 在 Core 的基础上构建了一种用于处理映射到数据库模式的域对象模型的手段。当使用  ORM 时，SQL 语句的构造方式与使用 Core 时基本相同，但 DML  任务（在这里指的是将业务对象持久化到数据库中）是使用一种称为工作单元的模式自动化的，该模式将可变对象的状态变化转换为 INSERT、UPDATE  和 DELETE 构造，并以这些对象的术语调用这些构造。SELECT 语句也通过 ORM 特定的自动化和对象中心的查询功能进行增强。

而使用 Core 和 SQL 表达式语言工作呈现了数据库的模式中心视图，以及以不可变性为导向的编程范式，ORM  在此基础上构建了一个更加明确面向对象的数据库领域视图，具有更多显式面向对象的编程范式，并依赖于可变性。由于关系型数据库本身是一个可变的服务，区别在于  Core/SQL 表达式语言是命令导向的，而 ORM 是状态导向的。

文档概览

文档分为四个部分：

• SQLAlchemy 统一教程 - 这个全新的教程适用于 1.4/2.0 系列的 SQLAlchemy，全面介绍了整个库，从 Core 的描述开始，逐渐深入到 ORM 特定的概念。新用户以及从 SQLAlchemy 1.x 系列转来的用户应该从这里开始。
  
• SQLAlchemy ORM - 在这一部分中，提供了 ORM 的参考文档。
  
• SQLAlchemy 核心 - 这里提供了 Core 中的其他所有内容的参考文档。SQLAlchemy 引擎、连接和池服务也在这里描述。
  
• 方言 - 提供所有 方言 实现的参考文档，包括 DBAPI 具体内容。
  

代码示例

SQLAlchemy 分发包含可用于大多数 ORM 的工作代码示例。所有包含的示例应用程序的描述位于 ORM 示例。

在 wiki 上还有各种各样的示例，涉及到核心 SQLAlchemy 结构以及 ORM。请参阅 Theatrum Chemicum。

安装指南

支持的平台

SQLAlchemy 支持以下平台：

• cPython 3.7 及更高版本
  
• 兼容 Python-3 的 PyPy 版本
  

从 2.0 版本开始更改：SQLAlchemy 现在的目标是 Python 3.7 及以上版本。

异步 IO 支持

SQLAlchemy 的 asyncio 支持依赖于 greenlet 项目。这个依赖关系将默认安装在常见的机器平台上，但不支持每个架构，并且在不常见的架构上也可能不会默认安装。请参阅 异步 IO 平台安装说明（包括 Apple M1） 部分，了解确保存在 asyncio 支持的额外详细信息。

支持的安装方法

SQLAlchemy 的安装是通过基于 setuptools 的标准 Python 方法进行的，可以直接引用 setup.py 或使用 pip 或其他兼容 setuptools 的方法。

通过 pip 安装

当 pip 可用时，可以从 PyPI 下载分发包，并在一步中进行安装：

pip install SQLAlchemy

此命令将从 Python Cheese Shop 下载最新的发布版本的 SQLAlchemy 并安装到您的系统上。对于大多数常见平台，将下载提供原生 Cython / C 扩展的 Python Wheel 文件。

要安装最新的预发行版本，例如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 - 主要迁移指南 这里找到关于 SQLAlchemy 2.0 新 API 的说明。

文档分为四个部分：

• SQLAlchemy 统一教程 - 这个全新的针对 1.4/2.0 系列 SQLAlchemy 的教程从 Core 的描述开始，逐渐深入 ORM 特定的概念。 新用户以及从 SQLAlchemy 1.x 系列转来的用户应该从这里开始。
  
• SQLAlchemy ORM - 本节介绍了 ORM 的参考文档。
  
• SQLAlchemy 核心 - 这里提供了核心内的其他所有内容的参考文档。SQLAlchemy 引擎、连接和池服务也在此处描述。
  
• 方言 - 提供了所有 方言 实现的参考文档，包括 DBAPI 具体细节。
  

代码示例

SQLAlchemy 分发包中包含了工作代码示例，主要涉及 ORM。所有包含的示例应用的描述请参阅 ORM 示例。

还有许多涉及核心 SQLAlchemy 构造和 ORM 的示例在维基上。请参阅 炼金剧场。

安装指南

支持的平台

SQLAlchemy 支持以下平台：

• cPython 3.7 及更高版本
  
• PyPy 的 Python-3 兼容版本
  

从版本 2.0 开始更改：SQLAlchemy 现在面向 Python 3.7 及以上版本。

异步 IO 支持

SQLAlchemy 的 asyncio 支持取决于 greenlet 项目。此依赖项默认情况下会安装在常见的机器平台上，但不支持每个体系结构，并且在不太常见的体系结构上也可能不会默认安装。有关确保存在 asyncio 支持的详细信息，请参阅 Asyncio 平台安装说明（包括 Apple M1） 部分。

支持的安装方法

SQLAlchemy 的安装是通过基于 setuptools 的标准 Python 方法进行的，可以直接参考 setup.py 或使用 pip 或其他与 setuptools 兼容的方法。

通过 pip 安装

当 pip 可用时，可以从 PyPI 下载分发包，并在一步中安装：

pip install SQLAlchemy

此命令将从 Python 奶酪商店 下载最新的已发布版本的 SQLAlchemy，并将其安装到您的系统上。对于大多数常见平台，将下载提供预构建的本机 Cython / C 扩展的 Python Wheel 文件。

为了安装最新的预发布版本，例如 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环境变量。 这种情况的用例要么是为了特殊的测试环境，要么是在通常的“重建”机制无法解决的兼容性/构建问题的情况下：

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 教程。

支持的平台

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，并将其安装到您的系统中。对于大多数常见平台，将下载提供本机 Cython / C 扩展预构建的 Python Wheel 文件。

为了安装最新的 预发布 版本，如 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 环境变量。这样做的用例是特殊测试情况，或者在通常的“重新构建”机制无法克服的兼容性/构建问题的罕见情况下：

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 - 主要迁移指南这里找到。

SQLAlchemy Unified Tutorial

原文：docs.sqlalchemy.org/en/20/tutorial/index.html

关于本文档

SQLAlchemy Unified Tutorial 在 SQLAlchemy 的 Core 和 ORM 组件之间集成，并作为  SQLAlchemy 整体的统一介绍。对于在 1.x 系列中使用 SQLAlchemy 的用户，在 2.0 风格下工作的用户，ORM 使用带有select()构造的 Core 风格查询，并且 Core 连接和 ORM 会话之间的事务语义是等效的。注意每个部分的蓝色边框样式，这将告诉您一个特定主题有多“ORM 式”！

对于已经熟悉 SQLAlchemy 的用户，特别是那些希望将现有应用程序迁移到 SQLAlchemy 2.0 系列下的 1.4 过渡阶段的用户，也应查看 SQLAlchemy 2.0 - 重大迁移指南文档。

对于新手来说，这份文档包含大量细节，但到最后他们将被视为炼金术士。

SQLAlchemy 被呈现为两个不同的 API，一个建立在另一个之上。这些 API 被称为Core和ORM。

SQLAlchemy Core是 SQLAlchemy 作为“数据库工具包”的基础架构。该库提供了管理与数据库的连接、与数据库查询和结果的交互以及 SQL 语句的编程构造的工具。

主要仅 Core的部分不会提到 ORM。在这些部分中使用的 SQLAlchemy 构造将从sqlalchemy命名空间导入。作为主题分类的另一个指示符，它们还将在右侧包括一个深蓝色边框。在使用 ORM 时，这些概念仍然存在，但在用户代码中不太明显。ORM 用户应阅读这些部分，但不要期望直接使用这些 API 来编写 ORM 中心的代码。

SQLAlchemy ORM建立在 Core 之上，提供了可选的对象关系映射功能。ORM 提供了一个额外的配置层，允许用户定义的 Python 类被映射到数据库表和其他构造，以及一个称为Session的对象持久性机制。然后，它扩展了 Core 级别的 SQL 表达语言，允许以用户定义的对象的术语来组合和调用 SQL 查询。

主要仅 ORM的部分应该标题包含“ORM”短语，以便清楚地表明这是一个与 ORM 相关的主题。在这些部分中使用的 SQLAlchemy 构造将从sqlalchemy.orm命名空间导入。最后，作为主题分类的另一个指示符，它们还将在左侧包括一个浅蓝色边框。仅 Core 的用户可以跳过这些部分。

大多数本教程中的部分都讨论了与 ORM 明确使用的核心概念。特别是 SQLAlchemy 2.0 在 ORM 中更大程度地整合了核心 API 的使用。

对于这些部分的每一个，都会有介绍性文本讨论 ORM 用户应该期望使用这些编程模式的程度。这些部分中的 SQLAlchemy 构造将从sqlalchemy命名空间中导入，同时可能会使用一些sqlalchemy.orm构造。作为主题分类的额外指示，这些部分还将在左侧具有较薄的浅色边框，并在右侧具有较粗的深色边框。核心和 ORM 用户应该同样熟悉这些部分的概念。

教程概述

教程将以应该学习的自然顺序呈现这两个概念，首先是以主要基于核心的方式，然后扩展到更多的 ORM 中心的概念。

本教程的主要部分如下：

• 建立连接 - Engine - 所有的 SQLAlchemy 应用都以一个Engine对象开始；这是如何创建一个的方法。
  
• 处理事务和 DBAPI - 此处介绍了Engine及其相关对象Connection和Result的使用 API。此内容是核心为中心的，但 ORM 用户至少应熟悉Result对象。
  
• 处理数据库元数据 - SQLAlchemy 的 SQL 抽象以及 ORM 都依赖于将数据库模式构造定义为 Python 对象的系统。本节介绍了如何从核心和 ORM 的角度进行操作。
  
• 处理数据 - 在这里我们学习如何在数据库中创建、选择、更新和删除数据。这里所谓的 CRUD 操作以 SQLAlchemy 核心的形式给出，并链接到其 ORM 对应项。在使用 SELECT 语句中详细介绍的 SELECT 操作同样适用于核心和 ORM。
  
• 使用 ORM 进行数据操作 - 涵盖了 ORM 的持久化框架；基本上是 ORM 为中心的插入、更新和删除的方式，以及如何处理事务。
  
• 处理 ORM 相关对象介绍了 relationship() 构造的概念，并简要概述了其用法，并提供了链接到更深入文档的链接。
  
• 进一步阅读 列出了一系列完全记录了本教程介绍的概念的顶级文档部分。
  

版本检查

本教程是使用称为 doctest 的系统编写的。所有带有 >>> 的代码摘录实际上都作为 SQLAlchemy 的测试套件的一部分运行，并且读者被邀请使用他们自己的 Python 解释器实时处理给定的代码示例。

如果运行示例，建议读者执行快速检查以验证我们在 版本 2.0 的 SQLAlchemy 上：

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

教程概述

本教程将按照应该学习的自然顺序呈现这两个概念，首先是基本的 Core 方法，然后扩展到更多的 ORM 方法。

本教程的主要部分如下：

• 建立连接 - Engine - 所有的 SQLAlchemy 应用程序都始于一个 Engine 对象；这里介绍如何创建一个。
  
• 处理事务和 DBAPI - 这里介绍了 Engine 及其相关对象 Connection 和 Result 的使用 API。这部分内容主要围绕 Core，但 ORM 用户至少要熟悉 Result 对象。
  
• 处理数据库元数据 - SQLAlchemy 的 SQL 抽象以及 ORM 都依赖于将数据库模式构造定义为 Python 对象的系统。本节介绍了如何从 Core 和 ORM 的角度来做到这一点。
  
• 处理数据  - 这里我们学习如何在数据库中创建、选择、更新和删除数据。这里所谓的 CRUD 操作以 SQLAlchemy Core 的术语给出，并链接到其  ORM 对应项。在 使用 SELECT 语句 中详细介绍的 SELECT 操作同样适用于 Core 和 ORM。
  
• 使用 ORM 进行数据操作涵盖了 ORM 的持久性框架；基本上是 ORM-centric 的插入、更新和删除方式，以及如何处理事务。
  
• 使用 ORM 相关对象介绍了relationship()构造的概念，并简要介绍了它的用法，并提供了更深入文档的链接。
  
• 进一步阅读列出了一系列主要的顶级文档部分，这些部分完全记录了本教程中介绍的概念。
  

版本检查

本教程是使用名为doctest的系统编写的。 所有使用>>>编写的代码摘录实际上都作为 SQLAlchemy 测试套件的一部分运行，并且读者被邀请实时使用自己的 Python 解释器与给出的代码示例一起工作。

如果运行示例，则建议读者进行快速检查以验证我们使用的是2.0 版本的 SQLAlchemy：

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

版本检查

本教程是使用名为doctest的系统编写的。 所有使用>>>编写的代码摘录实际上都作为 SQLAlchemy 测试套件的一部分运行，并且读者被邀请实时使用自己的 Python 解释器与给出的代码示例一起工作。

如果运行示例，则建议读者进行快速检查以验证我们使用的是2.0 版本的 SQLAlchemy：

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

建立连接 - Engine

原文：docs.sqlalchemy.org/en/20/tutorial/engine.html

欢迎 ORM 和 Core 读者！

每一个连接到数据库的 SQLAlchemy 应用程序都需要使用一个 Engine。这个简短的部分适用于所有人。

任何 SQLAlchemy 应用程序的起点是一个称为Engine  的对象。这个对象充当连接到特定数据库的连接的中心来源，提供了一个工厂以及一个称为连接池的保持空间，用于这些数据库连接。该引擎通常是一个全局对象，仅为特定数据库服务器创建一次，并且使用  URL 字符串进行配置，该字符串将描述它应该如何连接到数据库主机或后端。

为了本教程，我们将使用内存中的 SQLite 数据库。这是一个方便的测试方法，无需设置实际的预先存在的数据库。通过使用create_engine() 函数创建 Engine：

>>> from sqlalchemy import create_engine
>>> engine = create_engine("sqlite+pysqlite:///:memory:", echo=True)

create_engine 的主要参数是一个字符串 URL，上面传递的字符串是 "sqlite+pysqlite:///:memory:"。这个字符串向 Engine 指示了三个重要的事实：

1. 我们正在与什么样的数据库通信？上面的 sqlite 部分连接了 SQLAlchemy 到一个称为方言的对象。
   
2. 我们正在使用什么 DBAPI？Python DBAPI 是 SQLAlchemy 用来与特定数据库交互的第三方驱动程序。在这种情况下，我们使用的是 pysqlite，在现代 Python 中，它是 SQLite 的sqlite3 标准库接口。如果省略，则 SQLAlchemy 将使用特定数据库的默认 DBAPI。
   
3. 我们如何定位数据库？在这种情况下，我们的 URL 包含短语 /:memory:，这是对 sqlite3 模块的一个指示，表明我们将使用一个仅存在于内存中的数据库。这种类型的数据库非常适合用于实验，因为它不需要任何服务器，也不需要创建新文件。
   

我们还指定了一个参数create_engine.echo，它将指示Engine将其发出的所有 SQL 记录到一个 Python 日志记录器，该记录器将写入标准输出。此标志是一种更正式设置 Python 日志记录的简便方式，并且对于脚本中的实验很有用。许多 SQL 示例将包括此 SQL 日志输出，在点击 [SQL] 链接后，将显示完整的 SQL 交互。

处理事务和 DBAPI

原文：docs.sqlalchemy.org/en/20/tutorial/dbapi_transactions.html

准备好的Engine 对象后，我们现在可以继续深入探讨 Engine 的基本操作及其主要交互端点，即 Connection 和 Result。我们还将介绍 ORM 对这些对象的门面，称为 Session。

ORM 读者注意

使用 ORM 时，Engine 由另一个称为 Session 的对象管理。现代 SQLAlchemy 中的 Session 强调的是一种事务性和 SQL 执行模式，它与下面讨论的 Connection 的模式基本相同，因此，虽然本小节是以核心为中心的，但这里的所有概念基本上都与 ORM 使用相关，并且建议所有 ORM 学习者阅读。Connection 使用的执行模式将在本节末尾与 Session 的模式进行对比。

由于我们尚未介绍 SQLAlchemy 表达语言，这是 SQLAlchemy 的主要特性，我们将利用该软件包中的一个简单构造，称为text() 构造，它允许我们以文本 SQL的形式编写 SQL 语句。请放心，在日常使用 SQLAlchemy 时，文本 SQL 绝大多数情况下都是例外而不是规则，即使如此，它仍然始终完全可用。

获取连接

Engine对象从用户角度看唯一的目的是提供称为Connection的数据库连接单元。当直接使用核心时，与数据库的所有交互都是通过Connection对象完成的。由于Connection代表着针对数据库的一个开放资源，我们希望始终将对此对象的使用范围限制在特定的上下文中，而使用 Python 上下文管理器形式，也称为with 语句是这样做的最佳方式。下面我们使用文本 SQL 语句说明“Hello World”。文本 SQL 使用一个叫做text()的构造发出，稍后将更详细地讨论：

>>> from sqlalchemy import text
>>> with engine.connect() as conn:
...     result = conn.execute(text("select 'hello world'"))
...     print(result.all())
BEGIN  (implicit)
select  'hello world'
[...]  ()
[('hello world',)]
ROLLBACK 

在上面的示例中，为数据库连接提供了上下文管理器，并将操作放在事务内。Python DBAPI 的默认行为包括事务始终处于进行中；当连接的范围被释放时，会发出 ROLLBACK 以结束事务。事务不会自动提交；当我们想要提交数据时，通常需要调用Connection.commit()，我们将在下一节中看到。

提示

“自动提交”模式适用于特殊情况。章节设置事务隔离级别，包括 DBAPI 自动提交讨论了这一点。

我们的 SELECT 的结果也以一个叫做Result的对象返回，稍后将讨论，但是暂时我们将添加这样一句，最好确保在“connect”块内消耗此对象，并且不要在连接范围之外传递。## 提交更改

我们刚刚学到 DBAPI 连接是非自动提交的。如果我们想提交一些数据怎么办？我们可以修改我们上面的示例来创建一个表并插入一些数据，然后使用Connection.commit()方法在我们获取Connection对象的块内调用进行事务提交：

# "commit as you go"
>>> with engine.connect() as conn:
...     conn.execute(text("CREATE TABLE some_table (x int, y int)"))
...     conn.execute(
...         text("INSERT INTO some_table (x, y) VALUES (:x, :y)"),
...         [{"x": 1, "y": 1}, {"x": 2, "y": 4}],
...     )
...     conn.commit()
BEGIN  (implicit)
CREATE  TABLE  some_table  (x  int,  y  int)
[...]  ()
<sqlalchemy.engine.cursor.CursorResult  object  at  0x...>
INSERT  INTO  some_table  (x,  y)  VALUES  (?,  ?)
[...]  [(1,  1),  (2,  4)]
<sqlalchemy.engine.cursor.CursorResult  object  at  0x...>
COMMIT 

在上面，我们发出了两个通常是事务性的 SQL 语句，“CREATE TABLE”语句[1]和一个参数化的“INSERT”语句（上面的参数化语法在发送多个参数中讨论）。由于我们希望我们所做的工作在我们的块内被提交，我们调用Connection.commit()方法来提交事务。在块内调用此方法后，我们可以继续运行更多的 SQL 语句，如果选择的话，我们可以再次调用Connection.commit()来进行后续语句的提交。SQLAlchemy 将这种风格称为边提交边进行。

还有另一种提交数据的风格，即我们可以事先将我们的“connect”块声明为事务块。在这种操作模式下，我们使用Engine.begin()方法来获取连接，而不是使用Engine.connect()方法。这种方法既管理了Connection的范围，也在事务结束时包含了 COMMIT，假设块成功，或者在出现异常时回滚。这种风格被称为一次性开始：

# "begin once"
>>> with engine.begin() as conn:
...     conn.execute(
...         text("INSERT INTO some_table (x, y) VALUES (:x, :y)"),
...         [{"x": 6, "y": 8}, {"x": 9, "y": 10}],
...     )
BEGIN  (implicit)
INSERT  INTO  some_table  (x,  y)  VALUES  (?,  ?)
[...]  [(6,  8),  (9,  10)]
<sqlalchemy.engine.cursor.CursorResult  object  at  0x...>
COMMIT 

“一次性开始”风格通常更受青睐，因为它更简洁，并且事先指示整个块的意图。然而，在本教程中，我们通常会使用“边提交边进行”风格，因为这样更灵活，适合演示目的。## 语句执行的基础知识

我们已经看到了一些例子，针对数据库运行 SQL 语句，利用了一个叫做Connection.execute()的方法，结合一个叫做text()的对象，并返回一个叫做Result的对象。在本节中，我们将更详细地说明这些组件的机制和交互。

当使用 Session.execute() 方法时，本节大部分内容同样适用于现代 ORM 的使用，其工作原理与 Connection.execute() 非常相似，包括 ORM 结果行使用的是与 Core 相同的 Result 接口来传递。

SqlAlchemy 2.0 中文文档（一）（2）https://developer.aliyun.com/article/1563202