Flask-Migrate 官方文档 中文翻译

英文原文链接：http://flask-migrate.readthedocs.io/en/latest/
本人水平有限，不懂之处可参阅原文

---

Flask-Migrate是一个扩展，使用 Alembic 处理 Flask 程序的 SQLAlchemy 数据库迁移。数据库操作通过 Flask 命令行界面或 Flask-Script 扩展来提供。

安装

使用 pip 安装 Flask-Migrate ：pip install Flask-Migrate

示例

这是一个通过 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:///app.db'

db = SQLAlchemy(app)
migrate = Migrate(app, db)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(128))

使用上述程序，您可以使用以下命令来创建迁移存储库：

$ flask db init

这将向您的程序添加迁移文件夹。此文件夹的内容需要与其他源文件一起添加到版本控制中。

然后，您可以生成初始迁移：

$ flask db migrate

需要检查和编辑迁移脚本，因为 Alembic 当前未检测到您对模型所做的每项更改。特别是，Alembic 目前无法检测表名的更改，列名的更改或匿名限制。有关限制的详细摘要可在 Alembic自动生成文档 中找到。完成后，还需要将迁移脚本添加到版本控制中。

然后，您可以将迁移应用于数据库：

$ flask db upgrade

然后每次数据库模型更改时重复 migrate 和 upgrade 命令。

要在另一个系统中同步数据库，只需从源代码管理中刷新迁移文件夹并运行该 upgrade 命令。

要查看所有可用的命令，请运行以下命令：

$ flask db --help

请注意，必须在 FLASK_APP 环境变量中设置程序脚本，以使所有上述命令起作用，这是 flask 命令行脚本所要求的。

使用 Flask-Script

Flask-Migrate 还支持 Flask-Script 命令行界面。这是一个通过 Flask-Script 公开所有数据库迁移命令的示例应用程序：

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_script import Manager
from flask_migrate import Migrate, MigrateCommand

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///app.db'

db = SQLAlchemy(app)
migrate = Migrate(app, db)

manager = Manager(app)
manager.add_command('db', MigrateCommand)

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(128))

if __name__ == '__main__':
    manager.run()

假设上述脚本存储在一个名为 manage.py 的文件中，则可通过运行脚本来访问所有数据库迁移命令：

$ python manage.py db init
$ python manage.py db migrate
$ python manage.py db upgrade
$ python manage.py db --help

配置回调

有时，应用程序需要将自己的设置动态插入到 Alembic 配置中。configure 在读取配置之后，在使用之前，将调用使用回调修饰的函数。该函数可以修改配置对象，或者用另一个替换它。

@migrate.configure
def configure_alembic(config):
    # modify config object
    return config

可以简单地通过装饰多个函数来定义多个配置回调。调用多个回调的顺序是未确定的。

多数据库支持

Flask-Migrate 可以与 Flask-SQLAlchemy 的绑定（binds）功能集成 ，从而可以跟踪与应用程序关联的多个数据库的迁移。

要创建多个数据库迁移存储库，请将 --multidb 参数添加到该 init 命令：

$ flask db init --multidb

使用此命令，将设置迁移存储库以跟踪主数据库以及 SQLALCHEMY_BINDS 配置选项中定义的任何其他数据库上的迁移。

命令参考

lask-Migrate 公开了两个类，Migrate 和 MigrateCommand。Migrate 类包含扩展的所有功能。MigrateCommand类仅在希望通过 Flask-Script 扩展公开数据库迁移命令时才使用。

以下示例使用标准 Flask 命令行界面初始化扩展：

from flask_migrate import Migrate
migrate = Migrate(app, db)

Migrate 的两个参数是应用程序实例和 Flask-SQLAlchemy 数据库实例。该 Migrate 构造还需要额外的关键字参数，这些参数传递给 Alembic 的 EnvironmentContext.configure() 方法。作为所有 Flask 扩展的标准，Flask-Migrate 也可以使用该 init_app 方法进行初始化。

使用Flask-Script的命令行界面时，扩展名初始化如下：

from flask_migrate import Migrate, MigrateCommand
migrate = Migrate(app, db)
manager.add_command('db', MigrateCommand)

初始化扩展后，一个db组将被添加到命令行选项中，其中包含几个子命令。包括Flask 命令行界面中还是manage.py 在使用 Flask-Script 创建的脚本中。以下子命令的列表都是可用的：

• flask db –help
  显示可用命令的列表。
