SQLAlchemy 统一教程

关于此文档

SQLAlchemy 统一教程将 SQLAlchemy 的 Core 和 ORM 组件整合在一起，作为对 SQLAlchemy 的整体介绍。对于 SQLAlchemy 1.x 系列的用户，在 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 的部分 不会涉及 ORM。这些部分中使用的 SQLAlchemy 结构将从 sqlalchemy 命名空间导入。作为主题分类的额外指示器，它们还将在 右侧包含一个深蓝色的边框。在使用 ORM 时，这些概念仍在发挥作用，但在用户代码中并不总是显式。ORM 用户应该阅读这些部分，但不要期望直接使用这些 API 来编写以 ORM 为中心的代码。

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

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

本教程中的 大多数 部分讨论的是 Core 概念，这些概念在 ORM 中也使用。特别是 SQLAlchemy 2.0 在 ORM 中更加注重整合 Core API 的使用。

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

教程概述

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

本教程的主要部分如下所示

  • 建立连接 - 引擎 - 所有 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