Glance 扩展/收缩迁移与 Alembic¶

https://blueprints.launchpad.net/glance/+spec/alembic-migrations

本文档概述了将 Glance 数据库迁移从基于 SQLAlchemy 的脚本移植到 Alembic 的动机和实现细节。

问题描述¶

目前，Glance 中的数据库迁移是使用 SQLAlchemy-migrate 脚本实现的。这种方法使得设计滚动升级的迁移 ([1] & [2]) 变得非常困难。 expand 和 contract 迁移必须严格按顺序创建，所有收缩迁移必须在所有扩展迁移之后。这给迁移的顺序施加了不必要的限制，并且在单个周期中引入多个模式更改时，很容易出错。本质上，使用 SQLAlchemy-migrate 约束 expand 和 contract 迁移以原子方式运行，并且不易于在滚动升级期间需要时将它们分成阶段。

提议的变更¶

我们建议将迁移流程移植到 Alembic [3]。这种更改有许多好处。 Alembic 允许使用指定的分支名称（例如 expand 和 contract）标记各种迁移脚本，这使得更容易将这两种类型的更改分组并分别运行它们。

另一个好处是 Alembic 迁移以链表的方式链接。这通过在每个迁移脚本中显式指定修订依赖项来实现。这将允许开发人员摆脱对迁移脚本的数字顺序的依赖，并消除对类似以下占位符迁移的需求：023_placeholder。为了便于此功能，建议为迁移脚本提出新的命名约定

<周期>_<分支标签><##>_<简短描述>.py

例如：ocata_expand01_add_visibility_column.py

此外，Alembic 支持使用 SQLAlchemy 的 ORM 自动生成迁移脚本。在未来，鼓励开发人员利用此功能，以最大程度地减少与底层 DBMS 的交互，并依赖 Python 代码来定义新的模式。

备选方案¶

最佳替代方案是继续使用 SQLAlchemy-migrate 脚本。此方法的缺点在问题描述部分中概述。

数据模型影响¶

无

REST API 影响¶

无

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

预计现有的离线迁移流程的性能不会受到显著影响。

其他部署者影响¶

glance-manage 命令行工具的 API 保持向后兼容。但是，操作员会注意到 db_version 命令返回一个命名的 head 修订版本，而不是一个数字。此更改将记录在案。此外，需要让操作员了解 glance-manage 命令行工具中的新 db_expand、db_contract 和 db_data_migrate API。请参阅下面的文档影响部分。

开发人员影响¶

今后，每当实施数据库模式更改时，开发人员都需要创建符合既定命名约定的 Alembic 迁移脚本，并确保将每个新修订链接到适当的 down 修订版本。

实现¶

在 glance/db/sqlalchemy 下添加了一个新的 alembic_migrations 文件夹。此文件夹将包含实现基于 Alembic 的迁移所需的所有代码，包括

Alembic 配置和环境文件。有关详细信息，请参见：迁移环境
用于创建初始 Glance DB 模式的辅助脚本
versions 目录，包含在不同发布周期中添加的迁移脚本

负责人¶

主要负责人: hemanthm abashmak

工作项¶

实施 Alembic 迁移基础设施和现有数据库迁移（至 Newton）的脚本。
为新的 Ocata 功能引入 expand/contract 迁移 [4]。
更新 glance-manage 工具以利用 Alembic 进行 db_sync 和相关命令。添加 db_expand 和 db_contract 命令以准备滚动升级。

依赖项¶

将添加一个新的 Python 模块到 Glance 的需求列表中
- alembic - 版本 0.8.7 或更高版本

测试¶

现有和新的数据库迁移测试（单元和功能）将被移植和/或添加，以测试更新的 glance-manage 工具并测试基于 Alembic 的迁移脚本的完整性。

文档影响¶

将需要记录迁移到 Alembic 导致的新数据库版本名称，以便开发人员了解 db_version 输出的更改。

此外，作为启用 assert:supports-zero-downtime -upgrade 标签 [5] 的一部分，此更改将引入并实施 glance-manage 工具的新 API 方法：db_expand、db_contract 和 db_data_migrate。需要对这些进行全面记录，并在 glance-manage 参考以及升级指南中解释其用法。建议等到 Glance 能够断言零停机升级标签后再添加新命令的文档。

Glance 扩展/收缩迁移与 Alembic