🔧 正确的 Alembic 使用步骤
这里是你 应该怎么做迁移 的完整流程（用一次记住，不会再糊涂）：
🥇 第一次迁移初始化（只做一次）
- 初始化 Alembic：
alembic init alembic
生成 alembic.ini 和 alembic/ 文件夹。
- 修改
alembic.ini
找到：
sqlalchemy.url = sqlite:///./test.db
👉 改成你的真实数据库地址，比如：
sqlalchemy.url = sqlite+aiosqlite:///./test.db
⚠ 注意别写错 dialect 和 driver。
- 修改
alembic/env.py，告诉它你的Base.metadata来自哪里：
找到这一段：
# target_metadata = None
改成👇：
from app.db import Base # 替换为你实际的位置
target_metadata = Base.metadata
🥈 每次模型变更后的操作（添加字段、加表、改类型等）
- 生成迁移脚本（Alembic 会自动比较差异）：
alembic revision --autogenerate -m "Add comment table"
它会在 alembic/versions/ 中生成一个 Python 脚本，里面是表结构的变更内容。
- 应用迁移（执行建表/改表）：
alembic upgrade head
这个命令才是真正“让数据库结构更新”的关键操作。
✅ 总结
| 步骤 | 作用 |
|---|---|
| 定义 ORM | 告诉 SQLAlchemy 你要什么表 |
revision --autogenerate | Alembic 对比 ORM 和数据库，生成变更脚本 |
upgrade head | Alembic 执行这些变更，更新数据库结构 |
太好了，我们现在来系统地总结一次 ✅ 使用 Alembic 时必须注意的关键点，特别是你关心的“多人协作场景下”，我会帮你分类清楚、逻辑清晰地列出来：
🧊 Alembic 使用原则总纲：
一个数据库 ➜ 一套模型 ➜ 一套 Alembic 迁移路径
✅ 一、初始化与项目结构
| 项目 | 建议 |
|---|---|
📁 alembic/ 目录 | 必须放进 Git，别人也用这套 |
📁 alembic/versions/ | 存储所有历史迁移脚本，每个 .py 文件都是一步 |
📄 alembic.ini | 可配置数据库 URL，建议读取 .env 动态设置 |
✅ 二、环境配置建议
- 不要在多个目录初始化 Alembic，只初始化一次，然后所有人复用
- 使用
.env管理数据库地址，生产和开发的数据库分开 - 通过
alembic/env.py里动态读取数据库连接和target_metadata
from yourproject.models import Base
target_metadata = Base.metadata
✅ 三、协作开发时的强制规范
| 场景 | 操作规范 |
|---|---|
| ❗ 修改模型结构后 | 运行：alembic revision --autogenerate -m "your message" |
| ✅ 添加字段 / 改名等 | 都要通过 Alembic 写入一份迁移脚本，不可只改模型 |
| ✅ 提交代码时 | 必须将迁移脚本一并 git commit |
| 🚫 不要 | 每人自己生成迁移文件，不合并，会版本冲突 |
| ✅ 多人修改模型结构 | 提前沟通，合并成一份迁移或顺序提交并 rebase |
✅ 四、生产环境注意事项
- 禁止在生产环境手动执行 SQL 改表结构（除非同步 Alembic）
- 每次上线前必须先跑
alembic upgrade head - 保留一个完整的迁移版本记录，不能中途跳版本
- 不建议频繁
downgrade，除非数据库结构非常稳定
✅ 五、常见错误与应对
| 问题 | 说明 | 解决办法 |
|---|---|---|
| 🔁 “Multiple heads found” | 多人生成迁移脚本，未合并 | 用 alembic merge 或 rebase |
| ⚠️ 版本错乱 | 多套 Alembic 同时用 | 统一迁移目录，版本目录 Git 管理 |
| ❌ 自动生成脚本为空 | 没正确配置 target_metadata | 修改 env.py，正确引入模型 |
❌ 执行 upgrade 报错 | 数据库结构与模型不同步 | 用 --sql 查看生成 SQL 手动排查 |
✅ 六、最关键的 3 条铁律
- 🧠 模型变化必须对应一份 Alembic 迁移脚本
- 🔄 所有人必须用同一份 Alembic 版本目录（并 Git 管理）
- 🔥 部署上线前，必须保证迁移到最新版本
alembic upgrade head
✨ 你可以这样安排自己的流程：
- 本地开发阶段，用
Base.metadata.create_all()搭建结构调试（临时） - 稳定后切换为 Alembic 统一管理迁移版本
- 一旦用了 Alembic，就严格按上述流程协作，不可再手动改结构
- 项目上线，版本控制 + 数据一致性都有保障
📌 如果你想，我还可以为你生成一份：
- FastAPI + SQLAlchemy + Alembic 的最小可部署结构
- 带
.env环境区分和alembic.ini动态配置 - 包含 Git 提交规范和
.gitignore模板