英文原文链接: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。