4. Alembic 迁移工具入门

Alembic 是 SQLAlchemy 团队开发的轻量级数据库迁移工具，专为 Python 异步与同步环境设计。它通过版本化迁移脚本管理数据库 Schema 的增量变更，是 Development 环境中保证数据库结构与代码模型一致性的核心组件。

4.1 Alembic 的核心作用

4.2 安装 Alembic

推荐在虚拟环境中通过 pip 安装，同时安装异步数据库驱动：

# 安装 Alembic 核心
pip install alembic

# 安装异步 PostgreSQL 驱动（开发环境常用）
pip install asyncpg

# 安装异步 MySQL 驱动
pip install aiomysql

# 验证安装
alembic --version

4.3 初始化配置：alembic init

在项目根目录执行初始化命令，生成标准目录结构与配置文件：

# 初始化 Alembic 项目
alembic init alembic

执行后生成的文件结构如下：

your_project/
├── alembic/                  # 迁移脚本目录
│   ├── versions/             # 版本迁移脚本存放处
│   │   └── .gitkeep          # 占位文件
│   ├── env.py                # 核心环境配置（关键文件）
│   ├── script.py.mako        # 迁移脚本模板
│   └── README                # 说明文件
└── alembic.ini               # 全局配置文件

4.4 env.py 文件结构解析

env.py 是 Alembic 迁移运行时的入口，控制数据库连接、模型加载、迁移上下文等核心逻辑。以下为适配异步开发环境的典型结构：

# alembic/env.py

import asyncio
from logging.config import fileConfig

from alembic import context
from sqlalchemy import pool
from sqlalchemy.ext.asyncio import async_engine_from_config

# 导入 SQLAlchemy 模型基类（所有模型继承自该 Base）
from app.models import Base

# Alembic Config 对象，读取 alembic.ini
config = context.config

# 配置日志
if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# 设置元数据，用于自动生成迁移
target_metadata = Base.metadata

def run_migrations_offline() -> None:
    """离线模式：仅生成 SQL 脚本，不连接数据库"""
    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 do_run_migrations(connection):
    """执行迁移的核心函数"""
    context.configure(connection=connection, target_metadata=target_metadata)
    with context.begin_transaction():
        context.run_migrations()

async def run_async_migrations() -> None:
    """异步模式：使用 async engine 执行迁移"""
    configuration = config.get_section(config.config_ini_section)
    # 创建异步引擎
    connectable = async_engine_from_config(
        configuration,
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )
    async with connectable.connect() as connection:
        await connection.run_sync(do_run_migrations)
    await connectable.dispose()

def run_migrations_online() -> None:
    """在线模式入口：根据配置选择同步或异步执行"""
    # 检测是否使用异步驱动
    url = config.get_main_option("sqlalchemy.url")
    if url.startswith("postgresql+asyncpg") or url.startswith("mysql+aiomysql"):
        asyncio.run(run_async_migrations())
    else:
        # 同步模式（兼容传统场景）
        from sqlalchemy import create_engine
        engine = create_engine(url, poolclass=pool.NullPool)
        with engine.connect() as connection:
            do_run_migrations(connection)

# 根据 Alembic 运行模式选择执行路径
if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

4.5 Alembic 迁移工作流

4.6 常用迁移命令速查