数据库迁移工具——Alembic

Alembic 是一个专为 SQLAlchemy 设计的数据库迁移工具，它可以帮助你以版本控制的方式管理和应用数据库结构的变更。你可以把它理解为数据库结构变更的"Git"。

下面是一份从零开始的 Alembic 使用教程。

🛠️ 第一步：安装与初始化

安装 Alembic

在你的项目环境中使用 pip 安装 Alembic。
bash 复制代码
```
uv add alembic sqlalchemy
```
初始化 Alembic 环境

进入你的项目根目录，运行以下命令来创建一个 alembic 目录和相关配置文件。
bash 复制代码
```
alembic init alembic
```
执行后会生成如下结构：
- alembic.ini: Alembic 的主配置文件。
- alembic/: 迁移脚本目录。
  - env.py: 迁移脚本的运行环境配置。
  - versions/: 存放所有迁移脚本文件的目录。

⚙️ 第二步：配置 Alembic

初始化完成后，需要进行两步关键配置。

配置数据库连接 (alembic.ini)

打开 alembic.ini 文件，找到 sqlalchemy.url 这一行，将其修改为你的数据库连接地址。
ini 复制代码
```
sqlalchemy.url = mysql+pymysql://用户名:密码@主机地址:端口/数据库名?charset=utf8mb4
```
关联 SQLAlchemy 模型 (alembic/env.py)

打开 alembic/env.py 文件，你需要在这里导入你的 SQLAlchemy 模型基类（通常是 Base），并让 Alembic 知道它。
- 在文件顶部导入你的 Base 对象。
- 找到 target_metadata = None 这一行，将其修改为：
  python 复制代码
```
from my_project.models import Base  # 请根据你的项目结构调整导入路径

# ...

target_metadata = Base.metadata
```
这样，Alembic 才能通过你的模型定义来自动检测数据库结构的变化。

⚙️ 第二步配置数据库连接进阶版

直接将账号密码配置在 alembic.ini 不安全，让它读取环境变量中的配置。

第一步：将 alembic.ini 数据库配置置为空
ini 复制代码
```
sqlalchemy.url =
```

第二步：需改env.py env.py

python 复制代码

...
load_env_files()
def get_url():
    db_url = os.getenv("DATABASE_URL")

    if not db_url:
        raise ValueError("未找到环境变量 'DATABASE_URL'，请检查配置")

    return db_url


def run_migrations_offline() -> None:
    url = get_url()
    context.configure(
        url=url,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )

    with context.begin_transaction():
        context.run_migrations()


def run_migrations_online() -> None:
    configuration = config.get_section(config.config_ini_section)
    configuration["sqlalchemy.url"] = get_url()

    connectable = engine_from_config(
        configuration,
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )
    ...

🚀 第三步：创建并执行迁移

当你创建或修改了 SQLAlchemy 模型后，就可以开始迁移了。

生成迁移脚本

使用 --autogenerate 参数，Alembic 会自动比对你的模型和数据库的差异，并生成相应的迁移脚本。
bash 复制代码
```
alembic revision --autogenerate -m "描述本次变更，例如：创建用户表"
```
命令执行后，会在 alembic/versions/ 目录下生成一个带时间戳的迁移脚本文件。
执行迁移 (升级数据库)

检查生成的迁移脚本无误后，运行以下命令将变更应用到数据库。
bash 复制代码
```
alembic upgrade head
```
head 代表最新的版本。执行成功后，数据库结构就会更新。

⏪ 第四步：回滚迁移

如果迁移出现问题，或者你需要撤销某次变更，可以使用回滚命令。

回滚到上一个版本
bash 复制代码
```
alembic downgrade -1
```
回滚到指定版本
bash 复制代码
```
alembic downgrade <版本号>
```
回滚到初始状态 (删除所有由迁移创建的表)
bash 复制代码
```
alembic downgrade base
```

📜 常用命令速查

命令	作用
`alembic init <dir>`	初始化 Alembic 环境
`alembic revision --autogenerate -m "msg"`	自动生成迁移脚本
`alembic upgrade head`	将数据库升级到最新版本
`alembic downgrade -1`	回滚到上一个版本
`alembic current`	查看数据库当前的版本
`alembic history`	查看所有迁移历史

💡 最佳实践提示

检查自动生成的脚本 ：--autogenerate 功能非常强大，但并非万无一失。对于复杂的变更（如字段重命名、删除操作），它可能无法准确识别。因此，在执行 upgrade 之前，务必人工检查一下生成的迁移脚本，确保 upgrade() 和 downgrade() 函数中的逻辑是正确的。
版本控制 ：建议将 alembic/versions/ 目录下的所有迁移脚本纳入 Git 等版本控制系统，以便团队协作和追踪变更历史。