Flask数据库迁移：Flask-Migrate使用指南

在使用Flask开发Web应用时，数据库结构的变化是常见需求。比如新增字段、修改表结构、调整字段类型等。如果直接手动修改数据库，不仅容易出错，还可能导致数据丢失。这时候，数据库迁移工具就派上用场了。Flask-Migrate就是专门为Flask设计的数据库迁移扩展，它基于Alembic实现，能帮助我们安全、方便地管理数据库结构的变更。

为什么需要数据库迁移？¶

假设你已经通过SQLAlchemy定义了一个User模型，此时数据库中生成了users表。如果突然想给User模型添加一个age字段（比如年龄），直接在Python代码中改模型是不够的——数据库表结构并没有同步更新。手动执行ALTER TABLE语句可能会有风险（比如数据类型不匹配、索引丢失）。而数据库迁移工具可以自动生成迁移脚本，将模型的变更安全地应用到数据库中。

Flask-Migrate是什么？¶

Flask-Migrate是Flask的扩展，它封装了Alembic的核心功能，让数据库迁移变得简单。它与Flask-SQLAlchemy配合使用，通过检测模型类的变化自动生成迁移脚本，并管理这些脚本的执行（升级/回滚）。

安装与配置¶

首先确保已安装必要的库：

# 安装Flask-Migrate
pip install flask-migrate

# 假设已安装Flask和Flask-SQLAlchemy（如果没装，先执行）
pip install flask flask-sqlalchemy

在Flask应用中初始化Flask-Migrate：

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///mydatabase.db'  # 数据库连接
app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False

db = SQLAlchemy(app)
migrate = Migrate(app, db)  # 初始化迁移工具，关联app和db

# 定义模型（示例）
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(80), nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)

# 路由和其他代码...

数据库迁移核心命令¶

Flask-Migrate将Alembic的命令封装成了Flask CLI命令，常用命令如下：

命令	作用
`flask db init`	初始化迁移环境（只执行一次，生成migrations文件夹和versions目录）
`flask db migrate -m "描述"`	生成迁移脚本（-m指定脚本说明，如“add age field to User”）
`flask db upgrade`	应用迁移脚本，更新数据库结构
`flask db downgrade`	回滚最近一次迁移（如果需要撤销）

完整迁移流程示例¶

1. 初始化迁移环境¶

在项目根目录执行：

flask db init

执行后会生成一个migrations文件夹，包含versions目录（存放迁移脚本）和env.py等配置文件。

2. 第一次模型迁移¶

假设此时我们有一个User模型（见上文代码），需要将其映射到数据库：

# 生成迁移脚本
flask db migrate -m "create users table"

# 应用迁移脚本到数据库
flask db upgrade

此时，数据库（mydatabase.db）中会自动创建users表，结构与User模型一致。

3. 修改模型并重新迁移¶

如果需要给User模型添加age字段：

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(80), nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)
    age = db.Column(db.Integer)  # 新增age字段

然后重复迁移流程：

# 生成新的迁移脚本（检测到模型变化）
flask db migrate -m "add age field to User"

# 应用新迁移，数据库表会自动添加age字段
flask db upgrade

4. 回滚迁移（如果出错）¶

如果迁移后发现问题，比如age字段定义错误（如应该允许为空但设为nullable=True却写成False），可以回滚：

# 回滚最近一次迁移
flask db downgrade

# 检查迁移记录：versions目录中会保留历史版本，回滚后versions中的最新迁移被撤销

进阶技巧：处理复杂迁移¶

如果模型变更涉及数据迁移（如修改字段类型、删除字段），flask db migrate可能无法自动生成正确的迁移脚本，这时需要手动修改迁移脚本：

生成迁移脚本后，检查migrations/versions/下的脚本文件（如a1b2c3d45678_add_age_field.py）
在upgrade和downgrade函数中手动处理数据转换，例如：

   # 假设修改字段类型为String，且需要设置默认值
   def upgrade():
       op.add_column('users', sa.Column('age', sa.String(), nullable=True))
       # 手动添加默认值（如果需要）
       op.execute("UPDATE users SET age = '20' WHERE age IS NULL")

总结¶

Flask-Migrate通过以下步骤解决了数据库迁移问题：
1. 初始化迁移环境：flask db init
2. 生成迁移脚本：flask db migrate -m "描述"
3. 应用/回滚迁移：flask db upgrade / flask db downgrade

核心优势是自动检测模型变更、版本控制迁移历史、安全回滚，避免手动修改数据库的风险。初学者只需记住上述命令和流程，就能轻松管理数据库结构的迭代。

常用命令速查表：
- 初始化：flask db init
- 生成脚本：flask db migrate -m "描述"
- 应用迁移：flask db upgrade
- 回滚：flask db downgrade

通过不断实践，你就能熟练使用Flask-Migrate管理数据库的每一次变化！