SQLAlchemy 和 Alembic

原创于 2026-07-01 22:46:17 发布 · 310 阅读

本内容遵循CC 4.0 BY-SA版权协议

SQLAlchemy 是 Python 生态系统中最知名、最成熟的数据库工具包，它提供了一套完整且灵活的工具，用于处理关系型数据库。

你可以把它理解为一个功能强大的“数据库翻译官”和“对象管家”，核心价值在于两点：

抽象与统一：让你能用统一的 Python 代码操作不同的数据库（如 PostgreSQL, MySQL, SQLite），无需关心底层SQL方言的差异。这极大地提升了代码的可移植性和维护性。
提供两种工作模式：它不像一些“大包大揽”的框架，而是提供了两种互补的方式，让你可以根据项目需求灵活选择，甚至混合使用。

这两种模式构成了 SQLAlchemy 的核心架构，其分层关系如下：

SQLAlchemy Core（核心）：这是地基，是一个功能完备的 SQL 抽象工具包。它通过 SQL 表达式语言 让你用 Python 对象来构建 SQL 语句，而不是拼接字符串。这不仅能防止 SQL 注入攻击，还非常直观。它关注的是 数据库模式（Schema），适合对 SQL 控制要求极高的场景，如数据仓库、复杂报表或直接执行原生 SQL。
SQLAlchemy ORM（对象关系映射）：它建立在 Core 之上，是一个可选的高级组件。它的核心思想是 工作单元（Unit of Work） 模式。简单说，它允许你用操作 Python 对象的方式来操作数据库记录，并自动追踪对象的变动，在提交（commit）时一次性将这些变化同步到数据库，而不需要手动编写每条 INSERT/UPDATE 语句。它关注的是 业务对象（Domain Model），能够极大提高开发效率。

选择哪种模式是开始使用 SQLAlchemy 的关键：

最重要的是，两者可以无缝结合。你可以在 ORM 中直接使用 Core 的表达式来编写复杂的查询，甚至在需要时执行原生 SQL。

Alembic 是专为 SQLAlchemy 打造的数据库迁移工具。你可以把它看作是 SQLAlchemy 生态的“版本控制系统”，专门用来管理数据库结构的变更。

如果说 SQLAlchemy 帮你用 Python 代码定义数据库结构（建表、定义字段），那么 Alembic 解决的是这个结构随着项目迭代，如何一步步、可追溯、可回退地更新到数据库的问题。

理解 Alembic，可以抓住这几个关键点：

迁移脚本（Revisions）是核心：每一次对数据库结构的变更（比如新增一个字段），都会生成一个独立的 Python 迁移脚本文件。你可以把它想象成 Git 的一次提交（commit），包含了如何“升级”（upgrade）和如何“回退”（downgrade）的完整指令。
“自动生成”很省力：当你修改了 SQLAlchemy 的模型定义后，Alembic 可以通过 alembic revision --autogenerate 命令，自动对比模型代码和当前数据库的实际状态，并生成一个包含变更内容的迁移脚本草稿，能省去大量手写重复代码的功夫。
像 Git 一样的版本管理：迁移脚本之间通过一个唯一的哈希 ID 相互链接，形成一个类似 Git 提交历史的有向无环图（DAG）。这使得它天然支持复杂的分支（Branches）和合并（Merges），非常适合团队协作。
特别照顾 SQLite：因为 SQLite 对 ALTER 语句的支持有限，Alembic 提供了一个“批量迁移（Batch Migration）”模式。它会自动创建一个临时的新表、复制数据、删除旧表、再将新表重命名，用一种变通的方式完成结构变更。

在实际开发中，你的操作流程通常是这样的：

初始化：在你的项目里运行 alembic init，它会生成一套 Alembic 需要的配置文件和目录结构。
修改模型：你像往常一样修改 SQLAlchemy 的 Model 定义。
生成迁移：运行 alembic revision --autogenerate -m "添加了用户年龄字段"，Alembic 会自动生成迁移脚本，你只需要检查和微调即可。
应用变更：运行 alembic upgrade head，就会将所有尚未应用的迁移按顺序应用到数据库，完成更新。