• flask db init [–multidb]
  初始化应用程序的迁移支持。可选项 --multidb 允许配置为 Flask-SQLAlchemy 绑定的多个数据库进行迁移。
• flask db revision [–message MESSAGE] [–autogenerate] [–sql] [–head HEAD] [–splice] [–branch-label BRANCH_LABEL] [–version-path VERSION_PATH] [–rev-id REV_ID]
  创建一个空的修订脚本。需要使用 upgrade 和 upgrade 更改手动编辑脚本。有关如何编写迁移脚本的说明，请参阅Alembic文档。可以包含可选的迁移消息。
• flask db migrate [–message MESSAGE] [–sql] [–head HEAD] [–splice] [–branch-label BRANCH_LABEL] [–version-path VERSION_PATH] [–rev-id REV_ID]
  相当于 revision --autogenerate。迁移脚本将填充自动检测到的更改。应该检查和编辑生成的脚本，因为不能自动检测所有类型的更改。此命令不会对数据库进行任何更改，只创建修订脚本。
• flask db edit
  使用$ EDITOR编辑修订脚本。
• flask db upgrade [–sql] [–tag TAG] [–x-arg ARG]
  升级数据库。如果没有修改，则返回 “head”。
• flask db downgrade [–sql] [–tag TAG] [–x-arg ARG]
  降级数据库。如果没有修改，则返回 -1。
• flask db stamp [–sql] [–tag TAG]
  将数据库中的版本设置为作为参数的版本，而不执行任何迁移。
• flask db current [–verbose]
  显示当前数据库的版本。
• flask db history [–rev-range REV_RANGE] [–verbose]
  显示迁移列表。如果没有给定范围，则显示整个历史。
• flask db show
  显示由给定标识表示的版本。
• flask db merge [–message MESSAGE] [–branch-label BRANCH_LABEL] [–rev-id REV_ID]
  将两个版本合并在一起。创建一个新的版本文件。
• flask db heads [–verbose] [–resolve-dependencies]
  在修订脚本目录中显示当前可用的 head。
• flask db branches [–verbose]
  显示当前分支点。

记录

• 所有命令都具有--directory DIRECTORY选项，该选项指向包含迁移脚本的目录。如果省略此参数，则使用的目录是 migrations。
• 默认目录也可以指定为 directory 参数给 Migrate 构造函数。
• --sql 选项存在于多个命令中来执行“脱机”模式迁移。需要执行的SQL语句不是执行数据库命令，而是打印到控制台。
• 这些命令的详细文档可以在Alembic’s command reference page找到。

API参考

Flask-Migrate 命令行界面公开的命令也可以通过从模块导入函数以编程方式访问 flask_migrate。可用的功能有：

• init(directory=’migrations’, multidb=False)
  初始化程序的迁移支持。
• revision(directory=’migrations’, message=None, autogenerate=False, sql=False, head=’head’, splice=False, branch_label=None, version_path=None, rev_id=None)
  创建一个空的修订脚本。
• migrate(directory=’migrations’, message=None, sql=False, head=’head’, splice=False, branch_label=None, version_path=None, rev_id=None)
  创建自动修订脚本。
• edit(directory=’migrations’, revision=’head’)
  使用$ EDITOR编辑修订脚本。
• merge(directory=’migrations’, revisions=”, message=None, branch_label=None, rev_id=None)
  合并两个修订版。创建新的迁移文件。
• upgrade(directory=’migrations’, revision=’head’, sql=False, tag=None)
  升级数据库。
• downgrade(directory=’migrations’, revision=’-1’, sql=False, tag=None)
  降级数据库。
• show(directory=’migrations’, revision=’head’)
  显示给定标识表示的修订版本。
• history(directory=’migrations’, rev_range=None, verbose=False)
  显示迁移列表。如果未给出范围，则显示整个历史记录。
• heads(directory=’migrations’, verbose=False, resolve_dependencies=False)
  在脚本目录中显示当前可用的头。
• branches(directory=’migrations’, verbose=False)
  显示当前分支点。
• current(directory=’migrations’, verbose=False, head_only=False)
  显示数据库的当前版本。
• stamp(directory=’migrations’, revision=’head’, sql=False, tag=None)
  将数据库中的版本设置为作为参数给出的版本，而不执行任何迁移。

注意：为了获得更好的脚本编写灵活性，您还可以直接使用 Alembic 的 API。