生产环境中Flask-Migrate的使用模式及部署疑问

你提到的场景非常典型——当把Flask应用作为Python包发布部署时，默认放在项目根目录的migrations文件夹不会被包含在安装包内，直接复制这个文件夹又容易出现版本不匹配的问题。下面是更优的解决方案，以及为什么数据库迁移是必要的：

最优方案：将迁移脚本纳入应用包内 #

与其手动复制migrations文件夹，不如把迁移脚本作为应用包的一部分发布，这样部署时就能自动获取到对应版本的迁移文件，避免同步问题。具体步骤如下：

1. 调整项目结构

   • 在你的Flask应用核心包（比如app/目录）下创建migrations/versions目录，专门存放迁移脚本文件
   • 开发过程中，每次生成迁移脚本（执行flask db migrate）后，把migrations/versions下的新文件移动到应用包内的这个目录里
   • 在应用配置中指定迁移目录的路径，让Flask-Migrate能找到这些脚本：

     import os
     from flask import Flask
     from flask_sqlalchemy import SQLAlchemy
     from flask_migrate import Migrate
     
     app = Flask(__name__)
     app.config['SQLALCHEMY_DATABASE_URI'] = 'your-db-uri'
     # 指定迁移脚本所在的目录
     app.config['MIGRATIONS_DIR'] = os.path.join(os.path.dirname(__file__), 'migrations')
     
     db = SQLAlchemy(app)
     migrate = Migrate(app, db)
     

2. 打包时包含迁移脚本

   • 在setup.py（或pyproject.toml，如果你用Poetry/Setuptools）中，把应用包内的migrations目录添加到打包文件列表中。比如在setup.py里：

     from setuptools import setup, find_packages
     
     setup(
         name='your-flask-app',
         packages=find_packages(),
         package_data={
             'app': ['migrations/versions/*.py'],
         },
     )
     

3. 生产环境部署操作

   • 安装应用包后，直接执行flask db upgrade即可完成数据库升级。因为迁移脚本已经随包安装，Flask-Migrate会自动找到它们，无需手动复制migrations文件夹。
   • 如果是首次部署，执行flask db upgrade前可以先执行flask db stamp head，标记当前数据库为最新版本（避免因为空数据库导致的初始化问题）。

为什么不建议手动复制migrations文件夹？ #

手动同步migrations文件夹的最大问题是版本一致性难以保证：每次应用版本更新时，你都需要确保复制的migrations文件夹和当前应用版本的迁移脚本完全匹配。一旦出现遗漏或错配，执行upgrade时很可能会出现数据库结构不兼容的错误，甚至导致数据丢失，这在生产环境是非常危险的。

关于db.create_all()和数据库迁移的区别 #

你提到可以用db.create_all()替代迁移，但这只适用于首次部署且后续不会修改数据库结构的场景。两者的核心区别在于：

• db.create_all()：只能根据当前模型创建新表，无法处理已存在表的结构变更（比如新增字段、修改字段类型、添加索引等）。如果你的应用后续迭代需要修改数据库结构，db.create_all()不会对已有表做任何更新，导致应用代码和数据库结构不一致。
• 数据库迁移：会追踪每一次模型的变更，生成对应的SQL脚本，支持逐步升级数据库结构，还能回滚到之前的版本。这对于生产环境的应用迭代至关重要——它可以安全地修改数据库结构，同时保留已有数据，保证应用和数据库的一致性。

简单来说，db.create_all()是“一次性创建”，而迁移是“持续维护”，后者才是生产环境应用的正确选择。

内容的提问来源于stack exchange，提问作者Maksim Grinman