Alembic 是一个处理数据库更改的工具,它利用 SQLAlchemy 来实现形成迁移。因为 SQLAlchemy 只会在我们使用时根据 metadata create_all 方法来创建缺少的表 ,它不会根据我们对代码的修改而更新数据库表中的列。它也不会自动帮助我们删除表。 Alembic 提供了一种更新 / 删除表,更改列名和添加新约束的方法。因为 Alembic 使用 SQLAlchemy 执行迁移,它们可用于各种后端数据库。

安装

pip install alembic

使用

初始化,使用如下命令会创建环境到 migrations 文件夹下,通常情况下使用 migrations 文件夹来存储 alembic 环境,如果想使用别的名字,相应替换为别的名字即可。注意下面命令中的 migrations 将会是存储所有迁移脚本的目录名字

alembic init migrations

初始化过程会创建迁移环境和 alembic.ini 文件。创建成功后可以看到如下结构:

alembic
├── README
├── env.py
├── script.py.mako
└── versions
alembic.ini

在这个环境中可以找到 env.pyscript.py.mako 模板还有 versions 文件夹。versions/ 目录会存储之后的所有迁移脚本。 env.py 文件用来定义和实例化 SQLAlchemy 引擎,连接引擎并进行事务,保证当 Alembic 执行命令时被合理的调用。 script.py.mako 模板在创建迁移时被使用,他定义了迁移的基本模板。

配置

init 生成之后需要修改 env.py 如下的两个配置,才能生效。改变 sqlalchemy.url 值,配置数据库连接。

sqlalchemy.url = driver://user:pass@localhost/dbname

为了让 Alembic 追踪到数据模型的变化,需要将 target_metadata 赋值为数据库的 metadata

from flask import current_app
config.set_main_option('sqlalchemy.url',
                       current_app.config.get('SQLALCHEMY_DATABASE_URI'))
target_metadata = current_app.extensions['migrate'].db.metadata

自动创建版本

使用alembic revision -m "comment" 来创建数据库版本。命令会产生一个数据库迁移脚本。

更新数据库

升级数据库使用 alembic upgrade,降级使用 alembic downgrade,更新到最新版则使用 alembic upgrade head

查看数据库就会发现 alembic 会自动产生一个 alembic_version 的表,只有一个字段和值 version_num,记录当前数据库版本。

reference

  • 《Essential SQLAlchemy 2nd Edition 2015》