Alembic 简明教程

本文记录了Alembic的主要使用过程。

数据库版本化

通常我们会将我们的代码放入到某个VCS（版本控制系统）中，进行可追溯的版本管理。一个项目除了代码，通常还会有一个数据库，这个数据库可能会随着项目的演进发生变化，甚至需要可以回滚到过去的某个状态，于是一些工具将数据库的版本化也纳入了管理。

Alembic 是 Sqlalchemy 的作者实现的一个数据库版本化管理工具，它可以对基于Sqlalchemy的Model与数据库之间的历史关系进行版本化的维护。

Alembic

你可以通过 pip install alembic 直接安装，它需要三个依赖包，PIP会自动处理。

• SQLAlchemy 同作者的ORM工具
• Mako 同作者的模版工具
• MarkupSafe 转换Markup到HTML的组件

初始化

在你的项目根目录运行

alembic init YOUR_ALEMBIC_DIR

随后你的项目目录应该会新增一个alembic.ini文件以及一个YOUR_ALEMBIC_DIR目录，最好指定一个符合自己项目风格的命名。

接下来的操作都是围绕这个目录。

yourproject/    alembic.ini    YOUR_ALEMBIC_DIR/        env.py        README        script.py.mako        versions/b954651e_add_account.pyb1ae634e5cd_add_order_id.pyadcc9a56557_rename_username_field.py

• alembic.ini 提供了一些基本的配置
• env.py 每次执行Alembic都会加载这个模块，主要提供项目Sqlalchemy Model 的连接
• script.py.mako 迁移脚本生成模版
• versions 存放生成的迁移脚本目录

除了基本的Alembic项目之外，你还可以指定几个特殊的项目模版。

$ alembic list_templatesAvailable templates:generic - Generic single-database configuration.multidb - Rudimentary multi-database configuration.pylons - Configuration that reads from a Pylons project environment.Templates are used via the 'init' command, e.g.:  alembic init --template pylons ./scripts

你需要编辑alembic.ini文件去指定Alembic的数据库连接。

# template used to generate migration files# file_template = %%(rev)s_%%(slug)s# set to 'true' to run the environment during# the 'revision' command, regardless of auto generate# revision_environment = falsesqlalchemy.url = driver://user:pass@localhost/dbname# Logging configuration[loggers]keys = root,sqlalchemy,alembic

版本

首先创建一个基本数据库版本，你当然可以从已有的数据库出发。

$ alembic revision -m "create account table"Generating /path/to/yourproject/YOUR_ALEMBIC_DIR/versions/1975ea83b712_create_account_table.py...done

生成的版本文件类似于：

"""create account tableRevision ID: 1975ea83b712Revises: NoneCreate Date: 2011-11-08 11:40:27.089406"""# revision identifiers, used by Alembic.revision = '1975ea83b712'down_revision = Nonefrom alembic import opimport sqlalchemy as sadef upgrade():    passdef downgrade():    pass

其中 revision = '1975ea83b712'和down_revision = None指定了这个reversion的当前版本号，以及父版本号，就是通过这个进行追溯。

然后我们修改upgrade和downgrade进行实际的升降级操作。通过易用的API，我们只需要对op和sa对象进行操作即可。

def upgrade():    op.create_table(        'account',        sa.Column('id', sa.Integer, primary_key=True),        sa.Column('name', sa.String(50), nullable=False),        sa.Column('description', sa.Unicode(200)),    )def downgrade():    op.drop_table('account')

具体op所支持的操作请看操作API引用。

升级，降级

然后我们更新好最新的版本。

$ alembic upgrade headINFO [alembic.context] Context class PostgresqlContext.INFO [alembic.context] Will assume transactional DDL.INFO [alembic.context] Running upgrade None -> 1975ea83b712

一般我们需要指定版本号进行升级，但是对于最新以及最初版本有两个额外的别名，head指最新版本，base指最初的版本。

降级也很简单，只要upgrade以及downgrade实现足够鲁棒。

$ alembic downgrade baseINFO [alembic.context] Context class PostgresqlContext.INFO [alembic.context] Will assume transactional DDL.INFO [alembic.context] Running downgrade 1975ea83b712 -> None

自动生成迁移脚本

Alembic 不仅仅能够维护数据库历史版本，而且带来这个新奇的特性，自动生成迁移脚本。

通常我们进行编码时候，在确定需求后，通常需要对数据模型进行变化。
不要担心，只要不是出于技术实现问题，诸如长度过少数据类型应用错等。而是因为业务的变更而导致的数据模型变更完全可以理解。"程序=算法+数据结构“，业务逻辑发生了变化，实现算法、数据结构必然发生变化，不要贪图抽象隔离设计之类云云，这类除了使得程序复杂度增加之外，很难保证未来预期是否如之前所设计的工作量完全可以避免。

口头商量，确定方案，然后开始打算修改，除了设计稿之外，往往最先实现的是ORM中我们的实体类，因为他们简单易懂。
在此例中我因为需要给用户添加微博OAuth2.0的绑定，所以新增了两个字段：

class User(Base):    # …. origin others setting    weibo_token = Column(String(64), nullable=True)    weibo_expires = Column(DateTime, nullable=True)

这个时候直接运行程序必然会失败，因为映射关系已经被打乱了，我们需要重建这个关系。

配置YOUR_ALEMBIC_DIR/env.py文件，修改target_metadata = None为你的元信息对象。
这里我就直接导入了，但是在导入的过程中由于目录问题，所以一个额外的Hack。

# Hack for model import import osimport syssys.path.insert(0, os.path.realpath("."))# add your model's MetaData object here# for 'autogenerate' support# from myapp import my model# target_metadata = Nonefrom model import Basetarget_metadata = Base.metadata

见证奇迹的时刻：

$ alembic revision --autogenerate -m "add weibo token fields for user"INFO [alembic.migration] Context impl MySQLImpl.INFO [alembic.migration] Will assume non-transactional DDL.INFO [alembic.autogenerate] Detected added column 'user.weibo_expires'INFO [alembic.autogenerate] Detected added column 'user.weibo_token'  Generating migrate/versions/3117ba3f1f1f_add_weibo_token_expires_for_user.py...done

剩下的就可以按照正常的Alembic操作进行升降级了，是不是把烦人的数据库结构变更问题解决了？当然，这些问题可能在其他生态圈中根本不是问题（Java/Hibernate，Ruby/RoR）。 别忘了将这些变更提交到VCS中，他们可是非常值得你去维护。

自动迁移脚本生成功能实现

你可以在Alembic的源码的autogenerate.py模块中找到，一共近七百行。
程序流程如下： 

写得挺流水的，没有抽象，至少_compare_*都只是对于两个集合差集的提取，以及交集的迭代，这部分是可以很容易抽象出来的。
得到差异后，再对差异数据进行“渲染”，既有原地执行，也有渲染输出为Sql，还能对升降级进行不同的输出。

Sqlalchemy-migrate

Sqlalchemy-migrate 借鉴RoR的思路，对数据库进行版本化管理。但是只是提供了基本的功能，对于多个数据库引擎的差异暴露给了开发者，不易用。
命令行的控制细节也挺多了，和Sqlalchemy似乎不是一个思路。 这里就有一个StackOverflow的用户在抱怨难以上手。

Reference

• Alembic
• Alembic - Tutorial