alembic使用指南
一、alembic是什么？
Alembic 是一个用于 Python 数据库迁移和版本控制的工具。它与 SQLAlchemy（一个流行的 Python ORM 库）紧密集成，共同为 Python 应用程序提供数据库管理和迁移支持。
python使用mysql时常用SQLAlchemy+Alembic进行ORM和数据库迁移。
二、如何集成到项目中？
1.安装
uv install alembic==1.13.0 or pip install alembic==1.13.0
2.进入项目根目录 初始化Alembic
2.1 终端执行 alembic init alembic init 初始化命令 alembic 环境名称
项目中多出alembic目录
alembic.ini: Alembic 的主配置文件。
env.py: Alembic 运行时环境的 Python 脚本，用于配置 SQLAlchemy 引擎和元数据。
script.py.mako: 迁移脚本的模板文件。
versions/: 存放所有迁移脚本的目录。
图片
2.2 配置 alembic.ini（指定数据库连接字符串）
通过环境变量读取 不要硬编码
图片
2.3 配置 env.py （告诉 Alembic 你的 SQLAlchemy 模型在哪里，以便它能够进行自动检测。）
找到 target_metadata 变量，将其指向你的 SQLAlchemy Base.metadata 对象。
图片
解释一下：Base对象是所有模型类的基类，你创建的所有模型都要继承Base
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
创建Base虽然创建在哪都可以，最好放在数据库连接层，结构清晰，目录结构如下
图片
2.4 创建SQLAlchemy模型
所有模型集成Base对象，这样后面执行迁移就会自动检测所有更改的字段
图片
3.生成第一个迁移脚本
要提前安装 pip install pymysql
3.1 自动生成
终端输入命令： alembic revision --autogenerate -m "Create initial tables"
alembic revision: 创建一个新的数据库迁移脚本。
--autogenerate: 自动检测你的 SQLAlchemy 模型与数据库当前状态的差异，并生成相应的升级/降级 SQL 语句。
-m "Create initial tables": 为这个迁移脚本添加一个描述性消息，方便你理解其目的。
图片
图片
检查生成的迁移文件sql命令是否正常 不正常就手动或者找ai修复下
3.2 手动生成（推荐）
第一次创建迁移文件 上一次版本号为None
后续按照现有的文件格式创建新的迁移即可，版本号使用基于时间戳的uuid即可，上一个版本的版本号记得填。
upgrade：对应新的sql操作
downgrade：操作失败回滚
有时候alembic对于修改和删除的字段检测不出来，最好就手写迁移脚本
4.执行迁移
终端命令 alembic upgrade head 检查库中表是否存在
图片
逻辑流程图
初始化 Alembic 项目
↓
配置 alembic.ini (数据库连接) & env.py (加载 ORM 模型, 建立连接)
↓
定义 SQLAlchemy Base 和 ORM 模型
↓
ORM 模型发生变化?
├─ 是 (模型与数据库结构不一致)
│ ↓
│ 5. 生成迁移文件 (alembic revision --autogenerate)
│ (Alembic 比较 ORM 模型定义 与 MySQL 数据库实际结构)
│ ↓
│ 6. 人工检查并修改迁移文件 (确保 upgrade/downgrade 逻辑正确)
│ ↓
│ 7. 执行迁移 (alembic upgrade head)
│ (Alembic 读取迁移文件, 更新 MySQL 数据库结构, 并更新 alembic_version 表)
│ ↓
└─ 否 (模型与数据库结构一致)
↓
(无需迁移)
↓
应用程序启动 & 与更新后的 MySQL 数据库交互
三、常用的命令？
alembic revision --autogenerate -m "描述" 自动生成迁移脚本
alembic upgrade head 执行最新迁移
alembic current 查看当前数据库迁移脚本
alembic stamp <revision_id> 将数据库标记为指定版本（不执行迁移）
alembic history 查看迁移历史