SQLAlchemy 统一教程


关于本文档


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


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


对于新手来说，这份文件有很多细节，但是到最后他们将被视为炼金术士。


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


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


主要仅 Core 的部分将不会引用 ORM。 这些部分中使用的 SQLAlchemy 构造将从 sqlalchemy 命名空间。作为主题分类的附加指标，它们还将在右侧包含一个深蓝色边框。当使用 ORM 时，这些概念仍然存在，但在用户代码中不太明确。ORM 用户应该阅读这些部分，但不要指望直接将这些 API 用于以 ORM 为中心的代码。


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


主要仅限 ORM 的部分应命名为 包括短语 “ORM”，这样就可以清楚地知道这是一个与 ORM 相关的主题。 这些部分中使用的 SQLAlchemy 构造将从 sqlalchemy.orm 命名空间。最后，作为主题分类的附加指标，它们还将在 左。仅限 Core 的用户可以跳过这些作。


本教程中的大多数部分讨论的核心概念 也显式地与 ORM 一起使用。特别是 SQLAlchemy 2.0 在 ORM 中对核心 API 使用进行了更高级别的集成。


对于这些部分中的每一个，都将有介绍性文本讨论 ORM 用户应该期望使用这些编程的程度 模式。这些部分中的 SQLAlchemy 构造将从 sqlalchemy 命名空间，具有 sqlalchemy.orm 的一些潜在用途 构造。作为主题的附加指标 分类，这些部分还将包括较细的光源 左侧为边框，右侧为较粗的深色边框。Core 和 ORM 用户应该同样熟悉这些部分中的概念。


教程概述


本教程将按照应该学习的自然顺序介绍这两个概念，首先使用主要以 Core 为中心的方法，然后扩展到更多以 ORM 为中心的概念。


本教程的主要部分如下：


  • 建立连接 - 引擎 - 所有 SQLAlchemy 应用程序都以 Engine 对象;以下是创建一个的方法。


  • 使用事务和 DBAPI - 使用 API 的 Engine 及其相关对象连接 和 Result 在此处显示。此内容以 Core 为中心 但是，ORM 用户至少需要熟悉 Result 对象。


  • 使用数据库元数据 - SQLAlchemy 的 SQL 抽象以及 ORM 依赖于将数据库架构构造定义为 Python 对象的系统。本节从 Core 和 ORM 的角度介绍如何做到这一点。


  • 使用数据 - 在这里，我们学习如何在数据库中创建、选择、更新和删除数据。所谓的 CRUD 这里的作是根据 SQLAlchemy Core 给出的，并带有指向 它们的 ORM 对应物。 在 使用 SELECT 语句同样适用于 Core 和 ORM。


  • 使用 ORM 进行数据作 涵盖了 ORM 的持久化框架;基本上是以 ORM 为中心的插入、更新和删除方法，以及如何处理事务。


  • Working with ORM Related Objects 介绍了 relationship（） 结构，并简要概述了它的使用方式，并提供了指向更深入文档的链接。


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


版本检查


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


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

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