logo cmdragon's Blog

Alembic迁移脚本：让数据库变身时间旅行者

avatar
cmdragon 大乘
  2025-05-09 13:08:18   2025-05-09 13:08:18   1.7k 字  7 分钟
image image

扫描二维码
关注或者微信搜一搜：编程智域 前端至全栈交流与成长

探索数千个预构建的 AI 应用，开启你的下一个伟大创意：https://tools.cmdragon.cn/

1. Alembic 迁移脚本自动生成原理与实践

1.1 什么是数据库迁移？

数据库迁移（Database Migration）是跟踪数据库模式变化的系统化方法。就像我们使用Git管理代码版本一样，Alembic
通过迁移脚本记录数据库结构的变更历史。当我们在开发过程中修改数据表结构时，通过迁移可以确保不同环境（开发、测试、生产）的数据库保持同步。

1.2 Alembic 核心工作原理

Alembic 的自动生成功能基于模型对比实现，其工作流程分为三个阶段：

  1. 模型扫描：读取SQLAlchemy的Base类元数据
  2. 数据库快照：连接目标数据库获取当前结构
  3. 差异分析：对比模型定义与数据库实际结构的差异
1
2
3
4
5
6
7
8
9
10
11
12
13
# 示例：典型模型定义（models.py）
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()


class User(Base):
    __tablename__ = 'users'

    id = Column(Integer, primary_key=True)
    name = Column(String(50))
    email = Column(String(100))  # 新增字段示例

1.3 自动生成迁移脚本实战

1.3.1 环境配置

安装必要依赖：

1
pip install alembic sqlalchemy fastapi

项目目录结构：

1
2
3
4
5
6
7
/project
  /alembic
    /versions
    env.py
  alembic.ini
  main.py
  models.py

1.3.2 初始化Alembic

1
alembic init alembic

修改alembic.ini配置：

1
2
3
[alembic]
script_location = alembic
sqlalchemy.url = postgresql://user:pass@localhost/dbname

1.3.3 生成迁移脚本

1
alembic revision --autogenerate -m "add email column"

生成的迁移文件示例（alembic/versions/xxxx_add_email_column.py）：

1
2
3
4
5
6
def upgrade():
    op.add_column('users', Column('email', String(100)))


def downgrade():
    op.drop_column('users', 'email')

1.4 高级配置技巧

1.4.1 自定义上下文配置

在env.py中添加模型导入：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 修改后的env.py核心部分
from models import Base  # 导入模型基类

target_metadata = Base.metadata


def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            compare_type=True,  # 启用字段类型比对
            compare_server_default=True  # 比对默认值
        )

1.4.2 处理复杂字段变更

当修改字段类型时，建议分步骤操作：

1
2
3
4
5
6
7
# 迁移脚本示例：安全修改字段类型
def upgrade():
    with op.batch_alter_table('users') as batch_op:
        batch_op.alter_column('phone',
                              existing_type=String(20),
                              type_=Integer(),
                              existing_nullable=True)

1.5 课后Quiz

问题1：当新增模型类后执行alembic revision --autogenerate没有生成迁移脚本，最可能的原因是？
A. 忘记保存模型文件
B. 模型未正确导入到env.py
C. 数据库连接失败
D. 未安装sqlalchemy

答案：B。Alembic需要正确导入包含Base类的模型定义才能进行元数据比对，如果未在env.py中正确设置target_metadata，会导致无法检测模型变化。

问题2：哪个命令可以查看当前数据库版本？
A. alembic current
B. alembic show
C. alembic history
D. alembic heads

答案：A。alembic current命令显示当前数据库所处的迁移版本。

1.6 常见报错解决方案

错误1：FAILED: Target database is not up to date

1
alembic upgrade head

原因：存在未应用的迁移版本
解决：执行升级命令更新数据库

错误2：SAWarning: Did not recognize type 'geometry'...

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 在env.py中添加自定义类型映射
from sqlalchemy.dialects.postgresql import JSONB


def include_name(name, type_, parent_names):
    if type_ == "geometry":
        return False
    return True


context.configure(
    ...
include_name = include_name,
user_module_prefix = 'sa.'
)

原因：使用了数据库特定的字段类型
解决：在env.py中添加类型过滤逻辑

错误3：Can't locate revision identified by 'xxxxx'

1
2
alembic history --verbose
alembic downgrade -1

原因：版本链断裂或历史记录不完整
解决：检查迁移历史记录，必要时回滚到有效版本

1.7 最佳实践建议

  1. 每次修改模型后立即生成迁移脚本
  2. 测试环境始终执行alembic upgrade head保证最新
  3. 生产环境变更前必须备份数据库
  4. 复杂变更建议分多个迁移步骤完成
  5. 保持开发、测试、生产环境的数据库版本一致

通过掌握这些核心原理和实践技巧，您可以在FastAPI项目中实现安全可靠的数据库版本管理。下次当您修改模型时，记得用--autogenerate
参数让Alembic自动生成迁移脚本，这将极大提升开发效率并减少人为错误。

余下文章内容请点击跳转至 个人博客页面 或者 扫码关注或者微信搜一搜：编程智域 前端至全栈交流与成长，阅读完整的文章：

往期文章归档：

Alembic迁移脚本：让数据库变身时间旅行者
posts/24a6445f18ef/
作者
cmdragon
发布于
2025-05-09 13:08
许可
  1. 1. 1. Alembic 迁移脚本自动生成原理与实践
    1. 1.1. 1.1 什么是数据库迁移？
    2. 1.2. 1.2 Alembic 核心工作原理
    3. 1.3. 1.3 自动生成迁移脚本实战
      1. 1.3.1. 1.3.1 环境配置
      2. 1.3.2. 1.3.2 初始化Alembic
      3. 1.3.3. 1.3.3 生成迁移脚本
    4. 1.4. 1.4 高级配置技巧
      1. 1.4.1. 1.4.1 自定义上下文配置
      2. 1.4.2. 1.4.2 处理复杂字段变更
    5. 1.5. 1.5 课后Quiz
    6. 1.6. 1.6 常见报错解决方案
    7. 1.7. 1.7 最佳实践建议
    8. 1.8. 往期文章归档：
  1. 1. 1. Alembic 迁移脚本自动生成原理与实践
    1. 1.1. 1.1 什么是数据库迁移？
    2. 1.2. 1.2 Alembic 核心工作原理
    3. 1.3. 1.3 自动生成迁移脚本实战
      1. 1.3.1. 1.3.1 环境配置
      2. 1.3.2. 1.3.2 初始化Alembic
      3. 1.3.3. 1.3.3 生成迁移脚本
    4. 1.4. 1.4 高级配置技巧
      1. 1.4.1. 1.4.1 自定义上下文配置
      2. 1.4.2. 1.4.2 处理复杂字段变更
    5. 1.5. 1.5 课后Quiz
    6. 1.6. 1.6 常见报错解决方案
    7. 1.7. 1.7 最佳实践建议
    8. 1.8. 往期文章归档：