🛠️ 数据库迁移管理（SQLAlchemy 版）

🛠️ 使用 Alembic 进行数据库迁移管理（SQLAlchemy 版）

Alembic 是 SQLAlchemy 提供的官方数据库版本管理工具。
它可以记录并执行数据表结构的变化，用于持续集成和项目演进时追踪数据库 schema。

以下是项目中常用的 Alembic 使用方式 👇

1️⃣ 初始化 Alembic 配置

在项目根目录初始化一个名为 migrations 的目录结构：

alembic init migrations

执行后，会生成如下一些配置和模板：

2️⃣ 修改 env.py 配置（用于加载项目 Models）

打开 migrations/env.py，修改如下：

from logging.config import fileConfig

from sqlalchemy import engine_from_config
from sqlalchemy import pool

from alembic import context

# from apis.models import *  # 每个项目独立的db model
from commonlibs.models import *  # 确保所有的表都被检测到
from commonlibs.commonDbEngine import Base, create_db_engine

config = context.config

if config.config_file_name is not None:
    fileConfig(config.config_file_name)

target_metadata = Base.metadata
print("检测到的表：", Base.metadata.tables.keys())


def run_migrations_offline() -> None:
    url = config.get_main_option("sqlalchemy.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:
    connectable = create_db_engine()
    with connectable.connect() as connection:
        context.configure(connection=connection, target_metadata=target_metadata)
        with context.begin_transaction():
            context.run_migrations()


if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

⚠️ 注意事项：

• Base 必须是所有 SQLAlchemy 模型的基础类集合
• 所有模型文件必须在此处可被正确导入（不导入就无法识别）
• create_db_engine() 返回 SQLAlchemy Engine 的连接函数（自定义封装即可）

3️⃣ 生成迁移脚本（自动对比差异）

每次模型变更后执行：

alembic revision --autogenerate

推荐加上变更描述：

alembic revision --autogenerate -m "create user table"

执行后会在 migrations/versions 下生成新的迁移脚本。

可在文件中看到 detect 出来的变更：

def upgrade():
    # ### auto-generated ###
    op.create_table(
        'user',
        sa.Column('id', sa.Integer(), nullable=False),
        sa.Column('username', sa.String(), nullable=False),
        ...
    )
    # ### end auto-generated ###

4️⃣ 执行数据库迁移

将最新迁移应用到数据库：

alembic upgrade head

其他用法：

✅ 总结

• alembic 可自动检测 Model 变更，生成并应用 migration 脚本
• env.py 是连接模型与数据库的关键配置文件
• 配置好后，只需更新 Model → autogenerate → upgrade 即可完成版本同步
• 推荐配合 Git 管理 migrations/versions 文件夹，确保多人协作一致性

📌 拓展建议：

• 支持多数据库（可通过 env.py 切换 engine）
• Alembic 也支持针对 SQLite、PostgreSQL、MySQL 等多种数据库
• 可集成 CI/CD 中自动执行 upgrade，例如部署上线前或 Docker 启动脚本中加入命令