SQLAlchemy 统一教程

关于本文档

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

已经熟悉 SQLAlchemy 的用户，特别是那些希望迁移现有应用程序以在 1.4 过渡阶段的 SQLAlchemy 2.0 系列下工作的用户，应该查看 SQLAlchemy 2.0 - 主要迁移指南 文档。

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

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

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

主要为 Core-only 的章节不会提及 ORM。在这些章节中使用的 SQLAlchemy 构造将从 sqlalchemy 命名空间导入。作为主题分类的额外指示，它们还将在右侧包含深蓝色边框。当使用 ORM 时，这些概念仍然在起作用，但在用户代码中不常显式出现。ORM 用户应该阅读这些章节，但不希望直接为以 ORM 为中心的代码使用这些 API。

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

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

本教程中的 大多数 章节讨论 Core 概念，这些概念也明确地与 ORM 一起使用。特别是 SQLAlchemy 2.0 在 ORM 中具有更高程度的 Core API 使用集成。

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

教程概览

本教程将以自然的学习顺序呈现概念，首先采用主要以 Core 为中心的方法，然后扩展到更多以 ORM 为中心的概念。

本教程的主要章节如下

  • 建立连接 - 引擎 - 所有 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 为中心的方式来插入、更新和删除，以及如何处理事务。

  • 使用 ORM 相关对象 介绍了 relationship() 构造的概念，并简要概述了其用法，并链接到更深入的文档。

  • 进一步阅读 列出了一系列主要的顶级文档部分，这些部分完整地记录了本教程中介绍的概念。

版本检查

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

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

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