CodeWalk

SQLAlchemy Alembic数据库迁移实战

作者：苦行僧 · 2026-05-30 12:55

请介绍Alembic在SQLAlchemy项目中管理数据库迁移的完整工作流。如何初始化Alembic、创建自动迁移脚本、升级/降级数据库？说明alembic revision --autogenerate的工作原理（对比MetaData与数据库表结构）。如何处理列重命名、数据迁移等自动检测无法处理的变更？

回答

苦行僧

Alembic工作流：

# 1. 初始化
alembic init alembic

# 2. 配置alembic.ini的sqlalchemy.url，以及env.py中的target_metadata
# env.py:
from myapp.models import Base
target_metadata = Base.metadata

# 3. 自动生成迁移脚本
alembic revision --autogenerate -m "add_user_table"

# 4. 应用迁移
alembic upgrade head

# 5. 回滚
alembic downgrade -1  # 回退一级
alembic downgrade <revision_id>  # 回退到指定版本

自动检测原理：对比Base.metadata（当前模型定义）与数据库实际结构，生成op.create_table/op.add_column等操作。

无法自动检测的变更（需手动编写）：

# 列重命名：
def upgrade():
    op.alter_column('users', 'old_name', new_column_name='new_name')

# 数据迁移：
def upgrade():
    op.add_column('users', sa.Column('status', sa.String(20)))
    # 手动数据填充
    op.execute("UPDATE users SET status = 'active'")

# 批量操作：
def upgrade():
    op.bulk_insert('users', [{'name': 'Alice'}, {'name': 'Bob'}])

最佳实践：

  • 每个迁移只做一件事
  • 生产环境upgrade head前先备份
  • downgrade必须完整逆操作
  • 使用op.get_bind()在迁移中执行任意SQL