Alembic自动生成迁移靠谱吗

本文目录导读：

1. 靠谱的地方（它能做什么）
2. 不靠谱的地方（它容易搞砸或需要特别注意的地方）
3. 最佳实践：如何让它更“靠谱”

Alembic 的 --autogenerate 功能是否“靠谱”，结论是：它是一个强大的辅助工具，但绝对不是万能的，对于生产环境，绝对不能完全信任它自动生成的迁移脚本。

把它看作“草稿生成器”而非“自动提交机”是比较合理的预期。

下面详细分析它的靠谱之处、常见坑点以及最佳实践。

靠谱的地方（它能做什么）

对于大多数日常的、简单的模型变更，--autogenerate 非常高效且准确：

1. 新增表和列： 添加新的 SQLAlchemy 模型或字段，它几乎 100% 能正确生成 CREATE TABLE 或 ALTER TABLE ADD COLUMN。
2. 删除表和列： 移除了模型或字段，它会生成 DROP TABLE 或 DROP COLUMN。
3. 修改列类型： 如 String(50) -> String(100)，或 Integer -> Float，它能检测到并生成 ALTER COLUMN。
4. 修改列属性： 添加/删除 nullable，添加/删除 unique 约束，添加/删除 index 等，通常能正确生成。
5. 索引/约束变更： 修改外键、唯一约束等，通常也没有问题。

对于 80% 的日常模型变更，它都能胜任。

不靠谱的地方（它容易搞砸或需要特别注意的地方）

这才是重点,也是很多开发者踩坑的地方：

1. 命名约束的“瞎猜”：

   • Alembic 在检测约束（如唯一约束、外键约束、检查约束）变更时，依赖于约束的名字。
   • 如果你在 __table_args__ 或 UniqueConstraint('name', name='uq_user_name') 中为约束显式命名，Alembic 能通过名字匹配来判断是修改还是删除。
   • 但如果你没有命名约束（UniqueConstraint('email')），Alembic 会给它生成一个自动名字（如 uq_user_email），当你下次再修改时，它无法确定这两个约束是不是同一个，往往会生成 DROP CONSTRAINT 再 ADD CONSTRAINT 的操作，这在大表上非常危险（可能导致锁表或数据丢失）。

2. 列的重命名：

   • 它是检测不出来的，如果你把 name 列改名为 full_name，Alembic 会认为你删除了 name 并添加了 full_name，它会生成 DROP COLUMN name; ADD COLUMN full_name。
   • 显式重命名：它无法自动识别 ALTER TABLE RENAME COLUMN 的意图。

3. 表和列的重命名：

   • 同理,无法检测，它会生成 DROP TABLE old_name; CREATE TABLE new_name，导致数据丢失。

4. 复杂的数据迁移和默认值处理：

   • 它只关注 元数据（Schema） 的变更，不关心已存在的数据。
   • 添加 nullable=False 列时： 如果表非空，自动生成的脚本会直接 ALTER TABLE ADD COLUMN new_col ... NOT NULL，这会直接导致数据库报错，正确的做法应该是：先 ADD COLUMN 允许为空 -> 填充数据 -> 再 ALTER COLUMN SET NOT NULL，Alembic 不会处理这中间的步骤。
   • 修改列的默认值： 它能检测到默认值的修改，但生成的 ALTER COLUMN SET DEFAULT 只影响新增的行，不会更新历史已有行的默认值。

5. 特殊类型和数据库特定操作：

   • ENUM 类型： PostgreSQL 中，添加/修改 ENUM 类型可能会生成为 ALTER TYPE ... ADD VALUE，但删除 ENUM 值时通常不支持，Alembic 可能生成错误或跳过。
   • JSON/JSONB 类型的嵌套变更： 它无法检测到 JSON 字段内部结构的改变。
   • ARRAY 类型的内部元素类型变更： 同样无法检测。

6. 依赖顺序和循环依赖：

   • 自动生成的迁移脚本可能不会考虑表之间的依赖顺序,如果 A 引用了 B，删除 B 表可能会在 A 表外键约束之前执行，导致失败。
   • 循环外键依赖可能导致迁移无法执行。

7. --sql 和离线模式：

   • 如果你使用 --sql 生成 SQL 脚本，需要注意生成的 SQL 可能会包含一些特定于当前数据库连接状态的特性（如数据库名），在另一个数据库中执行可能出错。

最佳实践：如何让它更“靠谱”

1. 总是手动审查： 永远不要在生成后直接执行 alembic upgrade head，必须打开生成的迁移文件（migrations/versions/xxx.py），仔细阅读 upgrade() 和 downgrade() 函数中的每一行 SQL 操作。
2. 为所有约束命名： 在 SQLAlchemy 模型中，显式为 UniqueConstraint、ForeignKeyConstraint、CheckConstraint 等命名，避免依赖自动命名。
3. 重命名时手动处理： 如果修改了列名或表名，手动在迁移脚本中写 ALTER TABLE RENAME COLUMN old TO new，并删除自动生成的 DROP/ADD 代码。
4. 复杂迁移手动编写： 对于数据迁移（如拆分字段、填充新列默认值、修改已有数据），不要依赖自动生成，手动编写 op.execute(sa.text('...')) 或使用 SQLAlchemy 的 bulk_update。
5. 区分 test/staging/production： 先在开发环境或 staging 数据库上生成并执行迁移，验证没问题后再应用到生产环境。
6. 使用 compare_type=True 和 compare_server_default： 在 env.py 的 run_migrations_online 中配置这些参数，可以让 Alembic 更细致地比较类型和服务器默认值，但依然需要手动检查。
7. 关注 depends_on： 对于有依赖关系的迁移，在迁移类的 depends_on 属性中指定依赖，确保执行顺序正确。
8. 版本控制： 始终将迁移脚本（migrations/versions/*.py）加入版本控制。
9. 熟悉回滚： 确保自动生成的 downgrade() 函数也是合理的，或者至少能安全地回滚。

最终结论：

• 对于开发/测试环境： --autogenerate 非常“靠谱”，能极大提升效率，但每次执行前仍需快速扫一眼生成的 SQL。
• 对于生产环境： 绝对不要直接信任 --autogenerate 生成的脚本，必须经过手动审查、测试，并对复杂或高风险操作进行手动重写。

能把“不靠谱”的部分控制好的人，用 --autogenerate 会非常顺手；但认为它能解决一切的人，最后往往会出问题。